From 4056efa3a4ad9de5460c7b7a448077f6508bce98 Mon Sep 17 00:00:00 2001 From: maierlars Date: Fri, 12 Mar 2021 16:16:04 +0100 Subject: [PATCH 01/14] Barebones for multi dimensional docu. --- 3.8/indexing-which-index.md | 5 +++++ 3.8/indexing.md | 1 + _data/3.8-http.yml | 2 ++ _data/3.8-manual.yml | 2 ++ 4 files changed, 10 insertions(+) diff --git a/3.8/indexing-which-index.md b/3.8/indexing-which-index.md index fef4dbe2b9..18b5980bdb 100644 --- a/3.8/indexing-which-index.md +++ b/3.8/indexing-which-index.md @@ -94,6 +94,11 @@ different usage scenarios: result TTL indexes will likely not be used for filtering and sort operations in user-land AQL queries. +- multi-dimensional index: a multi dimensional index allows to efficiently intersect + multiple range queries. Typical use cases are querying intervals that intersect + a given point or interval. Currently only doubles are supported as underlying + type for each dimension. + - geo index: the geo index provided by ArangoDB allows searching for documents within a radius around a two-dimensional earth coordinate (point), or to find documents with are closest to a point. Document coordinates can either diff --git a/3.8/indexing.md b/3.8/indexing.md index 2c50f23727..359b0e0e77 100644 --- a/3.8/indexing.md +++ b/3.8/indexing.md @@ -16,5 +16,6 @@ There are special sections for - [Persistent Indexes](indexing-persistent.html) - [TTL Indexes](indexing-ttl.html) - [Fulltext Indexes](indexing-fulltext.html) + - [Multidimensional Indexes](indexing-zkd.html) - [Geo-spatial Indexes](indexing-geo.html) - [Vertex-centric Indexes](indexing-vertex-centric.html) diff --git a/_data/3.8-http.yml b/_data/3.8-http.yml index bf3a379427..8ada78c0ee 100644 --- a/_data/3.8-http.yml +++ b/_data/3.8-http.yml @@ -88,6 +88,8 @@ href: indexes-persistent.html - text: TTL href: indexes-ttl.html + - text: Multi-dimensional + href: indexes-multi-dim.html - text: Geo-Spatial href: indexes-geo.html - text: Fulltext diff --git a/_data/3.8-manual.yml b/_data/3.8-manual.yml index 316f655a09..89b80a5c68 100644 --- a/_data/3.8-manual.yml +++ b/_data/3.8-manual.yml @@ -287,6 +287,8 @@ href: indexing-ttl.html - text: Fulltext Indexes href: indexing-fulltext.html + - text: Multi-dimensional Indexes + href: indexing-multi-dim.html - text: Geo-spatial Indexes href: indexing-geo.html - text: Vertex Centric Indexes From ef07e051c993372944b5a7aba7299085f1cfc2be Mon Sep 17 00:00:00 2001 From: maierlars Date: Fri, 12 Mar 2021 16:46:54 +0100 Subject: [PATCH 02/14] Added missing files. --- 3.8/http/indexes-multi-dim.md | 7 +++++++ 3.8/indexing-multi-dim.md | 11 +++++++++++ 2 files changed, 18 insertions(+) create mode 100644 3.8/http/indexes-multi-dim.md create mode 100644 3.8/indexing-multi-dim.md diff --git a/3.8/http/indexes-multi-dim.md b/3.8/http/indexes-multi-dim.md new file mode 100644 index 0000000000..f59448d737 --- /dev/null +++ b/3.8/http/indexes-multi-dim.md @@ -0,0 +1,7 @@ +--- +layout: default +--- +Working with multi-dimensional Indexes +======================================= + +{% docublock post_api_index_zkd %} diff --git a/3.8/indexing-multi-dim.md b/3.8/indexing-multi-dim.md new file mode 100644 index 0000000000..8cd727a1c7 --- /dev/null +++ b/3.8/indexing-multi-dim.md @@ -0,0 +1,11 @@ +--- +layout: default +description: This is an introduction to ArangoDB's multi-dimensional indexes +--- +Multi-dimensional indexes +================ + +This is an introduction to ArangoDB's multi-dimensional indexes. + +Introduction to Multi-dimensional Indexes +-------------------------------- From a79b0bb228f2d80f8586a5c8852b2e0fd86ab1ca Mon Sep 17 00:00:00 2001 From: maierlars Date: Mon, 15 Mar 2021 08:17:24 +0100 Subject: [PATCH 03/14] Fixed link. --- 3.8/indexing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/3.8/indexing.md b/3.8/indexing.md index 359b0e0e77..f599716fa8 100644 --- a/3.8/indexing.md +++ b/3.8/indexing.md @@ -16,6 +16,6 @@ There are special sections for - [Persistent Indexes](indexing-persistent.html) - [TTL Indexes](indexing-ttl.html) - [Fulltext Indexes](indexing-fulltext.html) - - [Multidimensional Indexes](indexing-zkd.html) + - [Multidimensional Indexes](indexing-multi-dim.html) - [Geo-spatial Indexes](indexing-geo.html) - [Vertex-centric Indexes](indexing-vertex-centric.html) From 027dd1460f5375102dd60103a8ae6739c2181d21 Mon Sep 17 00:00:00 2001 From: maierlars Date: Mon, 15 Mar 2021 09:29:39 +0100 Subject: [PATCH 04/14] Added example for multi dim index. --- 3.8/indexing-which-index.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/3.8/indexing-which-index.md b/3.8/indexing-which-index.md index 18b5980bdb..857d5b7366 100644 --- a/3.8/indexing-which-index.md +++ b/3.8/indexing-which-index.md @@ -96,8 +96,15 @@ different usage scenarios: - multi-dimensional index: a multi dimensional index allows to efficiently intersect multiple range queries. Typical use cases are querying intervals that intersect - a given point or interval. Currently only doubles are supported as underlying - type for each dimension. + a given point or interval, e.g. if intervals look like + + { "from": 12, "to": 45 } + + with an index on `from, to` can be used to query via + + FOR i IN intervals FILTER i.from <= t && t <= i.to RETURN i + + Currently only doubles are supported as underlying type for each dimension. - geo index: the geo index provided by ArangoDB allows searching for documents within a radius around a two-dimensional earth coordinate (point), or to From af486769818316e2e30ceca8d9de6beee24bf741 Mon Sep 17 00:00:00 2001 From: maierlars Date: Mon, 15 Mar 2021 10:31:20 +0100 Subject: [PATCH 05/14] More documentation. --- 3.8/indexing-multi-dim.md | 71 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 68 insertions(+), 3 deletions(-) diff --git a/3.8/indexing-multi-dim.md b/3.8/indexing-multi-dim.md index 8cd727a1c7..7d3a86ed61 100644 --- a/3.8/indexing-multi-dim.md +++ b/3.8/indexing-multi-dim.md @@ -5,7 +5,72 @@ description: This is an introduction to ArangoDB's multi-dimensional indexes Multi-dimensional indexes ================ -This is an introduction to ArangoDB's multi-dimensional indexes. - Introduction to Multi-dimensional Indexes --------------------------------- +----------------------------------------- + +The multi-dimensional index type provided by ArangoDB can be used to efficiently +intersect multiple range queries. + +A multi-dimensional index is setup by setting the index type to `zkd`. The `fields` +attribute describes which fields are used as dimensions. The value of each dimension +has to be a double value. (See limitations) + + +### Querying documents within a 3D box + +Assume we have documents in a collection `points` of the form + + {x: 12.9, y: -284.0, z: 0.02} + +and we want to query all documents that contained within a box defined by + + [x0, x1] * [y0, y1] * [z0, z1]. + +To do so one creates a multi-dimensional index on the attributes `x`, `y` and `z`: + + + db.collection.ensureIndex({ + type: "zkd", + fields: ["x", "y", "z"], + fieldValueTypes: "double" + }); + +Unlike for other indexes the order of the fields does not matter. `fieldValueTypes` is required and +future extensions of the index will allow different values. However, for now `double` is the only +allowed value. + +Now we can use the index in a query + + FOR p IN points + FILTER x0 <= p.x && p.x <= x1 + FILTER y0 <= p.y && p.y <= y1 + FILTER z0 <= p.z && p.z <= z1 + RETURN p + +### Possible range queries + +Having an index on a set of fields does not require you to specify a full range +for every dimension. For each dimension you can decide if you want to only bound +it from one side (i.e. only an upper or lower bound) or not bound it at all. + +Futhermore you can use any comparsion operator. The index supports `<=` and `>=` +naturally, `==` will be translated to the bound `[c, c]`. Strict comparsion +is translated to they non-strict counterparts and a post-filter is inserted. + + FOR p IN points + FILTER 2 <= p.x && p.x < 9 + FILTER y0 >= 80 + FILTER p.z == 4 + RETURN p + +### Limitations + +Currently there are a few limitations: + +- Using array expansions for attributes is not possible. +- The `sparse` property is not supported. +- You can only index numeric values that are representable as IEEE-754 double. + + + + From 9059f3dfd59e833e41d670f28906018c08fe0f46 Mon Sep 17 00:00:00 2001 From: maierlars Date: Mon, 15 Mar 2021 14:38:12 +0100 Subject: [PATCH 06/14] Rephrase some parts. --- 3.8/indexing-multi-dim.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/3.8/indexing-multi-dim.md b/3.8/indexing-multi-dim.md index 7d3a86ed61..3d8f969e4e 100644 --- a/3.8/indexing-multi-dim.md +++ b/3.8/indexing-multi-dim.md @@ -50,12 +50,13 @@ Now we can use the index in a query ### Possible range queries Having an index on a set of fields does not require you to specify a full range -for every dimension. For each dimension you can decide if you want to only bound -it from one side (i.e. only an upper or lower bound) or not bound it at all. +for every field. For each field you can decide if you want to bound +it from both sides, from one side only (i.e. only an upper or lower bound) +or not bound it at all. Futhermore you can use any comparsion operator. The index supports `<=` and `>=` naturally, `==` will be translated to the bound `[c, c]`. Strict comparsion -is translated to they non-strict counterparts and a post-filter is inserted. +is translated to their non-strict counterparts and a post-filter is inserted. FOR p IN points FILTER 2 <= p.x && p.x < 9 From 51c82341b8d670ba28a835b48fec3c54a3c2355c Mon Sep 17 00:00:00 2001 From: Lars Maier Date: Mon, 15 Mar 2021 14:09:38 +0000 Subject: [PATCH 07/14] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Tobias Gödderz --- 3.8/indexing-multi-dim.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/3.8/indexing-multi-dim.md b/3.8/indexing-multi-dim.md index 3d8f969e4e..ff6e3e3728 100644 --- a/3.8/indexing-multi-dim.md +++ b/3.8/indexing-multi-dim.md @@ -54,7 +54,7 @@ for every field. For each field you can decide if you want to bound it from both sides, from one side only (i.e. only an upper or lower bound) or not bound it at all. -Futhermore you can use any comparsion operator. The index supports `<=` and `>=` +Furthermore you can use any comparison operator. The index supports `<=` and `>=` naturally, `==` will be translated to the bound `[c, c]`. Strict comparsion is translated to their non-strict counterparts and a post-filter is inserted. @@ -74,4 +74,3 @@ Currently there are a few limitations: - From 8940697dbd8cbcefdd705d9d9f833726d7123329 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Thu, 8 Apr 2021 23:34:33 +0200 Subject: [PATCH 08/14] Move to 3.9 --- 3.8/indexing-which-index.md | 12 ------------ 3.8/indexing.md | 1 - {3.8 => 3.9}/http/indexes-multi-dim.md | 0 {3.8 => 3.9}/indexing-multi-dim.md | 0 3.9/indexing-which-index.md | 12 ++++++++++++ 3.9/indexing.md | 1 + _data/3.8-manual.yml | 2 -- _data/3.9-http.yml | 2 ++ _data/3.9-manual.yml | 2 ++ 9 files changed, 17 insertions(+), 15 deletions(-) rename {3.8 => 3.9}/http/indexes-multi-dim.md (100%) rename {3.8 => 3.9}/indexing-multi-dim.md (100%) diff --git a/3.8/indexing-which-index.md b/3.8/indexing-which-index.md index 857d5b7366..fef4dbe2b9 100644 --- a/3.8/indexing-which-index.md +++ b/3.8/indexing-which-index.md @@ -94,18 +94,6 @@ different usage scenarios: result TTL indexes will likely not be used for filtering and sort operations in user-land AQL queries. -- multi-dimensional index: a multi dimensional index allows to efficiently intersect - multiple range queries. Typical use cases are querying intervals that intersect - a given point or interval, e.g. if intervals look like - - { "from": 12, "to": 45 } - - with an index on `from, to` can be used to query via - - FOR i IN intervals FILTER i.from <= t && t <= i.to RETURN i - - Currently only doubles are supported as underlying type for each dimension. - - geo index: the geo index provided by ArangoDB allows searching for documents within a radius around a two-dimensional earth coordinate (point), or to find documents with are closest to a point. Document coordinates can either diff --git a/3.8/indexing.md b/3.8/indexing.md index f599716fa8..2c50f23727 100644 --- a/3.8/indexing.md +++ b/3.8/indexing.md @@ -16,6 +16,5 @@ There are special sections for - [Persistent Indexes](indexing-persistent.html) - [TTL Indexes](indexing-ttl.html) - [Fulltext Indexes](indexing-fulltext.html) - - [Multidimensional Indexes](indexing-multi-dim.html) - [Geo-spatial Indexes](indexing-geo.html) - [Vertex-centric Indexes](indexing-vertex-centric.html) diff --git a/3.8/http/indexes-multi-dim.md b/3.9/http/indexes-multi-dim.md similarity index 100% rename from 3.8/http/indexes-multi-dim.md rename to 3.9/http/indexes-multi-dim.md diff --git a/3.8/indexing-multi-dim.md b/3.9/indexing-multi-dim.md similarity index 100% rename from 3.8/indexing-multi-dim.md rename to 3.9/indexing-multi-dim.md diff --git a/3.9/indexing-which-index.md b/3.9/indexing-which-index.md index fef4dbe2b9..857d5b7366 100644 --- a/3.9/indexing-which-index.md +++ b/3.9/indexing-which-index.md @@ -94,6 +94,18 @@ different usage scenarios: result TTL indexes will likely not be used for filtering and sort operations in user-land AQL queries. +- multi-dimensional index: a multi dimensional index allows to efficiently intersect + multiple range queries. Typical use cases are querying intervals that intersect + a given point or interval, e.g. if intervals look like + + { "from": 12, "to": 45 } + + with an index on `from, to` can be used to query via + + FOR i IN intervals FILTER i.from <= t && t <= i.to RETURN i + + Currently only doubles are supported as underlying type for each dimension. + - geo index: the geo index provided by ArangoDB allows searching for documents within a radius around a two-dimensional earth coordinate (point), or to find documents with are closest to a point. Document coordinates can either diff --git a/3.9/indexing.md b/3.9/indexing.md index 2c50f23727..f599716fa8 100644 --- a/3.9/indexing.md +++ b/3.9/indexing.md @@ -16,5 +16,6 @@ There are special sections for - [Persistent Indexes](indexing-persistent.html) - [TTL Indexes](indexing-ttl.html) - [Fulltext Indexes](indexing-fulltext.html) + - [Multidimensional Indexes](indexing-multi-dim.html) - [Geo-spatial Indexes](indexing-geo.html) - [Vertex-centric Indexes](indexing-vertex-centric.html) diff --git a/_data/3.8-manual.yml b/_data/3.8-manual.yml index 89b80a5c68..316f655a09 100644 --- a/_data/3.8-manual.yml +++ b/_data/3.8-manual.yml @@ -287,8 +287,6 @@ href: indexing-ttl.html - text: Fulltext Indexes href: indexing-fulltext.html - - text: Multi-dimensional Indexes - href: indexing-multi-dim.html - text: Geo-spatial Indexes href: indexing-geo.html - text: Vertex Centric Indexes diff --git a/_data/3.9-http.yml b/_data/3.9-http.yml index 8eb73cf0d8..068fdf25f1 100644 --- a/_data/3.9-http.yml +++ b/_data/3.9-http.yml @@ -90,6 +90,8 @@ href: indexes-persistent.html - text: TTL href: indexes-ttl.html + - text: Multi-dimensional + href: indexes-multi-dim.html - text: Geo-Spatial href: indexes-geo.html - text: Fulltext diff --git a/_data/3.9-manual.yml b/_data/3.9-manual.yml index 9dd8ffcf75..1436375c12 100644 --- a/_data/3.9-manual.yml +++ b/_data/3.9-manual.yml @@ -287,6 +287,8 @@ href: indexing-ttl.html - text: Fulltext Indexes href: indexing-fulltext.html + - text: Multi-dimensional Indexes + href: indexing-multi-dim.html - text: Geo-spatial Indexes href: indexing-geo.html - text: Vertex Centric Indexes From a2908bfae359a442a8122dc30503a26e2f2ce465 Mon Sep 17 00:00:00 2001 From: maierlars Date: Thu, 5 Aug 2021 16:18:03 +0200 Subject: [PATCH 09/14] Added example and more limitations. --- 3.9/indexing-multi-dim.md | 54 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 52 insertions(+), 2 deletions(-) diff --git a/3.9/indexing-multi-dim.md b/3.9/indexing-multi-dim.md index ff6e3e3728..8f45d66d7a 100644 --- a/3.9/indexing-multi-dim.md +++ b/3.9/indexing-multi-dim.md @@ -64,6 +64,54 @@ is translated to their non-strict counterparts and a post-filter is inserted. FILTER p.z == 4 RETURN p +### Example Use Case + +If you build a calendar using ArangoDB you could create a collection for each user +that contains her appointsments. The documents would roughly look as follows: + + { + "from": 345365, + "to": 678934, + "what": "Dentist", + } + +Where `from`/`to` are the timestamps when an appointment starts/ends. Having an +multi-dimensional index on the fields + + ["from", "to"] + +allows you to query effeciently for all appointsments within a given time range. + +#### Finding all appointments within a time range +Given a time range `[f, t]` we want to find all appointments `[from, to]` that +are completely contained in `[f, t]`. Those appointments clearly satisfy the +relation + + f <= from and to <= t + +Thus our query would be: + + FOR app IN appointments + FILTER f <= app.from + FILTER app.to <= t + RETURN app + + +#### Finding all appointments that interset a time range +Given a time range `[f, t]` we want to find all appointments `[from, to]` that +intersect `[f, t]`. Two intervals `[a_1, b_1]` and `[a_2, b_2]` intersect if +and only if + + a_2 <= b_1 && a_1 <= b_2 + +Thus our query would be: + + FOR app IN appointments + FILTER f <= app.to + FILTER app.from <= t + RETURN app + + ### Limitations Currently there are a few limitations: @@ -71,6 +119,8 @@ Currently there are a few limitations: - Using array expansions for attributes is not possible. - 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 lead +to a high number of seeks. This behavior is typical for indexing using space +filling curves. From 1bf9764665164b5a85d544cf0379c5cf69935d7a Mon Sep 17 00:00:00 2001 From: maierlars Date: Thu, 5 Aug 2021 16:49:50 +0200 Subject: [PATCH 10/14] Fixing typos. --- 3.9/indexing-multi-dim.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/3.9/indexing-multi-dim.md b/3.9/indexing-multi-dim.md index 8f45d66d7a..2dca37663d 100644 --- a/3.9/indexing-multi-dim.md +++ b/3.9/indexing-multi-dim.md @@ -85,7 +85,7 @@ allows you to query effeciently for all appointsments within a given time range. #### Finding all appointments within a time range Given a time range `[f, t]` we want to find all appointments `[from, to]` that are completely contained in `[f, t]`. Those appointments clearly satisfy the -relation +condition f <= from and to <= t @@ -97,12 +97,12 @@ Thus our query would be: RETURN app -#### Finding all appointments that interset a time range +#### Finding all appointments that intersect a time range Given a time range `[f, t]` we want to find all appointments `[from, to]` that intersect `[f, t]`. Two intervals `[a_1, b_1]` and `[a_2, b_2]` intersect if and only if - a_2 <= b_1 && a_1 <= b_2 + a_2 <= b_1 and a_1 <= b_2 Thus our query would be: From 948693b03ba72473438cad7cffd78dafd0260a6e Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Mon, 20 Sep 2021 19:08:26 +0200 Subject: [PATCH 11/14] Formatting --- 3.9/indexing-multi-dim.md | 121 +++++++++++++++++++++----------------- 1 file changed, 67 insertions(+), 54 deletions(-) diff --git a/3.9/indexing-multi-dim.md b/3.9/indexing-multi-dim.md index 2dca37663d..9e473c6282 100644 --- a/3.9/indexing-multi-dim.md +++ b/3.9/indexing-multi-dim.md @@ -3,7 +3,7 @@ layout: default description: This is an introduction to ArangoDB's multi-dimensional indexes --- Multi-dimensional indexes -================ +========================= Introduction to Multi-dimensional Indexes ----------------------------------------- @@ -11,41 +11,46 @@ Introduction to Multi-dimensional Indexes The multi-dimensional index type provided by ArangoDB can be used to efficiently intersect multiple range queries. -A multi-dimensional index is setup by setting the index type to `zkd`. The `fields` -attribute describes which fields are used as dimensions. The value of each dimension -has to be a double value. (See limitations) - +A multi-dimensional index is setup by setting the index type to `"zkd"`. +The `fields` attribute describes which fields are used as dimensions. +The value of each dimension has to be a numeric (double) value. ### Querying documents within a 3D box Assume we have documents in a collection `points` of the form - {x: 12.9, y: -284.0, z: 0.02} +```json +{"x": 12.9, "y": -284.0, "z": 0.02} +``` and we want to query all documents that contained within a box defined by +`[x0, x1] * [y0, y1] * [z0, z1]`. - [x0, x1] * [y0, y1] * [z0, z1]. - -To do so one creates a multi-dimensional index on the attributes `x`, `y` and `z`: +To do so one creates a multi-dimensional index on the attributes `x`, `y` and +`z`, e.g. in _arangosh_: +```js +db.collection.ensureIndex({ + type: "zkd", + fields: ["x", "y", "z"], + fieldValueTypes: "double" +}); +``` - db.collection.ensureIndex({ - type: "zkd", - fields: ["x", "y", "z"], - fieldValueTypes: "double" - }); +Unlike for other indexes the order of the fields does not matter. -Unlike for other indexes the order of the fields does not matter. `fieldValueTypes` is required and -future extensions of the index will allow different values. However, for now `double` is the only -allowed value. +`fieldValueTypes` is required and the only allowed value is `"double"`. +Future extensions of the index will allow other types. -Now we can use the index in a query +Now we can use the index in a query: - FOR p IN points - FILTER x0 <= p.x && p.x <= x1 - FILTER y0 <= p.y && p.y <= y1 - FILTER z0 <= p.z && p.z <= z1 - RETURN p +```js +FOR p IN points + FILTER x0 <= p.x && p.x <= x1 + FILTER y0 <= p.y && p.y <= y1 + FILTER z0 <= p.z && p.z <= z1 + RETURN p +``` ### Possible range queries @@ -55,72 +60,80 @@ it from both sides, from one side only (i.e. only an upper or lower bound) or not bound it at all. Furthermore you can use any comparison operator. The index supports `<=` and `>=` -naturally, `==` will be translated to the bound `[c, c]`. Strict comparsion +naturally, `==` will be translated to the bound `[c, c]`. Strict comparison is translated to their non-strict counterparts and a post-filter is inserted. - FOR p IN points - FILTER 2 <= p.x && p.x < 9 - FILTER y0 >= 80 - FILTER p.z == 4 - RETURN p +```js +FOR p IN points + FILTER 2 <= p.x && p.x < 9 + FILTER y0 >= 80 + FILTER p.z == 4 + RETURN p +``` ### Example Use Case If you build a calendar using ArangoDB you could create a collection for each user -that contains her appointsments. The documents would roughly look as follows: +that contains her appointments. The documents would roughly look as follows: +```json { "from": 345365, "to": 678934, "what": "Dentist", } +``` -Where `from`/`to` are the timestamps when an appointment starts/ends. Having an -multi-dimensional index on the fields - - ["from", "to"] - -allows you to query effeciently for all appointsments within a given time range. +`from`/`to` are the timestamps when an appointment starts/ends. Having an +multi-dimensional index on the fields `["from", "to"]` allows you to query +for all appointments within a given time range efficiently. #### Finding all appointments within a time range + Given a time range `[f, t]` we want to find all appointments `[from, to]` that are completely contained in `[f, t]`. Those appointments clearly satisfy the condition - f <= from and to <= t +``` +f <= from and to <= t +``` Thus our query would be: - FOR app IN appointments - FILTER f <= app.from - FILTER app.to <= t - RETURN app - +```js +FOR app IN appointments + FILTER f <= app.from + FILTER app.to <= t + RETURN app +``` #### Finding all appointments that intersect a time range + Given a time range `[f, t]` we want to find all appointments `[from, to]` that -intersect `[f, t]`. Two intervals `[a_1, b_1]` and `[a_2, b_2]` intersect if +intersect `[f, t]`. Two intervals `[f, t]` and `[from, to]` intersect if and only if - a_2 <= b_1 and a_1 <= b_2 +``` +a_2 <= b_1 and a_1 <= b_2 +``` Thus our query would be: - FOR app IN appointments - FILTER f <= app.to - FILTER app.from <= t - RETURN app - +```js +FOR app IN appointments + FILTER f <= app.to + FILTER app.from <= t + RETURN app +``` ### Limitations Currently there are a few limitations: -- Using array expansions for attributes is not possible. +- 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 lead -to a high number of seeks. This behavior is typical for indexing using space -filling curves. - +- The performance can vary depending on the dataset. Densely packed points can + lead to a high number of seeks. This behavior is typical for indexing using + space filling curves. From a4b1d9c135b37fbe83465cf800b86f9231f26195 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Mon, 20 Sep 2021 19:08:50 +0200 Subject: [PATCH 12/14] Remove mention of volatile skiplist indexes --- 3.7/indexing-persistent.md | 2 -- 3.8/indexing-persistent.md | 2 -- 3.9/indexing-persistent.md | 2 -- 3 files changed, 6 deletions(-) diff --git a/3.7/indexing-persistent.md b/3.7/indexing-persistent.md index 50d34fc4ae..5dcb5e567f 100644 --- a/3.7/indexing-persistent.md +++ b/3.7/indexing-persistent.md @@ -184,5 +184,3 @@ the sort order of those which are returned can be wrong (whenever the persistent index is consulted). To fix persistent indexes after a language change, delete and re-create them. -Skiplist indexes are not affected, because they are not persisted and -automatically rebuilt on every server start. diff --git a/3.8/indexing-persistent.md b/3.8/indexing-persistent.md index 50d34fc4ae..5dcb5e567f 100644 --- a/3.8/indexing-persistent.md +++ b/3.8/indexing-persistent.md @@ -184,5 +184,3 @@ the sort order of those which are returned can be wrong (whenever the persistent index is consulted). To fix persistent indexes after a language change, delete and re-create them. -Skiplist indexes are not affected, because they are not persisted and -automatically rebuilt on every server start. diff --git a/3.9/indexing-persistent.md b/3.9/indexing-persistent.md index 50d34fc4ae..5dcb5e567f 100644 --- a/3.9/indexing-persistent.md +++ b/3.9/indexing-persistent.md @@ -184,5 +184,3 @@ the sort order of those which are returned can be wrong (whenever the persistent index is consulted). To fix persistent indexes after a language change, delete and re-create them. -Skiplist indexes are not affected, because they are not persisted and -automatically rebuilt on every server start. From d0c30cd9848a10ddf443ebaa3b81aab093d42c6b Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Mon, 20 Sep 2021 19:14:56 +0200 Subject: [PATCH 13/14] More formatting --- 3.9/indexing-which-index.md | 20 +++++++++++++------- 3.9/indexing.md | 2 +- _data/3.8-http.yml | 2 -- 3 files changed, 14 insertions(+), 10 deletions(-) diff --git a/3.9/indexing-which-index.md b/3.9/indexing-which-index.md index a5dc091755..02d1877228 100644 --- a/3.9/indexing-which-index.md +++ b/3.9/indexing-which-index.md @@ -94,17 +94,23 @@ different usage scenarios: result TTL indexes will likely not be used for filtering and sort operations in user-land AQL queries. -- **multi-dimensional index**: a multi dimensional index allows to efficiently intersect - multiple range queries. Typical use cases are querying intervals that intersect - a given point or interval, e.g. if intervals look like +- **multi-dimensional index** (ZKD): a multi dimensional index allows to + efficiently intersect multiple range queries. Typical use cases are querying + intervals that intersect a given point or interval. For example, if intervals + are stored in documents like - { "from": 12, "to": 45 } + ```json + { "from": 12, "to": 45 } + ``` - with an index on `from, to` can be used to query via + then you can create an index over `from, to` utilize it with this query: - FOR i IN intervals FILTER i.from <= t && t <= i.to RETURN i + ```js + FOR i IN intervals FILTER i.from <= t && t <= i.to RETURN i + ``` - Currently only doubles are supported as underlying type for each dimension. + Currently only floating-point numbers (doubles) are supported as underlying + type for each dimension. - **Geo index**: the geo index provided by ArangoDB allows searching for documents within a radius around a two-dimensional earth coordinate (point), or to diff --git a/3.9/indexing.md b/3.9/indexing.md index f599716fa8..7144e28c0c 100644 --- a/3.9/indexing.md +++ b/3.9/indexing.md @@ -16,6 +16,6 @@ There are special sections for - [Persistent Indexes](indexing-persistent.html) - [TTL Indexes](indexing-ttl.html) - [Fulltext Indexes](indexing-fulltext.html) - - [Multidimensional Indexes](indexing-multi-dim.html) + - [Multi-dimensional Indexes](indexing-multi-dim.html) - [Geo-spatial Indexes](indexing-geo.html) - [Vertex-centric Indexes](indexing-vertex-centric.html) diff --git a/_data/3.8-http.yml b/_data/3.8-http.yml index cc766d54cb..e643f8f27f 100644 --- a/_data/3.8-http.yml +++ b/_data/3.8-http.yml @@ -86,8 +86,6 @@ href: indexes-persistent.html - text: TTL href: indexes-ttl.html - - text: Multi-dimensional - href: indexes-multi-dim.html - text: Geo-Spatial href: indexes-geo.html - text: Fulltext From b29c16b25b195f2644686a14b79d910efa7ffc5d Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Mon, 20 Sep 2021 19:17:47 +0200 Subject: [PATCH 14/14] Tweak structure a little --- 3.9/indexing-multi-dim.md | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/3.9/indexing-multi-dim.md b/3.9/indexing-multi-dim.md index 9e473c6282..cec81311f4 100644 --- a/3.9/indexing-multi-dim.md +++ b/3.9/indexing-multi-dim.md @@ -1,21 +1,17 @@ --- layout: default -description: This is an introduction to ArangoDB's multi-dimensional indexes +description: A multi dimensional index allows to efficiently intersect multiple range queries --- -Multi-dimensional indexes -========================= +# Multi-dimensional indexes -Introduction to Multi-dimensional Indexes ------------------------------------------ - -The multi-dimensional index type provided by ArangoDB can be used to efficiently -intersect multiple range queries. +The multi-dimensional index type (also called ZKD) provided by ArangoDB can be +used to efficiently intersect multiple range queries. A multi-dimensional index is setup by setting the index type to `"zkd"`. The `fields` attribute describes which fields are used as dimensions. The value of each dimension has to be a numeric (double) value. -### Querying documents within a 3D box +## Querying documents within a 3D box Assume we have documents in a collection `points` of the form @@ -52,7 +48,7 @@ FOR p IN points RETURN p ``` -### Possible range queries +## Possible range queries Having an index on a set of fields does not require you to specify a full range for every field. For each field you can decide if you want to bound @@ -71,7 +67,7 @@ FOR p IN points RETURN p ``` -### Example Use Case +## Example Use Case If you build a calendar using ArangoDB you could create a collection for each user that contains her appointments. The documents would roughly look as follows: @@ -88,7 +84,7 @@ that contains her appointments. The documents would roughly look as follows: multi-dimensional index on the fields `["from", "to"]` allows you to query for all appointments within a given time range efficiently. -#### Finding all appointments within a time range +### Finding all appointments within a time range Given a time range `[f, t]` we want to find all appointments `[from, to]` that are completely contained in `[f, t]`. Those appointments clearly satisfy the @@ -107,7 +103,7 @@ FOR app IN appointments RETURN app ``` -#### Finding all appointments that intersect a time range +### Finding all appointments that intersect a time range Given a time range `[f, t]` we want to find all appointments `[from, to]` that intersect `[f, t]`. Two intervals `[f, t]` and `[from, to]` intersect if @@ -126,7 +122,7 @@ FOR app IN appointments RETURN app ``` -### Limitations +## Limitations Currently there are a few limitations: