Added handling of null and sparsity in the array index to the documentation

mchacki · mchacki · commit e9b858d2872d · 2015-10-27T13:23:38.000+01:00
diff --git a/Documentation/Books/Users/IndexHandling/IndexBasics.mdpp b/Documentation/Books/Users/IndexHandling/IndexBasics.mdpp
@@ -322,8 +322,46 @@ value `bar` will be inserted only once:
 db.posts.insert({ tags: [ "foobar", "bar", "bar" ] });
 ```
 
-If an array index is declared unique, the de-duplication of array values will happen before 
+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.
 
+If an array index is declared and you store documents that do not have an array at the specified attribute
+this document will not be inserted in the index. Hence the following objects will not be indexed:
+
+```js
+db.posts.ensureIndex({ type: "hash", fields: [ "tags[*]" ] });
+db.posts.insert({ something: "else" });
+db.posts.insert({ tags: null });
+db.posts.insert({ tags: "this is no array" });
+db.posts.insert({ tags: { content: [1, 2, 3] } });
+```
+
+An array index is able to index an explicit `null` value and when queried for it, it will only
+return those documents having explicitly `null` stored in the array, it will not return any
+documents that do not have the array at all.
+
+```js
+db.posts.ensureIndex({ type: "hash", fields: [ "tags[*]" ] });
+db.posts.insert({tags: null}) // Will not be indexed
+db.posts.insert({tags: []})  // Will not be indexed
+db.posts.insert({tags: [null]}); // Will be indexed for null
+db.posts.insert({tags: [null, 1, 2]}); // Will be indexed for null, 1 and 2
+```
+
+Declaring an array index as **sparse** does not have an effect on the array part of the index,
+this in particular means that explicit `null` values are also indexed in the **sparse** version.
+If an index is combined from an array and a normal attribute the sparsity will apply for the attribute e.g.:
+
+```js
+db.posts.ensureIndex({ type: "hash", fields: [ "tags[*]", "name" ], sparse: true });
+db.posts.insert({tags: null, name: "alice"}) // Will not be indexed
+db.posts.insert({tags: [], name: "alice"}) // Will not be indexed
+db.posts.insert({tags: [1, 2, 3]}) // Will not be indexed
+db.posts.insert({tags: [1, 2, 3], name: null}) // Will not be indexed
+db.posts.insert({tags: [1, 2, 3], name: "alice"})
+// Will be indexed for [1, "alice"], [2, "alice"], [3, "alice"]
+db.posts.insert({tags: [null], name: "bob"})
+// Will be indexed for [null, "bob"] 
+```
