Merge branch 'devel' of github.com:arangodb/arangodb into devel

CHANGELOG

@@ -21,9 +21,15 @@ v2.8.0 (XXXX-XX-XX)
   tags array using the following AQL query:
     
       FOR doc IN colName 
-        FILTER "ArangoDB" IN doc.tags 
+        FILTER "ArangoDB" IN doc.tags[*] 
         RETURN doc
 
+* rewrote AQL query optimizer rule `use-index-range` and renamed it to `use-indexes`.
+  The name change affects rule names in the optimizer's output.
+
+* rewrote AQL execution node `IndexRangeNode` and renamed it to `IndexNode`. The name
+  change affects node names in the optimizer's explain output.
+
 * added convenience function `db._explain(query)` for human-readable explanation
   of AQL queries
 

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.
+