DOC-648 | Stable multi-dimensional indexes

site/content/3.12/about-arangodb/features/community-edition.md

@@ -201,11 +201,9 @@ see [arangodb.com/community-server/](https://www.arangodb.com/community-server/)
   the S2 library. <!-- TODO: list supported queries? Centroid-limitations? -->
   Support for composable, distance-based geo-queries ("geo cursors").
 
-{{% comment %}} Experimental feature
 - [**Multi-dimensional indexes**](../../index-and-search/indexing/working-with-indexes/multi-dimensional-indexes.md):
   An index type to efficiently intersect multiple range queries, like finding
   all appointments that intersect a time range.
-{{% /comment %}}
 
 - [**Background Indexing**](../../index-and-search/indexing/basics.md#creating-indexes-in-background):
   Indexes can be created in the background to not block queries in the meantime.

site/content/3.12/about-arangodb/features/highlights-by-version.md

@@ -15,6 +15,10 @@ aliases:
 
 - 
 
+- [**Multi-dimensional indexes**](../../index-and-search/indexing/working-with-indexes/multi-dimensional-indexes.md):
+  An index type to efficiently intersect multiple range queries, like finding
+  all appointments that intersect a time range.
+
 **Enterprise Edition**
 
 - [**ArangoSearch WAND optimization**](../../index-and-search/arangosearch/performance.md#wand-optimization):

site/content/3.12/develop/http-api/indexes/multi-dimensional.md

@@ -10,9 +10,9 @@ archetype: default
 
 ```openapi
 paths:
-  /_api/index#zkd:
+  /_api/index#mdi:
     post:
-      operationId: createIndexZkd
+      operationId: createIndexMdi
       description: |
         Creates a multi-dimensional index for the collection `collection-name`, if
         it does not already exist. The call expects an object containing the index
@@ -37,7 +37,7 @@ paths:
               properties:
                 type:
                   description: |
-                    must be equal to `"zkd"`.
+                    must be equal to `"mdi"` or `"mdi-prefixed"`.
                   type: string
                 name:
                   description: |
@@ -48,24 +48,61 @@ paths:
                   type: string
                 fields:
                   description: |
-                    an array of attribute names used for each dimension. Array expansions are not allowed.
+                    An array of attribute names used for each dimension. Array expansions are not allowed.
+                  type: array
+                  items:
+                    type: string
+                fieldValueTypes:
+                  description: |
+                    must be equal to `"double"`. Currently only doubles are supported as values.
+                  type: string
+                prefixFields:
+                  description: |
+                    Requires `type` to be `"mdi-prefixed"`, and `prefixFields` needs to be set in this case.
+
+                    An array of attribute names used as search prefix. Array expansions are not allowed.
+                  type: array
+                  items:
+                    type: string
+                storedValues:
+                  description: |
+                    The optional `storedValues` attribute can contain an array of paths to additional
+                    attributes to store in the index. These additional attributes cannot be used for
+                    index lookups or for sorting, but they can be used for projections. This allows an
+                    index to fully cover more queries and avoid extra document lookups.
+                    The maximum number of attributes in `storedValues` is 32.
+
+                    It is not possible to create multiple indexes with the same `fields` attributes
+                    and uniqueness but different `storedValues` attributes. That means the value of
+                    `storedValues` is not considered by index creation calls when checking if an
+                    index is already present or needs to be created.
+
+                    In unique indexes, only the attributes in `fields` are checked for uniqueness,
+                    but the attributes in `storedValues` are not checked for their uniqueness.
+                    Non-existing attributes are stored as `null` values inside `storedValues`.
+
+                    Attributes in `storedValues` cannot overlap with attributes
+                    specified in `prefixFields` but you can have the attributes
+                    in both `storedValues` and `fields`.
                   type: array
                   items:
                     type: string
                 unique:
                   description: |
                     if `true`, then create a unique index.
                   type: boolean
+                  default: false
+                sparse:
+                  description: |
+                    If `true`, then create a sparse index.
+                  type: boolean
+                  default: false
                 inBackground:
                   description: |
                     You can set this option to `true` to create the index
                     in the background, which will not write-lock the underlying collection for
                     as long as if the index is built in the foreground. The default value is `false`.
                   type: boolean
-                fieldValueTypes:
-                  description: |
-                    must be equal to `"double"`. Currently only doubles are supported as values.
-                  type: string
       responses:
         '200':
           description: |
@@ -91,15 +128,15 @@ paths:
 ---
 description: |-
   Creating a multi-dimensional index
-name: RestIndexCreateNewZkd
+name: RestIndexCreateNewMdi
 ---
 var cn = "intervals";
 db._drop(cn);
 db._create(cn);
 
     var url = "/_api/index?collection=" + cn;
     var body = {
-      type: "zkd",
+      type: "mdi",
       fields: [ "from", "to" ],
       fieldValueTypes: "double"
     };
@@ -111,3 +148,29 @@ db._create(cn);
     logJsonResponse(response);
 db._drop(cn);
 ```
+
+```curl
+---
+description: |-
+  Creating a prefixed multi-dimensional index
+name: RestIndexCreateNewMdiPrefixed
+---
+var cn = "intervals";
+db._drop(cn);
+db._create(cn);
+
+    var url = "/_api/index?collection=" + cn;
+    var body = {
+      type: "mdi-prefixed",
+      fields: [ "from", "to" ],
+      fieldValueTypes: "double",
+      prefixFields: ["year", "month"]
+    };
+
+    var response = logCurlRequest('POST', url, body);
+
+    assert(response.code === 201);
+
+    logJsonResponse(response);
+db._drop(cn);
+```

site/content/3.12/index-and-search/indexing/working-with-indexes/multi-dimensional-indexes.md

@@ -7,13 +7,9 @@ description: >-
   such as time ranges, for efficient intersection of multiple range queries
 archetype: default
 ---
-The multi-dimensional index type is called **ZKD**.
+The multi-dimensional index type was previously called `"zkd"`.
 
-{{< warning >}}
-`zkd` indexes are an **experimental** feature.
-{{< /warning >}}
-
-A multi-dimensional index is setup by setting the index type to `"zkd"`.
+A multi-dimensional index is setup by setting the index type to `"mdi"`.
 The `fields` attribute describes which fields are used as dimensions.
 The value of each dimension has to be a numeric (double) value.
 
@@ -33,7 +29,7 @@ To do so one creates a multi-dimensional index on the attributes `x`, `y` and
 
 ```js
 db.collection.ensureIndex({
-    type: "zkd",
+    type: "mdi",
     fields: ["x", "y", "z"],
     fieldValueTypes: "double"
 });
@@ -154,7 +150,6 @@ FOR app IN appointments OPTIONS { lookahead: 32 }
 Currently there are a few limitations:
 
 - Using array expansions for attributes is not possible (e.g. `array[*].attr`)
-- The `sparse` property is not supported.
 - You can only index numeric values that are representable as IEEE-754 double.
 - A high number of dimensions (more than 5) can impact the performance considerably.
 - The performance can vary depending on the dataset. Densely packed points can

site/content/3.12/release-notes/version-3.12/api-changes-in-3-12.md

@@ -126,13 +126,34 @@ for details.
 
 #### Index API
 
+##### Inverted indexes
+
 Indexes of type `inverted` accept a new `optimizeTopK` property for the
 ArangoSearch WAND optimization. It is an array of strings, optional, and
 defaults to `[]`.
 
 See the [inverted index `optimizeTopK` property](../../develop/http-api/indexes/inverted.md)
 for details.
 
+##### Multi-dimensional indexes
+
+The previously experimental `zkd` index is now stable and has been renamed to
+`mdi`. Existing indexes keep the `zkd` type. The HTTP API still allows the old
+name to create new indexes that behave exactly like `mdi` indexes but this is
+discouraged. The `zkd` alias may get removed in a future version.
+
+An additional `mdi-prefixed` index variant has been added. This is a new index
+type in the API with the same settings as the `mdi` index but with one additional
+`prefixFields` attribute. It is a required setting and accepts an array of strings
+similar to the `fields` attribute.
+
+Both multi-dimensional index variants now support a `sparse` (boolean) and
+`storedValues` (array of strings) setting that were not supported by the `zkd`
+index in previous versions.
+
+See [Working with multi-dimensional indexes](../../index-and-search/indexing/working-with-indexes/multi-dimensional-indexes.md)
+for details.
+
 #### Optimizer rule descriptions
 
 <small>Introduced in: v3.10.9, v3.11.2</small>

site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md

@@ -249,6 +249,25 @@ non-collection data.
 
 ## Indexing
 
+### Multi-dimensional indexes
+
+The previously experimental `zkd` index is now stable and has been renamed to
+`mdi`. Existing indexes keep the `zkd` type.
+
+Multi-dimensional indexes can now be declared as `sparse` to exclude documents
+from the index that do not have the defined attributes or are explicitly set to
+`null` values. If a non-value is set, it still needs to be numeric.
+
+Multi-dimensional indexes now support stored values to cover queries for better
+performance.
+
+An additional `mdi-prefixed` index variant has been added that lets you specify
+additional attributes for the index to narrow down the search space using
+equality checks.
+
+See [Multi-dimensional indexes](../../index-and-search/indexing/working-with-indexes/multi-dimensional-indexes.md)
+for details.
+
 ### Stored values can contain the `_id` attribute
 
 The usage of the `_id` system attribute was previously disallowed for