# Dictionary data type
> Version: _Available or changed with runtime version 1.0._
Represents an unordered collection of keys and values. The Dictionary data type is optimized for fast lookup of values.
## Instance methods
The following methods are available on instances of the Dictionary data type.
Method name|Description
Add(TKey, TValue)<dictionary-add-method>|Adds the specified key and value to the dictionary.
ContainsKey(TKey)<dictionary-containskey-method>|Determines whether the Dictionary contains the specified key.
dictionary-count-method|Gets the number of key/value pairs contained in the Dictionary.
Get(TKey, var TValue)<dictionary-get-tkey-tvalue-method>|Gets the value associated with the specified key.
dictionary-get-tkey-method|Gets the value associated with the specified key.
dictionary-keys-method|Gets a collection containing the keys in the Dictionary.
Remove(TKey)<dictionary-remove-method>|Removes the value with the specified key from the Dictionary.
dictionary-set-tkey-tvalue-method|Sets the value associated with the specified key.
Set(TKey, TValue, var TValue)<dictionary-set-tkey-tvalue-tvalue-method>|Sets the value associated with the specified key.
dictionary-values-method|Gets a collection containing the values in the Dictionary.
## Remarks
Each addition to the dictionary consists of a value, and its associated key. Every key in a Dictionary must be unique. A key cannot be null, but a value can be, only when the value type is a reference type.
A Dictionary is a reference type, so assigning an instance of a dictionary to another variable or passing as a method parameter by value (for example without var), creates a second variable that reads/writes the same dictionary. It does not create a new dictionary.
To create a new dictionary that contains the same values as the original dictionary, you can do the following to perform a shallow copy:
```al
trigger OnRun()
    var
        dict1: Dictionary of [Integer, Integer];
        dict2: Dictionary of [Integer, Integer];
        dictionaryKey: Integer;
    begin
        // ...
        foreach dictionaryKey in dict1.Keys() do
            dict2.Add(dictionaryKey, dict1.Get(dictionaryKey));
    end;
```
The Dictionary data type does not support holding instantiated records. For this purpose, use temporary tables.
> WARNING
> Previously in C/AL, one would have typically used an in-memory temporary table to create a key-value data structure, as shown in the code below. In AL you use the Dictionary Data Type instead.
```
> IF KeyCacheRec.Get(‘Some Value’)​ THEN​
>     Complete data stack execution;
> ```

## Example

In the following example, the variable `counter` represents the Dictionary data type to store a value representing the number of occurrences for each character in the `customerName`. Using the `Get` method, you get the number of occurrences for the character at position `i`. If `i` returns **false**, it means there is no value associated with that character, so you add the value 1. If `i` returns **true**, it means the value already exists, so you add `c + 1` to the value. The `Add` method adds the {key:value} pair to the Dictionary.

```al
procedure CountCharactersInCustomerName(customerName: Text; counter: Dictionary of [Char, Integer])
var
    i : Integer;
    c : Integer;
begin
    for i := 1 to StrLen(customerName) do
        if counter.Get(customerName[i], c) then
            counter.Set(customerName[i], c + 1)
        else
            counter.Add(customerName[i], 1);
end;

```
## Related information
Get Started with AL<../../devenv-get-started>
Developing Extensions<../../devenv-dev-overview>
../list/list-data-type

Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/dictionary/dictionary-data-type, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact. https://jonas-paprotka.de/docs/dev-itpro/developer/methods-auto/dictionary/dictionary-data-type/
