Add Vector Index syntax (WIP)

Author: simon-dew

modules/n1ql/pages/n1ql-language-reference/alterindex.adoc

@@ -62,6 +62,7 @@ image::n1ql-language-reference/alter-index.png["Syntax diagram: refer to source
 The ALTER INDEX statement provides two possible syntaxes for specifying the index and the keyspace where the index is located.
 
 // TODO: Automatic links in EBNF.
+// FIXME: Maybe try to make consistent with DROP INDEX
 
 [horizontal]
 index-name:: (Required) A unique name that identifies the index.
@@ -78,6 +79,13 @@ Refer to <<index-using>> below.
 index-with:: (Required) Specifies options for the index.
 Refer to <<index-with>> below.
 
+[[vector]]
+=== VECTOR Keyword
+
+FIXME: The optional VECTOR keyword indicates that you are altering a vector index.
+The VECTOR keyword is purely a visual mnemonic.
+There is no syntactic requirement to include the VECTOR keyword when altering a vector index.
+
 [[index-path]]
 === Index Path
 

modules/n1ql/pages/n1ql-language-reference/createindex.adoc

@@ -2,7 +2,7 @@
 :page-topic-type: reference
 :imagesdir: ../../assets/images
 :keywords: secondary, index, placement
-:description: The CREATE INDEX statement allows you to create a secondary index. \
+:description: FIXME: The CREATE INDEX statement allows you to create a secondary index. \
 Secondary indexes contain a filtered or a full set of keys in a given keyspace.
 
 :authorization-overview: xref:learn:security/authorization-overview.adoc
@@ -23,7 +23,7 @@ Secondary indexes contain a filtered or a full set of keys in a given keyspace.
 // TEMP
 include::partial$n1ql-language-reference/horizontal-style.adoc[]
 
-The `CREATE INDEX` statement allows you to create a secondary index.
+FIXME: The `CREATE INDEX` statement allows you to create a secondary index.
 Secondary indexes contain a filtered or a full set of keys in a given keyspace.
 Secondary indexes are optional but increase query efficiency on a keyspace.
 
@@ -75,14 +75,12 @@ When querying, if the index name contains a `#` or `_` character, you
 keyspace-ref:: (Required) Specifies the keyspace where the index is created.
 Refer to <<keyspace-ref>> below.
 
-index-key:: (Required) Specifies an index key.
-Refer to <<index-key>> below.
-
-lead-key-attribs:: (Optional) Specifies attributes for the leading index key.
-Refer to <<index-key-attrib>> below.
+index-keys-and-attribs:: (Required) Specified the index keys and index key attributes.
+Refer to <<index-keys-and-attribs>> below.
 
-key-attribs:: (Optional) Specifies attributes for a non-leading index key.
-Refer to <<index-key-attrib>> below.
+index-include:: (Optional) Specifies non-key fields to include in the index.
+For use with vector indexes and secondary indexes with a vector field.
+Refer to <<index-include>> below.
 
 index-partition:: (Optional) Specifies index partitions.
 Refer to <<index-partition>> below.
@@ -96,6 +94,12 @@ Refer to <<index-using>> below.
 index-with:: (Optional) Specifies options for the index.
 Refer to <<index-with>> below.
 
+[[vector]]
+=== VECTOR Keyword
+
+FIXME: The optional `VECTOR` keyword indicates that the index is a vector index.
+For details, see Vector Indexes.
+
 [[if-not-exists]]
 === IF NOT EXISTS Clause
 
@@ -179,8 +183,31 @@ collection::
 For example, `airline` indicates the `airline` collection, assuming the query context is set.
 ====
 
+[[index-keys-and-attribs]]
+=== Index Keys and Attributes
+
+[source,ebnf]
+----
+include::partial$grammar/ddl.ebnf[tag=index-keys-and-attribs]
+----
+
+image::n1ql-language-reference/index-keys-and-attribs.png["Syntax diagram: refer to source code listing", align=left]
+
+TODO: Secondary indexes can have many keys.
+Vector indexes can only have one key, which must be a vector field.
+
+[horizontal]
+index-key:: (Required) Specifies an index key.
+Refer to <<index-key>> below.
+
+lead-key-attribs:: (Optional) Specifies attributes for the leading index key.
+Refer to <<index-key-attrib>> below.
+
+key-attribs:: (Optional) Specifies attributes for a non-leading index key.
+Refer to <<index-key-attrib>> below.
+
 [[index-key]]
-=== Index Key
+==== Index Key
 
 [source,ebnf]
 ----
@@ -203,7 +230,7 @@ Array indexing enables you to create global indexes on array elements and optimi
 For details, refer to {indexing-arrays}[Array Indexing].
 
 [[index-key-attrib]]
-=== Index Key Attributes
+==== Index Key Attributes
 
 [source,ebnf]
 ----
@@ -228,8 +255,11 @@ Refer to <<index-order>> below.
 include-missing:: (Optional) The leading index key may also include `INCLUDE MISSING` clause.
 Refer to <<include-missing>> below.
 
+include-vector:: (Optional) The leading index key may also include `INCLUDE MISSING` clause.
+Refer to <<include-vector>> below.
+
 [[index-order]]
-==== Index Order
+===== Index Order
 
 [source,ebnf]
 ----
@@ -250,7 +280,7 @@ The index key is sorted in descending order.
 This clause is optional; if omitted, the default is `ASC`.
 
 [[include-missing]]
-==== INCLUDE MISSING Clause
+===== INCLUDE MISSING Clause
 
 [source,ebnf]
 ----
@@ -265,6 +295,26 @@ If this clause is not present, then documents without the index key field are no
 The `INCLUDE MISSING` clause can only be applied to the leading index key.
 The `INCLUDE MISSING` clause may be included before or after the `ASC` or `DESC` keyword.
 
+[[include-vector]]
+===== VECTOR Field
+
+[source,ebnf]
+----
+include::partial$grammar/ddl.ebnf[tag=index-vector]
+----
+
+image::n1ql-language-reference/index-vector.png["Syntax diagram: refer to source code listing", align=left]
+
+FIXME: Indicates that the index key is a vector field.
+For details, see Vector Indexes and Secondary Indexes with a Vector Field.
+
+[[index-include]]
+=== INCLUDE Clause
+
+FIXME: Used to include non-key fields in the index.
+This is used for vector indexes and secondary indexes with a vector field.
+For details, see Vector Indexes and Secondary Indexes with a Vector Field.
+
 [[index-partition]]
 === PARTITION BY HASH Clause
 
@@ -378,6 +428,9 @@ If the value of this property is not less than the number of index nodes in the
 |Integer
 |===
 
+TODO: Vector indexes and secondary indexes with a vector field support further options.
+See Vector Indexes and Secondary Indexes with a Vector Field. 
+
 == Usage
 
 NOTE: It is not recommended to create (or drop) secondary indexes when any node with a secondary index role is down, as this may result in duplicate index names.

modules/n1ql/pages/n1ql-language-reference/dropindex.adoc

@@ -1,5 +1,5 @@
 = DROP INDEX
-:description: The DROP INDEX statement allows you to drop a named primary index or a secondary index.
+:description: The DROP INDEX statement allows you to drop a secondary index or a vector index.
 :page-topic-type: reference
 :imagesdir: ../../assets/images
 
@@ -42,29 +42,45 @@ The DROP INDEX statement provides two possible syntaxes for specifying the index
 // TODO: Automatic links in EBNF.
 
 [horizontal]
-index-name:: (Required) A unique name that identifies the index.
+index-path-and-name:: (Optional) One possible syntax for specifying the index and keyspace.
+Refer to <<index-path-and-name>> below.
 
-index-path:: (Optional) One possible syntax for specifying the the keyspace.
-Refer to <<index-path>> below.
+index-name-on-keyspace:: (Optional) The other possible syntax for specifying the index and keyspace.
+Refer to <<index-name-on-keyspace>> below.
 
-keyspace-ref:: (Optional) The other possible syntax for specifying the keyspace.
-Refer to <<keyspace-ref>> below.
+index-using:: (Optional) Specifies the index type.
+Refer to <<index-using>> below.
 
-index-using:: Specifies the index type.
-(Optional) Refer to <<index-using>> below.
+[[vector]]
+=== VECTOR Keyword
 
-[[if-exists]]
-=== IF EXISTS Clause
+FIXME: The optional VECTOR keyword indicates that you are deleting a vector index.
+The VECTOR keyword is purely a visual mnemonic.
+There is no syntactic requirement to include the VECTOR keyword when deleting a vector index.
 
-The optional `IF EXISTS` clause enables the statement to complete successfully when the specified index doesn't exist.
-If the index does not exist within the specified keyspace, then:
+[[index-path-and-name]]
+=== Index Path and Name
 
-* If this clause is not present, an error is generated.
+[source,ebnf]
+----
+include::partial$grammar/ddl.ebnf[tag=index-path-and-name]
+----
 
-* If this clause is present, the statement does nothing and completes without error.
+image::n1ql-language-reference/index-path-and-name.png["Syntax diagram: refer to source code listing", align=left]
+
+You can use a dotted notation to specify the index and the keyspace on which the index is built.
+This syntax provides compatibility with legacy versions of Couchbase Server.
+
+[horizontal]
+index-name:: (Required) A unique name that identifies the index.
+
+index-path:: (Required) Refer to <<index-path>> below.
+
+NOTE: If there is a hyphen (-) inside the index name or any part of the index path, you must wrap the index name or that part of the index path in backticks ({backtick}{nbsp}{backtick}).
+Refer to the examples below.
 
 [[index-path]]
-=== Index Path
+==== Index Path
 
 [source,ebnf]
 ----
@@ -73,15 +89,10 @@ include::partial$grammar/ddl.ebnf[tag=index-path]
 
 image::n1ql-language-reference/index-path.png["Syntax diagram: refer to source code listing", align=left]
 
-You can use a dotted notation to specify the index and the keyspace on which the index is built.
-This syntax provides compatibility with legacy versions of Couchbase Server.
 The index path may be a <<keyspace-full-index>>, a <<keyspace-prefix-index>>, or a <<keyspace-partial-index>>.
 
-NOTE: If there is a hyphen (-) inside the index name or any part of the index path, you must wrap the index name or that part of the index path in backticks ({backtick}{nbsp}{backtick}).
-Refer to the examples below.
-
 [[keyspace-full-index,full keyspace path]]
-==== Index Path: Full Keyspace
+===== Index Path: Full Keyspace
 
 [source,ebnf]
 ----
@@ -112,7 +123,7 @@ For example, `default:{backtick}travel-sample{backtick}.inventory.airline.{backt
 ====
 
 [[keyspace-prefix-index,keyspace prefix]]
-==== Index Path: Keyspace Prefix
+===== Index Path: Keyspace Prefix
 
 [source,ebnf]
 ----
@@ -138,7 +149,7 @@ For example, `default:{backtick}travel-sample{backtick}.def_type` indicates the
 ====
 
 [[keyspace-partial-index,keyspace partial]]
-==== Index Path: Keyspace Partial
+===== Index Path: Keyspace Partial
 
 [source,ebnf]
 ----
@@ -158,24 +169,40 @@ collection::
 For example, `airline.{backtick}idx-name{backtick}` indicates the `idx-name` index on the `airline` collection, assuming that the query context is set.
 ====
 
-[[keyspace-ref]]
+[[index-name-on-keyspace]]
 === Index Name ON Keyspace Reference
 
 [source,ebnf]
 ----
-include::partial$grammar/dql.ebnf[tag=keyspace-ref]
+include::partial$grammar/dql.ebnf[tag=index-name-on-keyspace]
 ----
 
-image::n1ql-language-reference/keyspace-ref.png["Syntax diagram: refer to source code listing", align=left]
+image::n1ql-language-reference/index-name-on-keyspace.png["Syntax diagram: refer to source code listing", align=left]
 
-You can use the index name with the `ON` keyword and a keyspace reference to specify the keyspace on which the index is built.
-The keyspace reference may be a <<keyspace-path>> or a <<keyspace-partial>>.
+You can use the index name with the `ON` keyword and a keyspace reference to specify the index and the keyspace on which the index is built.
+
+[horizontal]
+index-name:: (Required) A unique name that identifies the index.
+
+keyspace-ref:: (Required) Refer to <<keyspace-ref>> below.
 
 NOTE: If there is a hyphen (-) inside the index name or any part of the keyspace reference, you must wrap the index name or that part of the keyspace reference in backticks ({backtick}{nbsp}{backtick}).
 Refer to the examples below.
 
+[[keyspace-ref]]
+==== Keyspace Reference
+
+[source,ebnf]
+----
+include::partial$grammar/dql.ebnf[tag=keyspace-ref]
+----
+
+image::n1ql-language-reference/keyspace-ref.png["Syntax diagram: refer to source code listing", align=left]
+
+The keyspace reference may be a <<keyspace-path>> or a <<keyspace-partial>>.
+
 [[keyspace-path,keyspace path]]
-==== Keyspace Reference: Keyspace Path
+===== Keyspace Reference: Keyspace Path
 
 [source,ebnf]
 ----
@@ -211,7 +238,7 @@ Similarly, `{backtick}idx-name{backtick} ON default:{backtick}travel-sample{back
 ====
 
 [[keyspace-partial,keyspace partial]]
-==== Keyspace Reference: Keyspace Partial
+===== Keyspace Reference: Keyspace Partial
 
 [source,ebnf]
 ----
@@ -231,6 +258,16 @@ collection::
 For example, `{backtick}idx-name{backtick} ON airline` indicates the `idx-name` index on the `airline` collection, assuming the query context is set.
 ====
 
+[[if-exists]]
+=== IF EXISTS Clause
+
+The optional `IF EXISTS` clause enables the statement to complete successfully when the specified index doesn't exist.
+If the index does not exist within the specified keyspace, then:
+
+* If this clause is not present, an error is generated.
+
+* If this clause is present, the statement does nothing and completes without error.
+
 [[index-using]]
 === USING Clause