Named indices

CHANGELOG

@@ -1,6 +1,10 @@
 devel
 -----
 
+* added "name" property for indices
+
+  If a name is not specified on index creation, one will be auto-generated.
+
 * Under normal circumstances there should be no need to connect to a 
   database server in a cluster with one of the client tools, and it is 
   likely that any user operations carried out there with one of the client
@@ -9,7 +13,7 @@ devel
   The client tools arangosh, arangodump and arangorestore will now emit 
   a warning when connecting with them to a database server node in a cluster.
 
-* fix compation behaviour of followers
+* fix compation behavior of followers
 
 * added "random" masking to mask any data type, added wildcard masking
 
@@ -81,28 +85,28 @@ devel
 
 * `--query.registry-ttl` is now honored in single-server mode, and cursor TTLs
   are now honored on DBServers in cluster mode
-  
-* add "TTL" index type, for optional auto-expiration of documents 
+
+* add "TTL" index type, for optional auto-expiration of documents
 
 * disable selection of index types "persistent" and "skiplist" in the web
   interface when using the RocksDB engine. The index types "hash", "skiplist"
   and "persistent" are just aliases of each other with the RocksDB engine,
   so there is no need to offer all of them.
 
-* fixed JS AQL query objects with empty query strings not being recognized 
+* fixed JS AQL query objects with empty query strings not being recognized
   as AQL queries
 
 * update V8 to 7.1.302.28
 
