---
title: "Association"
language: "en"
type: "Symbol"
summary: "Association[key1 -> val1, key2 -> val2, ...] or <|key1 -> val1, key2 -> val2, ...|> represents an association between keys and values."
keywords: 
- collection
- named parts
canonical_url: "https://reference.wolfram.com/language/ref/Association.html"
source: "Wolfram Language Documentation"
related_guides: 
  - 
    title: "Associations"
    link: "https://reference.wolfram.com/language/guide/Associations.en.md"
  - 
    title: "Computation with Structured Datasets"
    link: "https://reference.wolfram.com/language/guide/ComputationWithStructuredDatasets.en.md"
  - 
    title: "Automated Reports"
    link: "https://reference.wolfram.com/language/guide/AutomatedReports.en.md"
  - 
    title: "WDF (Wolfram Data Framework)"
    link: "https://reference.wolfram.com/language/guide/WDFWolframDataFramework.en.md"
  - 
    title: "Language Overview"
    link: "https://reference.wolfram.com/language/guide/LanguageOverview.en.md"
  - 
    title: "Setting Up Input Interpreters"
    link: "https://reference.wolfram.com/language/guide/InterpretingStrings.en.md"
  - 
    title: "Wolfram Language Syntax Characters"
    link: "https://reference.wolfram.com/language/guide/WolframLanguageSyntaxCharacters.en.md"
  - 
    title: "Expressions"
    link: "https://reference.wolfram.com/language/guide/Expressions.en.md"
  - 
    title: "Wolfram Language Syntax"
    link: "https://reference.wolfram.com/language/guide/Syntax.en.md"
  - 
    title: "Database Connectivity"
    link: "https://reference.wolfram.com/language/guide/DatabaseConnectivity.en.md"
  - 
    title: "Scientific Data Analysis"
    link: "https://reference.wolfram.com/language/guide/ScientificDataAnalysis.en.md"
  - 
    title: "Wolfram Data Repository"
    link: "https://reference.wolfram.com/language/guide/WolframDataRepository.en.md"
related_workflows: 
  - 
    title: "Import Data"
    link: "https://reference.wolfram.com/language/workflow/ImportData.en.md"
  - 
    title: "Import Tabular Data as a Computable Dataset"
    link: "https://reference.wolfram.com/language/workflow/ImportTabularDataAsAComputableDataset.en.md"
  - 
    title: "Select Elements in a Dataset"
    link: "https://reference.wolfram.com/language/workflow/SelectElementsInADataset.en.md"
  - 
    title: "Extract Columns in a Dataset"
    link: "https://reference.wolfram.com/language/workflow/ExtractColumnsInADataset.en.md"
  - 
    title: "Make a Grid of Output Data"
    link: "https://reference.wolfram.com/language/workflow/MakeAGridOfOutputData.en.md"
related_functions: 
  - 
    title: "List"
    link: "https://reference.wolfram.com/language/ref/List.en.md"
  - 
    title: "Tabular"
    link: "https://reference.wolfram.com/language/ref/Tabular.en.md"
  - 
    title: "Dataset"
    link: "https://reference.wolfram.com/language/ref/Dataset.en.md"
  - 
    title: "Normal"
    link: "https://reference.wolfram.com/language/ref/Normal.en.md"
  - 
    title: "AssociationQ"
    link: "https://reference.wolfram.com/language/ref/AssociationQ.en.md"
  - 
    title: "Lookup"
    link: "https://reference.wolfram.com/language/ref/Lookup.en.md"
  - 
    title: "KeyExistsQ"
    link: "https://reference.wolfram.com/language/ref/KeyExistsQ.en.md"
  - 
    title: "Keys"
    link: "https://reference.wolfram.com/language/ref/Keys.en.md"
  - 
    title: "Values"
    link: "https://reference.wolfram.com/language/ref/Values.en.md"
  - 
    title: "KeyValuePattern"
    link: "https://reference.wolfram.com/language/ref/KeyValuePattern.en.md"
  - 
    title: "SparseArray"
    link: "https://reference.wolfram.com/language/ref/SparseArray.en.md"
  - 
    title: "CompoundElement"
    link: "https://reference.wolfram.com/language/ref/CompoundElement.en.md"
  - 
    title: "DataStructure"
    link: "https://reference.wolfram.com/language/ref/DataStructure.en.md"
  - 
    title: "Tree"
    link: "https://reference.wolfram.com/language/ref/Tree.en.md"
