diff --git a/CHANGELOG b/CHANGELOG index b751475b94..6c913b6e9b 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -10,7 +10,7 @@ v3.0.0 (XXXX-XX-XX) The operator is currently implemented by calling the already existing AQL function `LIKE`. - This change also makes `LIKE` an AQL keyword. Using `like` in either case as + This change also makes `LIKE` an AQL keyword. Using `LIKE` in either case as an attribute or collection name in AQL thus requires quoting. * make AQL optimizer rule "remove-unnecessary-calculations" fire in more cases diff --git a/Documentation/Books/Users/AqlOperations/Insert.mdpp b/Documentation/Books/Users/AqlOperations/Insert.mdpp index 69173180e6..74df65f1dd 100644 --- a/Documentation/Books/Users/AqlOperations/Insert.mdpp +++ b/Documentation/Books/Users/AqlOperations/Insert.mdpp @@ -65,7 +65,7 @@ To refer to the inserted documents, the `INSERT` statement introduces a pseudo-v named `NEW`. The documents contained in `NEW` will contain all attributes, even those auto-generated by -the database (e.g. `_id`, `_key`, `_rev`, `_from`, and `_to`). +the database (e.g. `_id`, `_key`, `_rev`). ``` diff --git a/Documentation/Books/Users/AqlOperations/Replace.mdpp b/Documentation/Books/Users/AqlOperations/Replace.mdpp index fa40291d82..7d9c7b3a45 100644 --- a/Documentation/Books/Users/AqlOperations/Replace.mdpp +++ b/Documentation/Books/Users/AqlOperations/Replace.mdpp @@ -9,8 +9,7 @@ Each *REPLACE* operation is restricted to a single collection, and the Only a single *REPLACE* statement per collection is allowed per AQL query, and it cannot be followed by read operations that access the same collection, by traversal operations, or AQL functions that can read documents. -The system attributes of documents (*_key*, *_id*, *_from*, *_to*, *_rev*) cannot be -replaced. +The system attributes *_id*, *_key* and *_rev* cannot be replaced, *_from* and *_to* can. The two syntaxes for a replace operation are: diff --git a/Documentation/Books/Users/AqlOperations/Update.mdpp b/Documentation/Books/Users/AqlOperations/Update.mdpp index 48827a7918..3aaa5ea60d 100644 --- a/Documentation/Books/Users/AqlOperations/Update.mdpp +++ b/Documentation/Books/Users/AqlOperations/Update.mdpp @@ -9,8 +9,7 @@ Each *UPDATE* operation is restricted to a single collection, and the Only a single *UPDATE* statement per collection is allowed per AQL query, and it cannot be followed by read operations that access the same collection, by traversal operations, or AQL functions that can read documents. -The system attributes of documents (*_key*, *_id*, *_from*, *_to*, *_rev*) cannot be -updated. +The system attributes *_id*, *_key* and *_rev* cannot be updated, *_from* and *_to* can. The two syntaxes for an update operation are: diff --git a/Documentation/Books/Users/AqlOperations/Upsert.mdpp b/Documentation/Books/Users/AqlOperations/Upsert.mdpp index 02f869d0ed..845091a8bb 100644 --- a/Documentation/Books/Users/AqlOperations/Upsert.mdpp +++ b/Documentation/Books/Users/AqlOperations/Upsert.mdpp @@ -24,8 +24,7 @@ updated or added. When using the *REPLACE* variant of upsert, existing documents be replaced with the contexts of *update-expression*. Updating a document will modify the document's revision number with a server-generated value. -The system attributes of documents (*_key*, *_id*, *_from*, *_to*, *_rev*) cannot be -updated. +The system attributes *_id*, *_key* and *_rev* cannot be updated, *_from* and *_to* can. The *search-expression* contains the document to be looked for. It must be an object literal without dynamic attribute names. In case no such document can be found in diff --git a/Documentation/Books/Users/Documents/DocumentMethods.mdpp b/Documentation/Books/Users/Documents/DocumentMethods.mdpp index 94d4563306..6b1c04d161 100644 --- a/Documentation/Books/Users/Documents/DocumentMethods.mdpp +++ b/Documentation/Books/Users/Documents/DocumentMethods.mdpp @@ -837,8 +837,8 @@ replaces documents matching an example Replaces all documents matching an example with a new document body. The entire document body of each document matching the *example* will be -replaced with *newValue*. The document meta-attributes such as *_id*, -*_key*, *_from*, *_to* will not be replaced. +replaced with *newValue*. The document meta-attributes *_id*, *_key* and +*_rev* will not be replaced. `collection.replaceByExample(document, newValue, waitForSync)` @@ -884,8 +884,7 @@ partially updates documents matching an example Partially updates all documents matching an example with a new document body. Specific attributes in the document body of each document matching the *example* will be updated with the values from *newValue*. -The document meta-attributes such as *_id*, *_key*, *_from*, -*_to* cannot be updated. +The document meta-attributes *_id*, *_key* and *_rev* cannot be updated. Partial update could also be used to append new fields, if there were no old field with same name. diff --git a/Documentation/Books/Users/Edges/README.mdpp b/Documentation/Books/Users/Edges/README.mdpp index 6962b73c78..cf0198a206 100644 --- a/Documentation/Books/Users/Edges/README.mdpp +++ b/Documentation/Books/Users/Edges/README.mdpp @@ -9,8 +9,8 @@ A graph data model always consists of at least two collections: the relations be nodes in the graphs are stored in an "edges collection", the nodes in the graph are stored in documents in regular collections. -Edges in ArangoDB are special documents. In addition to the internal -attributes *_key*, *_id* and *_rev*, they have two attributes *_from* and *_to*, +Edges in ArangoDB are special documents. In addition to the system +attributes *_key*, *_id* and *_rev*, they have the attributes *_from* and *_to*, which contain [document handles](../Glossary/README.md#document-handle), namely the start-point and the end-point of the edge. *Example*: @@ -21,9 +21,6 @@ which contain [document handles](../Glossary/README.md#document-handle), namely - *_from* is the [document handle](../Glossary/README.md#document-handle) of the linked vertex (incoming relation) - *_to* is the document handle of the linked vertex (outgoing relation) -The values of *_from* and *_to* are immutable once as edge was saved - thus you will not be able to update them. - - [Edge collections](../Glossary/README.md#edge-collection) are special collections that store edge documents. Edge documents are connection documents that reference other documents. The type of a collection must be specified when a collection is created and cannot be changed afterwards. diff --git a/Documentation/Books/Users/Glossary/README.mdpp b/Documentation/Books/Users/Glossary/README.mdpp index cf493af98d..af54ccfd30 100644 --- a/Documentation/Books/Users/Glossary/README.mdpp +++ b/Documentation/Books/Users/Glossary/README.mdpp @@ -103,9 +103,7 @@ ArangoDB currently uses 64bit unsigned integer values to maintain document revis !SUBSECTION Edge -Edges are special documents used for connecting other documents into a graph. An edge describes the connection between two documents using the internal attributes: _from and _to. These contain document handles, namely the start-point and the end-point of the edge. - -The values of _from and _to are immutable once saved. +Edges are special documents used for connecting other documents into a graph. An edge describes the connection between two documents using the internal attributes: `_from` and `_to`. These contain document handles, namely the start-point and the end-point of the edge. !SUBSECTION Edge Collection @@ -127,15 +125,15 @@ Named graphs enforce consistency between edge collections and vertex collections Indexes are used to allow fast access to documents in a collection. All collections have a primary index, which is the document's _key attribute. This index cannot be dropped or changed. -Edge collections will also have an automatically created edges index, which cannot be modified. This index provides quick access to documents via the _from and _to attributes. +Edge collections will also have an automatically created edges index, which cannot be modified. This index provides quick access to documents via the `_from` and `_to` attributes. Most user-land indexes can be created by defining the names of the attributes which should be indexed. Some index types allow indexing just one attribute (e.g. fulltext index) whereas other index types allow indexing multiple attributes. -Indexing system attributes such as _id, _key, _from, and _to in user-defined indexes is not supported by any index type. Manually creating an index that relies on any of these attributes is unsupported. +Indexing the system attribute `_id` in user-defined indexes is not supported by any index type. !SUBSECTION Edges Index -An edges index is automatically created for edge collections. It contains connections between vertex documents and is invoked when the connecting edges of a vertex are queried. There is no way to explicitly create or delete edge indexes. +An edges index is automatically created for edge collections. It contains connections between vertex documents and is invoked when the connecting edges of a vertex are queried. There is no way to explicitly create or delete edges indexes. !SUBSECTION Fulltext Index diff --git a/Documentation/Books/Users/HttpIndexes/README.mdpp b/Documentation/Books/Users/HttpIndexes/README.mdpp index 4ff67fc5df..c751239142 100644 --- a/Documentation/Books/Users/HttpIndexes/README.mdpp +++ b/Documentation/Books/Users/HttpIndexes/README.mdpp @@ -8,11 +8,11 @@ general. There are special sections for various index types. !SUBSUBSECTION Index Indexes are used to allow fast access to documents. For each collection there is always the primary index which is a hash index for the [document key](../Glossary/README.md#document-key) (_key attribute). This index cannot be dropped or changed. -[edge collections](../Glossary/README.md#edge-collection) will also have an automatically created edges index, which cannot be modified. This index provides quick access to documents via the _from and _to attributes. +[edge collections](../Glossary/README.md#edge-collection) will also have an automatically created edges index, which cannot be modified. This index provides quick access to documents via the `_from` and `_to` attributes. Most user-land indexes can be created by defining the names of the attributes which should be indexed. Some index types allow indexing just one attribute (e.g. fulltext index) whereas other index types allow indexing multiple attributes. -Indexing system attributes such as _id, _key, _from, and _to in user-defined indexes is not supported by any index type. Manually creating an index that relies on any of these attributes is unsupported. +Using the system attribute `_id` in user-defined indexes is not supported by any index type. !SUBSUBSECTION Index Handle diff --git a/Documentation/Books/Users/IndexHandling/IndexBasics.mdpp b/Documentation/Books/Users/IndexHandling/IndexBasics.mdpp index f277f82e7e..91307480ec 100644 --- a/Documentation/Books/Users/IndexHandling/IndexBasics.mdpp +++ b/Documentation/Books/Users/IndexHandling/IndexBasics.mdpp @@ -13,8 +13,8 @@ other index types allow indexing multiple attributes at the same time. The system attributes `_id`, `_key`, `_from` and `_to` are automatically indexed by ArangoDB, without the user being required to create extra indexes for them. -Therefore, indexing `_id`, `_key`, `_rev`, `_from`, and `_to` in a user-defined -index is often not required and is currently not supported by ArangoDB. +Using the system attribute `_id` in user-defined indexes is not possible, but +indexing `_key`, `_rev`, `_from`, and `_to` is. ArangoDB provides the following index types: diff --git a/Documentation/Books/Users/NamingConventions/AttributeNames.mdpp b/Documentation/Books/Users/NamingConventions/AttributeNames.mdpp index 9f139218bd..b91b42a598 100644 --- a/Documentation/Books/Users/NamingConventions/AttributeNames.mdpp +++ b/Documentation/Books/Users/NamingConventions/AttributeNames.mdpp @@ -24,11 +24,10 @@ following attribute naming constraints are not violated: portability, special characters should be avoided though. For example, attribute names may contain the dot symbol, but the dot has a special meaning in JavaScript and also in AQL, so when using such attribute names in one of - these languages, the attribute name would need to be quoted by the end - user. This will work but requires more work so it might be better to use - attribute names which don't require any quoting/escaping in all languages - used. This includes languages used by the client (e.g. Ruby, PHP) if the - attributes are mapped to object members there. + these languages, the attribute name needs to be quoted by the end user. + Overall it might be better to use attribute names which don't require any + quoting/escaping in all languages used. This includes languages used by the + client (e.g. Ruby, PHP) if the attributes are mapped to object members there. * Attribute names starting with an at-mark (*@*) will need to be enclosed in backticks when used in an AQL query to tell them apart from bind variables. Therefore we do not encourage the use of attributes starting with at-marks, @@ -36,23 +35,6 @@ following attribute naming constraints are not violated: * ArangoDB does not enforce a length limit for attribute names. However, long attribute names may use more memory in result sets etc. Therefore the use of long attribute names is discouraged. -* As ArangoDB saves document attribute names separate from the actual document - attribute value data, the combined length of all attribute names for a - document must fit into an ArangoDB shape structure. The maximum combined names - length is variable and depends on the number and data types of attributes - used. * Attribute names are case-sensitive. -* Attribute names should not include the NUL byte (`\u0000`), as names will be - truncated at the first NUL byte. -* Attributes with empty names (the empty string) are removed from the document - when saving it. - - When the document is later requested, it will be returned without these - attributes. For example, if this document is saved: - - { "a" : 1, "" : 2, "b": 3 } - - and later requested, it will be returned like this: - - { "a" : 1, "b": 3 } +* Attributes with empty names (the empty string) are disallowed. diff --git a/Documentation/Books/Users/Upgrading/UpgradingChanges30.mdpp b/Documentation/Books/Users/Upgrading/UpgradingChanges30.mdpp index 597fd6d71d..e0b51d79b4 100644 --- a/Documentation/Books/Users/Upgrading/UpgradingChanges30.mdpp +++ b/Documentation/Books/Users/Upgrading/UpgradingChanges30.mdpp @@ -3,6 +3,47 @@ It is recommended to check the following list of incompatible changes **before** upgrading to ArangoDB 3.0, and adjust any client programs if necessary. +!SECTION Datafiles and datafile names + +ArangoDB 3.0 uses a new VelocyPack-based format for storing data in WAL logfiles +and collection datafiles. The file format is not compatible with the files used +in prior versions of ArangoDB. That means datafiles written by ArangoDB 3.0 cannot be +used in earlier versions and vice versa. + +The pattern for collection directory names was changed in 3.0 to include a random +id component at the end. The new pattern is `collection--`, where `` +is the collection id and `` is a random number. Previous versions of ArangoDB +used a pattern `collection-` without the random number. + + +!SECTION Edges and edges attributes + +In ArangoDB prior to 3.0 the attributes `_from` and `_to` of edges were treated +specially when loading or storing edges. That special handling led to these attributes +being not as flexible as regular document attributes. For example, the `_from` and +`_to` attribute values of an existing edge could not be updated once the edge was +created. Additionally, the `_from` and `_to` attributes could not be indexed in +user-defined indexes, e.g. to make each combination of `_from` and `_to` unique. +Finally, as `_from` and `_to` referenced the linked collections by collection id +and not by collection name, their meaning became unclear once a referenced collection +was dropped. The collection id stored in edges then became unusable, and when +accessing such edge the collection name part of it was always translated to `_undefined`. + +In ArangoDB 3.0, the `_from` and `_to` values of edges are saved as regular strings. +This allows using `_from` and `_to` in user-defined indexes. Additionally this allows +updating the `_from` and `_to` values of existing edges. Furthermore, collections +referenced by `_from` and `_to` values may be dropped and re-created later. Any +`_from` and `_to` values of edges pointing to such dropped collection are unaffected +by the drop operation now. + + +!SECTION AQL + +`LIKE` is now a keyword in AQL. Using `LIKE` in either case as an attribute or collection +name in AQL queries now requires quoting. + +The AQL optimizer rule "merge-traversal-filter" was renamed to "optimize-traversals". + !SECTION Command Line Options @@ -104,6 +145,11 @@ previous versions of ArangoDB, this route was accessible from within the `_syste database only, and an HTTP 403 (Forbidden) was thrown by the server for any access from within another database. +The undocumented HTTP REST endpoints `/_open/cerberus` and `/_system/cerberus` have +been removed. These endpoints have been used by some ArangoDB-internal applications +and were not part of ArangoDB's public API. + + !SECTION Miscellaneous changes The checksum calculation algorithm for the `collection.checksum()` method and its