Add docs about map fields

apl/data-types/map-fields.mdx

@@ -0,0 +1,39 @@
+---
+title: 'Map fields'
+description: 'This page explains what map fields are and how to query them.'
+tags: ['axiom documentation', 'documentation', 'axiom', 'map fields', 'object fields', 'data types']
+---
+
+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.
+
+## Benefits of map fields
+
+The benefit of map fields is that you can store additional attributes without adding more fields. This is particularly useful when the shape of your data is unpredictable (for example, additional attributes added by an OpenTelemetry instrumentation). Using map fields means that you can avoid reaching the field limit of a dataset and improve query performance.
+
+## Custom attributes in tracing datasets
+
+If you use [OpenTelemetry](/send-data/opentelemetry) to send data to Axiom, you find some attributes in the `attributes.custom` map field. The reason is that instrumentation libraries can add hundreds or even thousands of arbitrary attributes to spans. Storing each custom attribute in a separate field would significantly increase the number of fields in your dataset. To keep the number of fields in your dataset under control, Axiom places all custom attributes in the single `attributes.custom` map field.
+
+## Use map fields in queries
+
+The example query below uses the map field `attributes.http.url` to filter results:
+
+```kusto
+['otel-demo-traces']
+| where ['attributes.http.url'] == 'http://opentelemetry-demo-frontendproxy:8080/api/cart'
+```
+
+[Run in playground](https://play.axiom.co/axiom-play-qf1k/explorer?initForm=%7b%22apl%22%3a%22%5b%27otel-demo-traces%27%5d%5cn%7c%20where%20%5b%27attributes.http.url%27%5d%20%3d%3d%20%27http%3a%2f%2fopentelemetry-demo-frontendproxy%3a8080%2fapi%2fcart%27%22%2c%22queryOptions%22%3a%7b%22quickRange%22%3a%2230d%22%7d%7d)
+
+To access `http.protocol` inside the `attributes.custom` map field, use the syntax `['MAP_FIELD_NAME']['INDEX_TO_MAP_FIELD']` instead:
+
+```kusto
+['otel-demo-traces']
+| where ['attributes.custom']['http.protocol'] == 'HTTP/1.1'
+```
+
+[Run in playground](https://play.axiom.co/axiom-play-qf1k/explorer?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)
+
+## Add custom fields
+
+The possibility to add custom fields is coming in early 2025. To express interest in the feature, [contact Axiom](https://axiom.co/contact).

mint.json

@@ -422,6 +422,7 @@
           "icon": "book",
           "pages": [
             "apl/entities/entity-names",
+            "apl/data-types/map-fields",
             "apl/data-types/null-values",
             "apl/data-types/scalar-data-types",
             "apl/query-statement/set-statement",