From 1447a903e6c5fb523fcabe4567ee0a6e8866d18d Mon Sep 17 00:00:00 2001
From: Jan Steemann <jan@arangodb.com>
Date: Wed, 21 Oct 2015 18:06:09 +0200
Subject: [PATCH] note on array indexes

---
 .../Books/Users/IndexHandling/WhichIndex.mdpp | 46 +++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/Documentation/Books/Users/IndexHandling/WhichIndex.mdpp b/Documentation/Books/Users/IndexHandling/WhichIndex.mdpp
index 3726f88a01..1d8803519c 100644
--- a/Documentation/Books/Users/IndexHandling/WhichIndex.mdpp
+++ b/Documentation/Books/Users/IndexHandling/WhichIndex.mdpp
@@ -132,3 +132,49 @@ Note that if you intend to use [joins](../AqlExamples/Join.html) it may be cleve
 to use non-sparsity and maybe even uniqueness for that attribute, else all items containing
 the `null` value will match against each other and thus produce large results.
 
+
+!SUBSECTION Indexing array values
+
+If an index attribute contains an array, ArangoDB will store the entire array as the index value
+by default. Accessing individual members of the array via the index is not possible this
+way. 
+
+To make an index insert the individual array members into the index separately, an array index 
+needs to be created for the attribute. Array indexes can be set up like regular hash or
+skiplist indexes using the `collection.ensureIndex()` function. To make a hash or skiplist index 
+an array index, the index attribute name needs to be extended with <i>[\*]</i>.
+
+The following example creates an array hash index on the `tags` attribute in a collection named
+`posts`:
+
+```js
+db.posts.ensureIndex({ type: "hash", fields: [ "tags[*]" ] });
+```
+
+This array index can then be used for looking up individual `tags` values from AQL queries via 
+the `IN` operator and the attribute name extension <i>[\*]</i>:
+
+    FOR doc IN posts
+      FILTER 'foobar' IN doc.tags[*]
+      RETURN doc
+    
+The following FILTER conditions will not use the array index:
+      
+    FILTER 'foobar' IN doc.tags
+    FILTER doc.tags IN 'foobar'
+    FILTER doc.tags == 'foobar'
+    FILTER 'foobar' == doc.tags
+
+Array values will automatically be de-duplicated before being inserted into an array index.
+For example, if the following document is inserted into the collection, the duplicate array
+value `bar` will be inserted only once:
+
+```js
+db.posts.insert({ tags: [ "foobar", "bar", "bar" ] });
+```
+
+If an array index is declared unique, the de-duplication of array values will happen before 
+inserting the values into the index, so the above insert operation will not necessarily fail.
+It will fail if the index already contains an instance of the `bar` value, but will succeed 
+if the value `bar` is not already present in the index.
+