Skip to content

Commit 5853711

Browse files
authored
Update map fields (#304)
1 parent fe34e61 commit 5853711

File tree

1 file changed

+64
-15
lines changed

1 file changed

+64
-15
lines changed

apl/data-types/map-fields.mdx

Lines changed: 64 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ import ReplaceDatasetToken from "/snippets/replace-dataset-token.mdx"
99

1010
Map fields are a special type of field that can hold a collection of nested key-value pairs within a single field. You can think of the content of a map field as a JSON object.
1111

12-
Axiom automatically creates map fields in datasets that use [OpenTelemetry](/send-data/opentelemetry) and you can create them yourself.
12+
Axiom automatically creates map fields in datasets that use [OpenTelemetry](/send-data/opentelemetry) and you can create map fields yourself in any dataset.
1313

1414
## Benefits and drawbacks of map fields
1515

@@ -40,19 +40,6 @@ The example query below uses the `http.protocol` property inside the `attributes
4040

4141
[Run in playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7b%22apl%22%3a%22%5b%27otel-demo-traces%27%5d%5cn%7c%20where%20%5b%27attributes.custom%27%5d%5b%27http.protocol%27%5d%20%3d%3d%20%27HTTP%2f1.1%27%22%2c%22queryOptions%22%3a%7b%22quickRange%22%3a%2230d%22%7d%7d)
4242

43-
## Access properties of nested maps
44-
45-
To access the properties of nested maps, use dot notation, index notation, or a mix of the two. If you use index notation for an entity, enclose the entity name in quotation marks (`'` or `"`) and square brackets (`[]`). For example:
46-
- `where map_field.property1.property2 == 14`
47-
- `where ['map_field'].property1.property2 == 14`
48-
- `where ['map_field']['property1']['property2'] == 14`
49-
50-
If an entity name has spaces (` `), dots (`.`), or dashes (`-`), you can only use index notation for that entity. You can use dot notation for the other entities. For example:
51-
- `where ['map.field']['property.name1']['property.name2'] == 14`
52-
- `where ['map.field'].property1.property2 == 14`
53-
54-
For more information, see [Entity names](/apl/entities/entity-names#quote-identifiers).
55-
5643
## Create map fields using UI
5744

5845
To create a map field using the UI:
@@ -92,4 +79,66 @@ To view map fields:
9279

9380
- **MAPPED** means that the field was previously an ordinary field but at some point its parent was changed to a map field. Axiom adds new events to the field as an attribute of the parent map field. Events you ingested before the change retain the ordinary structure.
9481
- **UNUSED** means that the field is configured as a map field but you haven’t yet ingested data into it. Once ingested, data within this field won’t count toward your field limit.
95-
- **REMOVED** means that the field was configured as a map field but at some point it was changed to an ordinary field. Axiom adds new events to the field as usual. Events you ingested before the change retain the map structure. To fully remove this field, first [trim your dataset](/reference/datasets#trim-dataset) to remove the time period when map data was ingested, and then [vacuum the fields](/reference/datasets#vacuum-fields).
82+
- **REMOVED** means that the field was configured as a map field but at some point it was changed to an ordinary field. Axiom adds new events to the field as usual. Events you ingested before the change retain the map structure. To fully remove this field, first [trim your dataset](/reference/datasets#trim-dataset) to remove the time period when map data was ingested, and then [vacuum the fields](/reference/datasets#vacuum-fields).
83+
84+
## Access properties of nested maps
85+
86+
To access the properties of nested maps, use index notation, dot notation, or a mix of the two. If you use index notation for an entity, enclose the entity name in quotation marks (`'` or `"`) and square brackets (`[]`). For example:
87+
- `where ['map_field']['property1']['property2'] == 14`
88+
- `where map_field.property1.property2 == 14`
89+
- `where ['map_field'].property1.property2 == 14`
90+
91+
If an entity name has spaces (` `), dots (`.`), or dashes (`-`), you can only use index notation for that entity. You can use dot notation for the other entities. For example:
92+
- `where ['map.field']['property.name1']['property.name2'] == 14`
93+
- `where ['map.field'].property1.property2 == 14`
94+
95+
<Note>
96+
In OTel traces, custom attributes are located in the `attributes.custom` map field. You can access them as `['attributes.custom']['header.Accept']`, for example. In this case, you don’t access the `Accept` field nested within the `header` field. What actually happens is that you access the field named `header.Accept` within the `attributes.custom` map field.
97+
</Note>
98+
99+
For more information on quoting field names, see [Entity names](/apl/entities/entity-names#quote-identifiers).
100+
101+
## Map fields and flattened fields
102+
103+
Within a dataset, the same fields can exist as flattened fields and as subfields of a map field.
104+
105+
For example, consider the following:
106+
107+
1. `geo` is initially not a map field.
108+
1. You ingest the following:
109+
110+
```json
111+
{
112+
"geo": {
113+
"city": "Paris",
114+
"country": "France"
115+
}
116+
}
117+
```
118+
119+
This adds two flattened fields to the dataset that you can access as `['geo.city']` or `['geo.country']`.
120+
121+
1. You change `geo` to a map field through the UI or the API.
122+
1. You ingest the following:
123+
124+
```json
125+
{
126+
"geo": {
127+
"city": "Paris",
128+
"country": "France"
129+
}
130+
}
131+
```
132+
133+
You use the same ingest JSON as before, but this adds the new subfields to the `geo` parent map field. You can access the subfields as `['geo']['city']` and `['geo']['country']`.
134+
135+
Axiom treats the flattened fields (`['geo.city']` and `['geo.country']`) and the subfields of the map field (`['geo']['city']` and `['geo']['country']`) as separate fields and doesn’t maintain a relationship between them.
136+
137+
<Note>
138+
Queries using `['geo.city']` access a field literally named `geo.city`, while `['geo']['city']` accesses the `city` key inside a `geo` map. These references are not equivalent.
139+
</Note>
140+
141+
To avoid confusion:
142+
143+
- Choose either a flattened or map-based structure when designing your schema.
144+
- Be explicit in queries about which fields to include or exclude.

0 commit comments

Comments
 (0)