Added documentation for feature/disallow-smart-index-fields (#1086)

* Added documentation for feature/disallow-smart-index-fields * Review, add remark about dots in index fields too * Add to API changes * applied to 3.11 Co-authored-by: ansoboleva <93702078+ansoboleva@users.noreply.github.com> Co-authored-by: Simran Spiller <simran@arangodb.com>

Author: 3 people

3.10/indexing-index-basics.md

@@ -23,8 +23,17 @@ by ArangoDB, without the user being required to create extra indexes for them.
 `_id` and `_key` are covered by a collection's primary key, and `_from` and `_to`
 are covered by an edge collection's edge index automatically.
 
-Using the system attribute `_id` in user-defined indexes is not possible, but 
-indexing `_key`, `_rev`, `_from`, and `_to` is.
+You cannot use the `_id` system attribute in user-defined indexes, but indexing
+`_key`, `_rev`, `_from`, and `_to` is possible.
+
+You cannot index fields that contain `.` in their attribute names because dots
+are interpreted as paths of nested attributes. For example, `fields: ["foo.bar"]`
+indexes the value of the nested attribute `bar` under the top-level attribute
+`foo` (`{ "foo": { "bar": "value" } }`) and not a top-level attribute
+`foo.bar` (`{ "foo.bar": "value" }`).
+
+You can also not index fields whose names either start or end with `:`, for
+example, `fields: ["foo:"]`. This notation is reserved for internal use.
 
 Creating new indexes is by default done under an exclusive collection lock. The collection is not
 available while the index is being created. This "foreground" index creation can be undesirable, 

3.11/indexing-index-basics.md

@@ -23,8 +23,17 @@ by ArangoDB, without the user being required to create extra indexes for them.
 `_id` and `_key` are covered by a collection's primary key, and `_from` and `_to`
 are covered by an edge collection's edge index automatically.
 
-Using the system attribute `_id` in user-defined indexes is not possible, but 
-indexing `_key`, `_rev`, `_from`, and `_to` is.
+You cannot use the `_id` system attribute in user-defined indexes, but indexing
+`_key`, `_rev`, `_from`, and `_to` is possible.
+
+You cannot index fields that contain `.` in their attribute names because dots
+are interpreted as paths of nested attributes. For example, `fields: ["foo.bar"]`
+indexes the value of the nested attribute `bar` under the top-level attribute
+`foo` (`{ "foo": { "bar": "value" } }`) and not a top-level attribute
+`foo.bar` (`{ "foo.bar": "value" }`).
+
+You can also not index fields whose names either start or end with `:`, for
+example, `fields: ["foo:"]`. This notation is reserved for internal use.
 
 Creating new indexes is by default done under an exclusive collection lock. The collection is not
 available while the index is being created. This "foreground" index creation can be undesirable, 

3.11/release-notes-api-changes311.md

@@ -29,7 +29,14 @@ integrations for ArangoDB 3.11.
 
 ### Endpoints augmented
 
+#### Restriction of indexable fields
 
+It is now forbidden to create indexes that cover fields whose attribute names
+start or end with `:` , for example, `fields: ["value:"]`. This notation is
+reserved for internal use.
+
+Existing indexes are not affected but you cannot create new indexes with a
+preceding or trailing colon using the `POST /_api/index` endpoint.
 
 ### Endpoints moved
 

3.11/release-notes-upgrading-changes311.md

@@ -10,3 +10,12 @@ upgrading to ArangoDB 3.11, and adjust any client programs if necessary.
 
 The following incompatible changes have been made in ArangoDB 3.11:
 
+Restriction of indexable fields
+-------------------------------
+
+It is now forbidden to create indexes that cover fields whose attribute names
+start or end with `:` , for example, `fields: ["value:"]`. This notation is
+reserved for internal use.
+
+Existing indexes are not affected but you cannot create new indexes with a
+preceding or trailing colon.

3.8/indexing-index-basics.md

@@ -23,8 +23,14 @@ by ArangoDB, without the user being required to create extra indexes for them.
 `_id` and `_key` are covered by a collection's primary key, and `_from` and `_to`
 are covered by an edge collection's edge index automatically.
 
-Using the system attribute `_id` in user-defined indexes is not possible, but 
-indexing `_key`, `_rev`, `_from`, and `_to` is.
+You cannot use the `_id` system attribute in user-defined indexes, but indexing
+`_key`, `_rev`, `_from`, and `_to` is possible.
+
+You cannot index fields that contain `.` in their attribute names because dots
+are interpreted as paths of nested attributes. For example, `fields: ["foo.bar"]`
+indexes the value of the nested attribute `bar` under the top-level attribute
+`foo` (`{ "foo": { "bar": "value" } }`) and not a top-level attribute
+`foo.bar` (`{ "foo.bar": "value" }`).
 
 Creating new indexes is by default done under an exclusive collection lock. The collection is not
 available while the index is being created. This "foreground" index creation can be undesirable, 

3.9/indexing-index-basics.md

@@ -23,8 +23,14 @@ by ArangoDB, without the user being required to create extra indexes for them.
 `_id` and `_key` are covered by a collection's primary key, and `_from` and `_to`
 are covered by an edge collection's edge index automatically.
 
-Using the system attribute `_id` in user-defined indexes is not possible, but 
-indexing `_key`, `_rev`, `_from`, and `_to` is.
+You cannot use the `_id` system attribute in user-defined indexes, but indexing
+`_key`, `_rev`, `_from`, and `_to` is possible.
+
+You cannot index fields that contain `.` in their attribute names because dots
+are interpreted as paths of nested attributes. For example, `fields: ["foo.bar"]`
+indexes the value of the nested attribute `bar` under the top-level attribute
+`foo` (`{ "foo": { "bar": "value" } }`) and not a top-level attribute
+`foo.bar` (`{ "foo.bar": "value" }`).
 
 Creating new indexes is by default done under an exclusive collection lock. The collection is not
 available while the index is being created. This "foreground" index creation can be undesirable,