---
# Association ( <|...|> )

Association[key1 -> val1, key2 -> val2, …] or <|key1 -> val1, key2 -> val2, …|> represents an association between keys and values.

## Details

* The value associated with a given key ``k`` in the association ``assoc`` can be extracted using ``assoc[k]``. »

* An association acts like a symbolically indexed list. The value associated with a given key ``k`` can be extracted using the part specification ``Key[k]``. If ``k`` is a string, ``Key`` can be omitted. »

* If ``key`` is not present in ``assoc``, ``assoc[key]`` yields ``Missing["KeyAbsent", key]``. »

* If ``assoc`` is a symbol whose value is an association, ``assoc[key] = val`` can be used to associate or reset the association of ``key`` with ``val``. »

* Typical list operations (such as ``Map``, ``Select`` and ``Sort``) apply to the values in an association, leaving the keys unchanged. »

* ``Association[{key1 -> val1, …}]`` gives ``<|key1 -> val1, …|>``. »

* If there are multiple elements with the same key, all but the last of these elements are dropped. ``Merge`` yields instead a list of values for repeated keys.

* Associations can be input using the characters [`\[LeftAssociation]`](https://reference.wolfram.com/language/ref/character/LeftAssociation.en.md) and [`\[RightAssociation]`](https://reference.wolfram.com/language/ref/character/RightAssociation.en.md). These can be entered with esc <\| esc and esc \|> esc, respectively.

* ``Normal`` converts an ``Association`` object to a list of rules. »

* ``KeyValuePattern`` can be used to represent a pattern for associations that include particular elements. »

## Examples (32)

### Basic Examples (4)

An association in which key ``a`` is associated with value ``x``, key ``b`` with value ``y``, etc.:

```wl
In[1]:= <|a -> x, b -> y, c -> z|>

Out[1]= <|a -> x, b -> y, c -> z|>
```

Extract the value associated with key ``b`` :

```wl
In[2]:= %[b]

Out[2]= y
```

---

Convert a list of rules to an association:

```wl
In[1]:= Association[{a -> x, b -> y, c -> z}]

Out[1]= <|a -> x, b -> y, c -> z|>
```

---

Associations can be modified by resetting values:

```wl
In[1]:= assoc = <|a -> x, b -> y, c -> z|>

Out[1]= <|a -> x, b -> y, c -> z|>

In[2]:= assoc[b] = w

Out[2]= w
```

The key ``b`` now has value ``w`` rather than ``y`` :

```wl
In[3]:= assoc

Out[3]= <|a -> x, b -> w, c -> z|>
```

---

Using delayed rules prevents the values from being evaluated during association construction:

```wl
In[1]:= <|a -> 1 + 1, b -> 2 + 2, c :> 3 + 3, d :> 4 + 4|>

Out[1]= <|a -> 2, b -> 4, c :> 3 + 3, d :> 4 + 4|>
```

The values are evaluated when extracted:

```wl
In[2]:= %[c]

Out[2]= 6
```

### Scope (17)

#### Construction and Extraction (9)

Associations can have arbitrary expressions as keys, including associations:

```wl
In[1]:= Keys[<|{2, 3} -> x, RGBColor[0.95, 0.43, 0.96] -> y, <|a -> 1, b -> 2|> -> z|>]

Out[1]= {{2, 3}, RGBColor[0.95, 0.43, 0.96], <|a -> 1, b -> 2|>}
```

---

Append to an association:

```wl
In[1]:= Append[<|a -> x, b -> y, c -> z|>, d -> w]

Out[1]= <|a -> x, b -> y, c -> z, d -> w|>
```

---

Associations work with any number of elements:

```wl
In[1]:= assoc = Association[Table[i -> i ^ 2, {i, 10000}]];
```

Extracting values from an association is highly efficient:

```wl
In[2]:= assoc[10000]//EchoTiming

⌚ 2.`*^-6

Out[2]= 100000000
```

---

Missing elements are represented by ``Missing`` :

```wl
In[1]:= <|a -> x, b -> y, c -> z|>[d]

Out[1]= Missing["KeyAbsent", d]
```

``Lookup`` allows a default value to be given:

```wl
In[2]:= Lookup[<|a -> x, b -> y, c -> z|>, d, q]

Out[2]= q
```

---

Extract a value from an association using ``Part`` :

```wl
In[1]:=
assoc = <|a -> x, b -> {y, z}|>;
assoc[[Key[b]]]

Out[1]= {y, z}
```

Extract a portion of the value:

```wl
In[2]:= assoc[[Key[b], 1]]

Out[2]= y
```

The ``Key[k]`` part specification works at any level whose value is an association:

```wl
In[3]:= {5, 7, assoc}[[3, Key[b], 2]]

Out[3]= z
```

---

Extract the third value in an association:

```wl
In[1]:=
assoc = <|3 -> a, 1 -> b, 2 -> c|>;
assoc[[3]]

Out[1]= c
```

Extract the value associated with the key ``3`` :

```wl
In[2]:= assoc[[Key[3]]]

Out[2]= a
```

---

Obtain the sub-association consisting of the second and third parts of an association:

```wl
In[1]:=
assoc = <|3 -> a, 1 -> b, 2 -> c|>;
assoc[[{2, 3}]]

Out[1]= <|1 -> b, 2 -> c|>
```

Use the keys ``2`` and ``3`` instead:

```wl
In[2]:= assoc[[{Key[2], Key[3]}]]

Out[2]= <|2 -> c, 3 -> a|>
```

Extract the value associated with the key ``{2, 3}`` :

```wl
In[3]:= assoc[[Key[{2, 3}]]]

Out[3]= Missing["KeyAbsent", Key[{2, 3}]]
```

---

Extract a value using ``Extract`` :

```wl
In[1]:=
assoc = <|a -> 1 + 1, b -> 2 + 2, c :> 3 + 3, d :> 4 + 4|>;
Extract[assoc, Key[c]]

Out[1]= 6
```

Obtain the value without letting it evaluate:

```wl
In[2]:=
assoc = <|a -> 1 + 1, b -> 2 + 2, c :> 3 + 3, d :> 4 + 4|>;
Extract[assoc, Key[c], Hold]

Out[2]= Hold[3 + 3]
```

---

Separate an association into a list of keys and a list of values:

```wl
In[1]:= Comap[{Keys, Values}, <|a -> 1, b -> 2, c -> 3|>]

Out[1]= {{a, b, c}, {1, 2, 3}}
```

Convert it to a list of ordered pairs:

```wl
In[2]:= Transpose[%]

Out[2]= {{a, 1}, {b, 2}, {c, 3}}
```

#### Pattern-Matching Operations (8)

Associations can be used for pattern matching:

```wl
In[1]:= MatchQ[<|a -> 1|>, <|_ -> _|>]

Out[1]= True

In[2]:= Replace[<|a -> 1|>, <|a -> x_|> -> x]

Out[2]= 1
```

---

Extract key and value from an association:

```wl
In[1]:= <|1 -> 2|> /. <|a_ -> b_|> :> {a, b}

Out[1]= {1, 2}
```

---

Replace arguments of a function:

```wl
In[1]:= f[<|1 -> 2, 3 -> 4|>] /. f[<|a_ -> b_, ___|>] :> f[a, b]

Out[1]= f[1, 2]
```

---

Pick the rule with the specific key:

```wl
In[1]:= <|1 -> 2, 2 -> 3, 3 -> 4, 5 -> 6|> /. <|___, 3 -> b_, ___|> :> f[b]

Out[1]= f[4]
```

---

Filter associations with length ``2`` only:

```wl
In[1]:= Cases[{<|1 -> x|>, <|1 -> x, 2 -> y|>, <|1 -> x, 2 -> y, 3 -> z|>}, <|_, _|>]

Out[1]= {<|1 -> x, 2 -> y|>}
```

---

Define a function using an association as an argument:

```wl
In[1]:= g[<|k_ -> v_|>] := v

In[2]:= g[<|1 -> 2|>]

Out[2]= 2
```

Use nested associations as a function argument:

```wl
In[3]:= h[<|k_ -> <|k2_ -> v2_|>|>] := {k, k2, v2}

In[4]:= h[<|1 -> <|2 -> 3|>|>]

Out[4]= {1, 2, 3}
```

---

``KeyValuePattern`` lets you match any element in an association:

```wl
In[1]:= MatchQ[<|a -> 1, b -> 2, c -> 3|>, KeyValuePattern[b -> 2]]

Out[1]= True
```

---

``KeyValuePattern`` matches elements that appear anywhere in an association:

```wl
In[1]:= Replace[<|a -> 1, b -> 2, c -> 3|>, KeyValuePattern[{a -> x_, c -> y_}] :> {x, y}]

Out[1]= {1, 3}
```

### Properties & Relations (9)

Keys are "transparent" for typical list operations:

```wl
In[1]:= Map[f, <|a -> 4, b -> 2, c -> 1, d -> 5|>]

Out[1]= <|a -> f[4], b -> f[2], c -> f[1], d -> f[5]|>

In[2]:= Sort[<|a -> 4, b -> 2, c -> 1, d -> 5|>]

Out[2]= <|c -> 1, b -> 2, a -> 4, d -> 5|>

In[3]:= Select[<|a -> 4, b -> 2, c -> 1, d -> 5|>, # > 3&]

Out[3]= <|a -> 4, d -> 5|>

In[4]:= Total[<|a -> 4, b -> 2, c -> 1, d -> 5|>]

Out[4]= 12
```

---

``Values`` extracts values from an association:

```wl
In[1]:= Values[<|a -> x, b -> y, c -> z|>]

Out[1]= {x, y, z}
```

``Keys`` extracts keys from an association:

```wl
In[2]:= Keys[<|a -> x, b -> y, c -> z|>]

Out[2]= {a, b, c}
```

---

``Normal`` turns an association into a list of rules:

```wl
In[1]:= Normal[<|a -> x, b -> y, c -> z|>]

Out[1]= {a -> x, b -> y, c -> z}
```

---

``Position`` gives keys in an association:

```wl
In[1]:= Position[<|a -> 4, b -> 2, c -> 1, d -> 5|>, 2]

Out[1]= {{Key[b]}}
```

---

Values in associations can be extracted like parts:

```wl
In[1]:= <|a -> x, b -> y, c -> z|>[[Key[b]]]

Out[1]= y
```

If the key in an association is a string, no explicit ``Key`` is needed to extract it as a part:

```wl
In[2]:= <|"a" -> x, "b" -> y, "c" -> z|>[["b"]]

Out[2]= y
```

---

Numerical part specifications work structurally on associations:

```wl
In[1]:= <|a -> x, b -> y, c -> z|>[[2]]

Out[1]= y
```

---

Associations keep only the last instance of repeated keys:

```wl
In[1]:= <|a -> x, a -> xp, b -> y, c -> z, c -> zp|>

Out[1]= <|a -> xp, b -> y, c -> zp|>

In[2]:= Join[<|a -> x, b -> y, c -> z|>, <|a -> xp, c -> zp|>]

Out[2]= <|a -> xp, b -> y, c -> zp|>
```

---

When an association is modified, a new copy is created:

```wl
In[1]:= v = w = <|a -> 1, b -> 2|>

Out[1]= <|a -> 1, b -> 2|>

In[2]:= v[a] = 3

Out[2]= 3
```

``v`` is modified; ``w`` is unchanged:

```wl
In[3]:= {v, w}

Out[3]= {<|a -> 3, b -> 2|>, <|a -> 1, b -> 2|>}
```

---

Associations can have zero length:

```wl
In[1]:= <||>

Out[1]= <||>

In[2]:= Length[%]

Out[2]= 0
```

### Possible Issues (2)

``Association`` counts as one level, not two, in structural functions:

```wl
In[1]:= Level[<|a -> x, b -> y|>, {1}]

Out[1]= {x, y}

In[2]:= Depth[<|a -> x, b -> y|>]

Out[2]= 2
```

Lists of rules are two levels:

```wl
In[3]:= Level[{a -> x, b -> y}, {1}]

Out[3]= {a -> x, b -> y}

In[4]:= Depth[{a -> x, b -> y}]

Out[4]= 3
```

---

Replacing the head of an association loses keys:

```wl
In[1]:= ReplacePart[<|"x" -> 1, "y" -> 2|>, {0} -> List]

Out[1]= {1, 2}
```

Extract rules from an association:

```wl
In[2]:= Normal[<|"x" -> 1, "y" -> 2|>]

Out[2]= {"x" -> 1, "y" -> 2}
```

## See Also

* [`List`](https://reference.wolfram.com/language/ref/List.en.md)
* [`Tabular`](https://reference.wolfram.com/language/ref/Tabular.en.md)
* [`Dataset`](https://reference.wolfram.com/language/ref/Dataset.en.md)
* [`Normal`](https://reference.wolfram.com/language/ref/Normal.en.md)
* [`AssociationQ`](https://reference.wolfram.com/language/ref/AssociationQ.en.md)
* [`Lookup`](https://reference.wolfram.com/language/ref/Lookup.en.md)
* [`KeyExistsQ`](https://reference.wolfram.com/language/ref/KeyExistsQ.en.md)
* [`Keys`](https://reference.wolfram.com/language/ref/Keys.en.md)
* [`Values`](https://reference.wolfram.com/language/ref/Values.en.md)
* [`KeyValuePattern`](https://reference.wolfram.com/language/ref/KeyValuePattern.en.md)
* [`SparseArray`](https://reference.wolfram.com/language/ref/SparseArray.en.md)
* [`CompoundElement`](https://reference.wolfram.com/language/ref/CompoundElement.en.md)
* [`DataStructure`](https://reference.wolfram.com/language/ref/DataStructure.en.md)
* [`Tree`](https://reference.wolfram.com/language/ref/Tree.en.md)

## Related Guides

* [`Associations`](https://reference.wolfram.com/language/guide/Associations.en.md)
* [Computation with Structured Datasets](https://reference.wolfram.com/language/guide/ComputationWithStructuredDatasets.en.md)
* [Automated Reports](https://reference.wolfram.com/language/guide/AutomatedReports.en.md)
* [WDF (Wolfram Data Framework)](https://reference.wolfram.com/language/guide/WDFWolframDataFramework.en.md)
* [Language Overview](https://reference.wolfram.com/language/guide/LanguageOverview.en.md)
* [Setting Up Input Interpreters](https://reference.wolfram.com/language/guide/InterpretingStrings.en.md)
* [Wolfram Language Syntax Characters](https://reference.wolfram.com/language/guide/WolframLanguageSyntaxCharacters.en.md)
* [`Expressions`](https://reference.wolfram.com/language/guide/Expressions.en.md)
* [Wolfram Language Syntax](https://reference.wolfram.com/language/guide/Syntax.en.md)
* [Database Connectivity](https://reference.wolfram.com/language/guide/DatabaseConnectivity.en.md)
* [Scientific Data Analysis](https://reference.wolfram.com/language/guide/ScientificDataAnalysis.en.md)
* [Wolfram Data Repository](https://reference.wolfram.com/language/guide/WolframDataRepository.en.md)

## Related Workflows

* [Import Data](https://reference.wolfram.com/language/workflow/ImportData.en.md)
* [Import Tabular Data as a Computable Dataset](https://reference.wolfram.com/language/workflow/ImportTabularDataAsAComputableDataset.en.md)
* [Select Elements in a Dataset](https://reference.wolfram.com/language/workflow/SelectElementsInADataset.en.md)
* [Extract Columns in a Dataset](https://reference.wolfram.com/language/workflow/ExtractColumnsInADataset.en.md)
* [Make a Grid of Output Data](https://reference.wolfram.com/language/workflow/MakeAGridOfOutputData.en.md)

## Related Links

* [Fast Introduction for Programmers: Associations](http://www.wolfram.com/language/fast-introduction-for-programmers/associations/)
* [An Elementary Introduction to the Wolfram Language: Associations](https://www.wolfram.com/language/elementary-introduction/34-associations.html)

## History

* [Introduced in 2014 (10.0)](https://reference.wolfram.com/language/guide/SummaryOfNewFeaturesIn100.en.md) \| [Updated in 2016 (10.4)](https://reference.wolfram.com/language/guide/SummaryOfNewFeaturesIn104.en.md)