-  New V8 behavior introduced herein: 
+  New V8 behavior introduced herein:
 
   - ES2016 changed the default timezone of date strings to be conditional on
     whether a time part is included. The semantics were a compromise approach
     based on web compatibility feedback from V8, but until now, we have been
     shipping ES5.1 default timezone semantics. This patch implements the
     new semantics, following ChakraCore and SpiderMonkey (though JSC
     implements V8's previous semantics).
- 
+
 * fixed JS AQL query objects with empty query strings not being recognized as AQL queries
 
 * report run-time openssl version (for dynamically linked executables)
@@ -121,7 +125,7 @@ devel
 
 * upgraded to OpenSSL 1.1.0j
 
-* added configurable masking of dumped data via `arangodump` tool to obfuscate 
+* added configurable masking of dumped data via `arangodump` tool to obfuscate
   exported sensible data
 
 * fixed arangoimp script for MacOSX CLI Bundle
@@ -140,7 +144,7 @@ devel
 * fix issue #7903: Regression on ISO8601 string compatibility in AQL
 
   millisecond parts of AQL date values were limited to up to 3 digits.
-  Now the length of the millisecond part is unrestricted, but the 
+  Now the length of the millisecond part is unrestricted, but the
   millisecond precision is still limited to up to 3 digits.
 
 * the RocksDB primary index can now be used by the optimizer to optimize queries
@@ -150,7 +154,7 @@ devel
   sorted when sorting documents by their `_key` values.
 
   Previous versions of ArangoDB tried to interpret `_key` values as numeric values if
-  possible and sorted by these. That previous sort strategy never used an index and 
+  possible and sorted by these. That previous sort strategy never used an index and
   could have caused unnecessary overhead. The new version will now use an index for
   sorting for the RocksDB engine, but may change the order in which documents are
   shown in the web UI (e.g. now a `_key` value of "10" will be shown before a `_key`

Documentation/Books/Drivers/JS/Reference/Collection/Indexes.md

@@ -227,7 +227,8 @@ Fetches information about the index with the given _indexHandle_ and returns it.
 
   The handle of the index to look up. This can either be a fully-qualified
   identifier or the collection-specific key of the index. If the value is an
-  object, its _id_ property will be used instead.
+  object, its _id_ property will be used instead. Alternatively, the index
+  may be looked up by name.
 
 **Examples**
 
@@ -243,6 +244,12 @@ assert.equal(result.id, index.id);
 
 const result = await collection.index(index.id.split("/")[1]);
 assert.equal(result.id, index.id);
+
+// -- or --
+
+const result = await collection.index(index.name);
+assert.equal(result.id, index.id);
+assert.equal(result.name, index.name);
 // result contains the properties of the index
 ```
 

Documentation/Books/Manual/Indexing/WorkingWithIndexes.md

@@ -7,8 +7,8 @@ Learn how to use different indexes efficiently by going through the
 Index Identifiers and Handles
 -----------------------------
 
-An *index handle* uniquely identifies an index in the database. It is a string and 
-consists of the collection name and an *index identifier* separated by a `/`. The 
+An *index handle* uniquely identifies an index in the database. It is a string and
+consists of the collection name and an *index identifier* separated by a `/`. The
 index identifier part is a numeric value that is auto-generated by ArangoDB.
 
 A specific index of a collection can be accessed using its *index handle* or
@@ -35,6 +35,15 @@ Because the index handle is unique within the database, you can leave out the
 db._index("demo/362549736");
 ```
 
+An index may also be looked up by its name. Since names are only unique within
+a collection, rather than within the database, the lookup must also include the
+collection name.
+
+```js
+db._index("demo/primary")
+db.demo.index("primary")
+```
+
 Collection Methods
 ------------------
 
@@ -86,6 +95,10 @@ Other attributes may be necessary, depending on the index type.
 - *fulltext*: fulltext index
 - *geo*: geo index, with _one_ or _two_ attributes
 
+**name** can be a string. Index names are subject to the same character
+restrictions as collection names. If omitted, a name will be auto-generated so
+that it is unique with respect to the collection, e.g. `idx_832910498`.
+
 **sparse** can be *true* or *false*.
 
 For *hash*, and *skiplist* the sparsity can be controlled, *fulltext* and *geo*
@@ -98,7 +111,7 @@ object existed before the call is indicated in the return attribute
 *isNewlyCreated*.
 
 **deduplicate** can be *true* or *false* and is supported by array indexes of
-type *hash* or *skiplist*. It controls whether inserting duplicate index values 
+type *hash* or *skiplist*. It controls whether inserting duplicate index values
 from the same document into a unique array index will lead to a unique constraint
 error or not. The default value is *true*, so only a single instance of each
 non-unique index value will be inserted into the index per document. Trying to
@@ -248,7 +261,7 @@ finds an index
 So you've created an index, and since its maintainance isn't for free,
 you definitely want to know whether your query can utilize it.
 
-You can use explain to verify whether **skiplists** or **hash indexes** are 
+You can use explain to verify whether **skiplists** or **hash indexes** are
 used (if you omit `colors: false` you will get nice colors in ArangoShell):
 
     @startDocuBlockInline IndexVerify
@@ -260,4 +273,3 @@ used (if you omit `colors: false` you will get nice colors in ArangoShell):
     ~db._drop("example");
     @END_EXAMPLE_ARANGOSH_OUTPUT
     @endDocuBlock IndexVerify
-

Documentation/Books/Manual/ReleaseNotes/NewFeatures35.md

@@ -214,6 +214,15 @@ entries, and will continue to work.
 
 Existing `_modules` collections will also remain functional.
 
+### Named indices
+
+Indices now have an additional `name` field, which allows for more useful
+identifiers. System indices, like the primary and edge indices, have default 
+names (`primary` and `edge`, respectively). If no `name` value is specified
+on index creation, one will be auto-generated (e.g. `idx_13820395`). The index
+name _cannot_ be changed after index creation. No two indices on the same
+collection may share the same name, but two indices on different collections 
+may.
 
 Client tools
 ------------

Documentation/Books/Manual/ReleaseNotes/UpgradingChanges35.md

@@ -56,3 +56,14 @@ undefined.
 This change is about making queries as the above fail with a parse error, as an 
 unknown variable `key1` is accessed here, avoiding the undefined behavior. This is 
 also in line with what the documentation states about variable invalidation.
+
+Miscellaneous
+-------------
+
+### Index creation
+
+In previous versions of ArangoDB, if one attempted to create an index with a
+specified `_id`, and that `_id` was already in use, the server would typically
+return the existing index with matching `_id`. This is somewhat unintuitive, as
+it would ignore if the rest of the definition did not match. This behavior has
+been changed so that the server will now return a duplicate identifier error.

Documentation/DocuBlocks/Rest/Indexes/post_api_index.md

@@ -32,6 +32,10 @@ Indexing the system attribute *_id* is not supported for user-defined indexes.
 Manually creating an index using *_id* as an index attribute will fail with 
 an error.
 
+Optionally, an index name may be specified as a string in the *name* attribute.
+Index names have the same restrictions as collection names. If no value is
+specified, one will be auto-generated.
+
 Some indexes can be created as unique or non-unique variants. Uniqueness
 can be controlled for most indexes by specifying the *unique* flag in the
 index details. Setting it to *true* will create a unique index.
@@ -76,4 +80,3 @@ target index will not support, then an *HTTP 400* is returned.
 @RESTRETURNCODE{404}
 If *collection* is unknown, then an *HTTP 404* is returned.
 @endDocuBlock
-