From cea9af125f390f0d24e9ff91aeca57d3042f1b46 Mon Sep 17 00:00:00 2001 From: Simon Dew Date: Mon, 29 Sep 2025 16:01:08 +0100 Subject: [PATCH 1/2] Apply Vale suggestions for DDL and DML --- .../n1ql-language-reference/alterindex.adoc | 58 +++++++++---------- .../altervectorindex.adoc | 6 +- .../n1ql-language-reference/createindex.adoc | 38 ++++++------ .../createprimaryindex.adoc | 26 +++++---- .../createvectorindex.adoc | 10 ++-- .../n1ql-language-reference/dropindex.adoc | 32 +++++----- .../dropprimaryindex.adoc | 20 +++---- .../dropvectorindex.adoc | 4 +- .../n1ql-language-reference/vectorfun.adoc | 20 +++---- 9 files changed, 108 insertions(+), 106 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/alterindex.adoc b/modules/n1ql/pages/n1ql-language-reference/alterindex.adoc index ac8168b1..1eaf569d 100644 --- a/modules/n1ql/pages/n1ql-language-reference/alterindex.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/alterindex.adoc @@ -20,7 +20,7 @@ include::partial$n1ql-language-reference/horizontal-style.adoc[] {description} The {alter-vector-index}[ALTER VECTOR INDEX] statement is a synonym for the ALTER INDEX statement. -The two statements have the same functionality. +Both statements have the same functionality. //tag::purpose[] == Purpose @@ -42,9 +42,9 @@ NOTE: The {doctitle} move operation is asynchronous. As soon as the move alter index command is executed, the command returns. If there is no error in the input, the move operation can be tracked through the console UI and any error can be found in the Console logs and Indexer logs. -If a node goes down while an {doctitle} operation is in progress, then the index would rollback to its original node (not affecting queries) and a notification would appear. +If a node goes down while an {doctitle} operation is happening, then the index would rollback to its original node (not affecting queries) and a notification would appear. -IMPORTANT: It is not possible to move an index or index replica and change the number of index replicas at the same time. +IMPORTANT: It's not possible to move an index or index replica and change the number of index replicas at the same time. //end::purpose[] @@ -53,7 +53,7 @@ IMPORTANT: It is not possible to move an index or index replica and change the n Only users with the RBAC role of `Administrator` are allowed to run the `{doctitle}` statement. -This statement is applicable only for Standard GSI (Plasma) and MOI Indexes; and hence supported only for Enterprise Edition nodes. +This statement is applicable only for Standard GSI (Plasma) and MOI Indexes; and hence supported only for Couchbase Server Enterprise Edition nodes. (Not applicable for Forest DB.) Altering indexes is only supported in Couchbase Server 5.5 and later; if any nodes in the cluster are running a version of Couchbase Server earlier than 5.5, then this statement will not work. @@ -68,10 +68,10 @@ In addition, altering the number of replicas or deleting an index replica is onl include::partial$grammar/ddl.ebnf[tag=alter-index] ---- -image::n1ql-language-reference/alter-index.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/alter-index.png["Syntax diagram: see source code listing", align=left] //tag::syntax-arguments[] -The {doctitle} statement provides two possible syntaxes for specifying the index and the keyspace where the index is located. +The {doctitle} statement provides 2 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 @@ -101,7 +101,7 @@ See <>. include::partial$grammar/ddl.ebnf[tag=index-path] ---- -image::n1ql-language-reference/index-path.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/index-path.png["Syntax diagram: see 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. @@ -118,7 +118,7 @@ See the examples on this page. include::partial$grammar/ddl.ebnf[tag=keyspace-full] ---- -image::n1ql-language-reference/keyspace-full.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-full.png["Syntax diagram: see source code listing", align=left] If the index is built on a named collection, the index path may be a full keyspace path, including namespace, bucket, scope, and collection, followed by the index name. In this case, the {query-context}[query context] is ignored. @@ -149,7 +149,7 @@ For example, `default:{backtick}travel-sample{backtick}.inventory.airline.{backt include::partial$grammar/ddl.ebnf[tag=keyspace-prefix] ---- -image::n1ql-language-reference/keyspace-prefix.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-prefix.png["Syntax diagram: see source code listing", align=left] If the index is built on the default collection in the default scope within a bucket, the index path may be just an optional namespace and the bucket name, followed by the index name. In this case, the {query-context}[query context] should not be set. @@ -175,7 +175,7 @@ For example, `default:{backtick}travel-sample{backtick}.def_type` indicates the include::partial$grammar/dql.ebnf[tag=keyspace-partial] ---- -image::n1ql-language-reference/keyspace-partial.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-partial.png["Syntax diagram: see source code listing", align=left] Alternatively, if the keyspace is a named collection, the index path may be just the collection name, followed by the index name. In this case, you must set the {query-context}[query context] to indicate the required namespace, bucket, and scope. @@ -198,7 +198,7 @@ For example, `airline.{backtick}idx-name{backtick}` indicates the `idx-name` ind include::partial$grammar/dql.ebnf[tag=keyspace-ref] ---- -image::n1ql-language-reference/keyspace-ref.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-ref.png["Syntax diagram: see 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 <> or a <>. @@ -214,7 +214,7 @@ See the examples on this page. include::partial$grammar/dql.ebnf[tag=keyspace-path] ---- -image::n1ql-language-reference/keyspace-path.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-path.png["Syntax diagram: see source code listing", align=left] If the keyspace is a named collection, or the default collection in the default scope within a bucket, the keyspace reference may be a keyspace path. In this case, the {query-context}[query context] should not be set. @@ -250,7 +250,7 @@ Similarly, `{backtick}idx-name{backtick} ON default:{backtick}travel-sample{back include::partial$grammar/dql.ebnf[tag=keyspace-partial] ---- -image::n1ql-language-reference/keyspace-partial.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-partial.png["Syntax diagram: see source code listing", align=left] Alternatively, if the keyspace is a named collection, the keyspace reference may be just the collection name. In this case, you must set the {query-context}[query context] to indicate the required namespace, bucket, and scope. @@ -273,7 +273,7 @@ For example, `{backtick}idx-name{backtick} ON airline` indicates the `idx-name` include::partial$grammar/ddl.ebnf[tag=index-using] ---- -image::n1ql-language-reference/index-using.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/index-using.png["Syntax diagram: see source code listing", align=left] The index type for a secondary index must be Global Secondary Index (GSI). The `USING GSI` keywords are optional and may be omitted. @@ -288,7 +288,7 @@ The `USING GSI` keywords are optional and may be omitted. include::partial$grammar/ddl.ebnf[tag=index-with] ---- -image::n1ql-language-reference/index-with.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/index-with.png["Syntax diagram: see source code listing", align=left] Use the `WITH` clause to specify additional options. @@ -337,8 +337,8 @@ Optional if `action` is set to `replica_count`. An array of strings, specifying a list of nodes. If `action` is set to `move`, the node list determines the new destination nodes for the index and its replicas. -If `action` is set to `replica_count` and you are increasing the number of replicas, the node list restricts the set of nodes available for placement of the index and its replicas. -However, if `action` is set to `replica_count` and you are decreasing the number of replicas, the `nodes` property is ignored. +If `action` is set to `replica_count` and you're increasing the number of replicas, the node list restricts the set of nodes available for placement of the index and its replicas. +However, if `action` is set to `replica_count` and you're decreasing the number of replicas, the `nodes` property is ignored. NOTE: You cannot use this property if you have enabled file-based index rebalancing. See xref:learn:clusters-and-availability/rebalance.adoc#index-rebalance-methods[Index Rebalance Methods]. @@ -363,7 +363,7 @@ The statement will not work while the cluster is undergoing a rebalance. === Moving an Index or Index Replicas When moving an index or index replicas, the number of destination nodes must be the same as the number of nodes on which the index and any replicas are currently placed. -You must specify the full node list, even if only one replica needs to be moved. +You must specify the full node list, even if you only need to move a single replica. Likewise, when moving a partitioned index, the number of destination nodes must be the same as the number of nodes on which the index partitions and any replicas are currently placed. You cannot use this statement to repartition an index across a different number of nodes. @@ -377,12 +377,12 @@ If the specified number of replicas is greater than or equal to the number of in If you specify a node list when changing the number of replicas, the specified nodes must include all of the nodes on which the index or index partitions and any index replicas are currently placed. -When increasing the number of replicas, whether you specify a node list or not, no single index node will host more than one replica of the same index, or the same partition of the same index. +When increasing the number of replicas, whether you specify a node list or not, no single index node will host more than 1 replica of the same index, or the same partition of the same index. Replicas are distributed across the available server groups. When reducing the number of replicas, the index service will first drop unhealthy replicas, where an unhealthy replica is a replica with missing partitions. After all unhealthy replicas are dropped, the index service will if necessary drop replicas with the highest replica ID. -An unhealthy replica may not have the highest replica ID, so after an index reduction there may be "gaps" in the sequence of replica IDs -- for example, 1, 2, 4, where replica ID 3 was dropped. +An unhealthy replica may not have the highest replica ID, so after an index reduction there may be gaps in the sequence of replica IDs -- for example, 1, 2, 4, where replica ID 3 was dropped. === Dropping a Specific Replica @@ -390,16 +390,16 @@ When dropping a replica, the index topology does not change. The indexing service remembers the number of partitions and replicas specified for this index. Given sufficient capacity, the dropped replica is rebuilt after the next rebalance -- although it may be placed on a different index node, depending on the resource usage statistics of the available nodes. -To find the ID of an index replica and see which node it is placed on, you can use the {console-indexes}[Indexes screen in the Couchbase Web Console] or query the {querying-indexes}[system:indexes] catalog. +To find the ID of an index replica and see which node it's placed on, you can use the {console-indexes}[Indexes screen in the Couchbase Web Console] or query the {querying-indexes}[system:indexes] catalog. -When dropping a replica, it is possible to leave a server group with no replica. +When dropping a replica, it's possible to leave a server group with no replica. For a partitioned index, run a rebalance to move a replica into the vacant server group. === Index Redistribution -Using this statement to move one index at a time may be cumbersome if there are a lot of indexes to be moved. -The _index redistribution_ setting enables you to specify how Couchbase Server redistributes indexes automatically on rebalance. -Refer to {rebalancing-the-index-service}[Rebalance] for more information. +Using this statement to move 1 index at a time may be cumbersome if there are a lot of indexes to be moved. +The index redistribution setting enables you to specify how Couchbase Server redistributes indexes automatically on rebalance. +For more information, see {rebalancing-the-index-service}[Rebalance]. //end::usage[] //tag::return-value[] @@ -408,7 +408,7 @@ Refer to {rebalancing-the-index-service}[Rebalance] for more information. If the statement succeeds, then: * The query returns an empty array. -* The index progress is visible in the Query Workbench. +* The index alteration is visible in the Query Workbench. * After the movement is complete, the new indexes begin to service query scans. * The command line displays the new index nodes. @@ -440,8 +440,8 @@ a| | `Unable to find Index service for destination xxx.xxx.xxx.xxx:8091 or destination is not part of the cluster` a| -* Address doesn't exist or was mistyped -* Node isn't running +* Address does not exist or was mistyped +* Node is not running * Node not properly added to the cluster | `Unsupported action value` @@ -561,7 +561,7 @@ WITH {"action": "replica_count", "num_replica": 1}; .Dropping a specific replica ==== -Create an index with two replicas, and specify that nodes 192.168.10.10, 192.168.10.11, 192.168.10.12, and 192.168.10.13 should be available for index and replica placement. +Create an index with 2 replicas, and specify that nodes 192.168.10.10, 192.168.10.11, 192.168.10.12, and 192.168.10.13 should be available for index and replica placement. Then delete replica 2. [source,sqlpp] diff --git a/modules/n1ql/pages/n1ql-language-reference/altervectorindex.adoc b/modules/n1ql/pages/n1ql-language-reference/altervectorindex.adoc index ae793da7..1386211c 100644 --- a/modules/n1ql/pages/n1ql-language-reference/altervectorindex.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/altervectorindex.adoc @@ -21,7 +21,7 @@ include::partial$n1ql-language-reference/horizontal-style.adoc[] {description} The {alter-index}[ALTER INDEX] statement is a synonym for the ALTER VECTOR INDEX statement. -The two statements have the same functionality. +Both statements have the same functionality. include::alterindex.adoc[tags=purpose] @@ -34,7 +34,7 @@ include::alterindex.adoc[tags=prerequisites] include::partial$grammar/ddl.ebnf[tag=alter-vector-index] ---- -image::n1ql-language-reference/alter-vector-index.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/alter-vector-index.png["Syntax diagram: see source code listing", align=left] include::alterindex.adoc[tags=syntax-arguments] @@ -167,7 +167,7 @@ WITH {"action": "replica_count", "num_replica": 1}; .Drop a specific replica ==== -Create a hyperscale vector index with two replicas, and specify that nodes 172.19.0.2, 172.19.0.3, and 172.19.0.4 should be available for index and replica placement. +Create a hyperscale vector index with 2 replicas, and specify that nodes 172.19.0.2, 172.19.0.3, and 172.19.0.4 should be available for index and replica placement. Then delete replica 2. [source,sqlpp] diff --git a/modules/n1ql/pages/n1ql-language-reference/createindex.adoc b/modules/n1ql/pages/n1ql-language-reference/createindex.adoc index 0cc3e216..c7c38b4d 100644 --- a/modules/n1ql/pages/n1ql-language-reference/createindex.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/createindex.adoc @@ -70,8 +70,8 @@ If the data set changes dramatically, you must drop and rebuild the index to upd [discrete] ===== RBAC Privileges -To execute the {doctitle} statement, you must have the _Query Manage Index_ privilege granted on the keyspace. -For more details about user roles, see +To execute the {doctitle} statement, you must have the `Query Manage Index` privilege granted on the keyspace. +For more information about user roles, see {authorization-overview}[Authorization]. include::partial$n1ql-language-reference/vector-index-no-windows.adoc[] @@ -84,7 +84,7 @@ include::partial$n1ql-language-reference/vector-index-no-windows.adoc[] include::partial$grammar/ddl.ebnf[tag=create-index] ---- -image::n1ql-language-reference/create-index.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/create-index.png["Syntax diagram: see source code listing", align=left] // TODO: Automatic links in EBNF. @@ -134,7 +134,7 @@ If an index with the same name already exists within the specified keyspace, the include::partial$grammar/dql.ebnf[tag=keyspace-ref] ---- -image::n1ql-language-reference/keyspace-ref.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-ref.png["Syntax diagram: see source code listing", align=left] Specifies the keyspace for which the index needs to be created. The keyspace reference may be a <> or a <>. @@ -150,7 +150,7 @@ See the examples on this page. include::partial$grammar/dql.ebnf[tag=keyspace-path] ---- -image::n1ql-language-reference/keyspace-path.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-path.png["Syntax diagram: see source code listing", align=left] If the keyspace is a named collection, or the default collection in the default scope within a bucket, the keyspace reference may be a keyspace path. In this case, the {query-context}[query context] should not be set. @@ -186,7 +186,7 @@ Similarly, `default:{backtick}travel-sample{backtick}.inventory.airline` indicat include::partial$grammar/dql.ebnf[tag=keyspace-partial] ---- -image::n1ql-language-reference/keyspace-partial.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-partial.png["Syntax diagram: see source code listing", align=left] Alternatively, if the keyspace is a named collection, the keyspace reference may be just the collection name with no path. In this case, you must set the {query-context}[query context] to indicate the required namespace, bucket, and scope. @@ -208,7 +208,7 @@ For example, `airline` indicates the `airline` collection, assuming the query co 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] +image::n1ql-language-reference/index-keys-and-attribs.png["Syntax diagram: see source code listing", align=left] Secondary indexes and composite vector indexes can have many keys. Each key may have index attributes, which define the behavior of the index key. @@ -231,7 +231,7 @@ See <>. include::partial$grammar/ddl.ebnf[tag=index-key] ---- -image::n1ql-language-reference/index-key.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/index-key.png["Syntax diagram: see source code listing", align=left] The index key is a {sqlpp} {expression}[expression] referring to a field in the document, or an ARRAY expression on the field. @@ -263,14 +263,14 @@ For details, see {indexing-arrays}[]. include::partial$grammar/ddl.ebnf[tag=lead-key-attribs] ---- -image::n1ql-language-reference/lead-key-attribs.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/lead-key-attribs.png["Syntax diagram: see source code listing", align=left] [source,ebnf] ---- include::partial$grammar/ddl.ebnf[tag=key-attribs] ---- -image::n1ql-language-reference/key-attribs.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/key-attribs.png["Syntax diagram: see source code listing", align=left] Specifies attributes for the index key. @@ -292,7 +292,7 @@ See <>. include::partial$grammar/ddl.ebnf[tag=index-order] ---- -image::n1ql-language-reference/index-order.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/index-order.png["Syntax diagram: see source code listing", align=left] Specifies the sort order of the index key. For non-vector fields only. @@ -314,7 +314,7 @@ This clause is optional; if omitted, the default is `ASC`. include::partial$grammar/ddl.ebnf[tag=include-missing] ---- -image::n1ql-language-reference/include-missing.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/include-missing.png["Syntax diagram: see source code listing", align=left] The optional `INCLUDE MISSING` clause ensures that documents which do not include the index key field are indexed regardless. If this clause is not present, then documents without the index key field are not indexed. @@ -330,7 +330,7 @@ The `INCLUDE MISSING` clause may be included before or after the `ASC` or `DESC` include::partial$grammar/ddl.ebnf[tag=index-vector] ---- -image::n1ql-language-reference/index-vector.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/index-vector.png["Syntax diagram: see source code listing", align=left] Indicates that the index key is a vector field. @@ -356,7 +356,7 @@ See {index-training}[The Importance of Index Training]. include::partial$grammar/dql.ebnf[tag=where-clause] ---- -image::n1ql-language-reference/where-clause.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/where-clause.png["Syntax diagram: see source code listing", align=left] [horizontal#where-clause-args] cond:: @@ -372,7 +372,7 @@ Specifies WHERE clause predicates to qualify the subset of documents to include include::partial$grammar/ddl.ebnf[tag=index-using] ---- -image::n1ql-language-reference/index-using.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/index-using.png["Syntax diagram: see source code listing", align=left] The index type for a secondary index must be Global Secondary Index (GSI). The `USING GSI` keywords are optional and may be omitted. @@ -387,7 +387,7 @@ The `USING GSI` keywords are optional and may be omitted. include::partial$grammar/ddl.ebnf[tag=index-with] ---- -image::n1ql-language-reference/index-with.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/index-with.png["Syntax diagram: see source code listing", align=left] Use the WITH clause to specify additional options. @@ -595,7 +595,7 @@ image::create-index-replica-id.png["The Indexes screen showing an index and inde If you select `view by server node` from the drop-down menu, you can see the server node where each index and index replica is placed. -You can also query the {querying-indexes}[system:indexes] catalog to find the ID of an index replica and see which node it is placed on. +You can also query the {querying-indexes}[system:indexes] catalog to find the ID of an index replica and see which node it's placed on. [NOTE] ==== @@ -675,7 +675,7 @@ include::example$n1ql-language-reference/check-idx-defer.n1ql[] include::example$n1ql-language-reference/check-idx-defer.jsonc[] ---- -<1> Note that the index is in the deferred state. +<1> The index is in the deferred state. ==== [[ex-build-idx-defer]] @@ -703,7 +703,7 @@ include::example$n1ql-language-reference/check-idx-online.n1ql[] include::example$n1ql-language-reference/check-idx-online.jsonc[] ---- -<1> Note that the index has now been created. +<1> The index has now been created. ==== [[ex-create-idx-missing]] diff --git a/modules/n1ql/pages/n1ql-language-reference/createprimaryindex.adoc b/modules/n1ql/pages/n1ql-language-reference/createprimaryindex.adoc index 1b423600..86f92d7e 100644 --- a/modules/n1ql/pages/n1ql-language-reference/createprimaryindex.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/createprimaryindex.adoc @@ -20,7 +20,7 @@ include::partial$n1ql-language-reference/horizontal-style.adoc[] The `CREATE PRIMARY INDEX` statement allows you to create a primary index. Primary indexes contain a full set of keys in a given keyspace. -Primary indexes are optional -- they enable you to run ad hoc queries on a keyspace that is not supported by a secondary index. +Primary indexes are optional -- they enable you to run ad hoc queries on a keyspace that's not supported by a secondary index. == Purpose @@ -45,8 +45,8 @@ See <> for more details. [discrete] ===== RBAC Privileges -To execute the `CREATE PRIMARY INDEX` statement, you must have the _Query Manage Index_ privilege granted on the keyspace. -For more details about user roles, see +To execute the `CREATE PRIMARY INDEX` statement, you must have the `Query Manage Index` privilege granted on the keyspace. +For more information about user roles, see {authorization-overview}[Authorization]. == Syntax @@ -56,7 +56,7 @@ For more details about user roles, see include::partial$grammar/ddl.ebnf[tag=create-primary-index] ---- -image::n1ql-language-reference/create-primary-index.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/create-primary-index.png["Syntax diagram: see source code listing", align=left] // TODO: Automatic links in EBNF. @@ -96,7 +96,7 @@ If a primary index with the same name already exists within the specified keyspa include::partial$grammar/dql.ebnf[tag=keyspace-ref] ---- -image::n1ql-language-reference/keyspace-ref.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-ref.png["Syntax diagram: see source code listing", align=left] Specifies the keyspace for which the index needs to be created. The keyspace reference may be a <> or a <>. @@ -112,7 +112,7 @@ See the examples on this page. include::partial$grammar/dql.ebnf[tag=keyspace-path] ---- -image::n1ql-language-reference/keyspace-path.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-path.png["Syntax diagram: see source code listing", align=left] If the keyspace is a named collection, or the default collection in the default scope within a bucket, the keyspace reference may be a keyspace path. In this case, the {query-context}[query context] should not be set. @@ -148,7 +148,7 @@ Similarly, `default:{backtick}travel-sample{backtick}.inventory.airline` indicat include::partial$grammar/dql.ebnf[tag=keyspace-partial] ---- -image::n1ql-language-reference/keyspace-partial.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-partial.png["Syntax diagram: see source code listing", align=left] Alternatively, if the keyspace is a named collection, the keyspace reference may be just the collection name with no path. In this case, you must set the {query-context}[query context] to indicate the required namespace, bucket, and scope. @@ -169,7 +169,7 @@ For example, `airline` indicates the `airline` collection, assuming the query co include::partial$grammar/ddl.ebnf[tag=index-using] ---- -image::n1ql-language-reference/index-using.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/index-using.png["Syntax diagram: see source code listing", align=left] The index type for a primary index must be Global Secondary Index (GSI). The `USING GSI` keywords are optional and may be omitted. @@ -182,7 +182,7 @@ The `USING GSI` keywords are optional and may be omitted. include::partial$grammar/ddl.ebnf[tag=index-with] ---- -image::n1ql-language-reference/index-with.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/index-with.png["Syntax diagram: see source code listing", align=left] Use the WITH clause to specify additional options. @@ -209,7 +209,7 @@ The `nodes` property allows you to specify the node that the index is placed on. [.edition]#{enterprise}# In Couchbase Server Enterprise Edition, you can specify multiple nodes to distribute replicas of an index across nodes running the indexing service: for example, `WITH {"nodes": ["node1:8091", "node2:8091", "node3:8091"]}`. -For details and examples, refer to {index-replication}[Index Replication]. +For details and examples, see {index-replication}[Index Replication]. If specifying both [.var]`nodes` and [.var]`num_replica`, the number of nodes in the array must be one greater than the specified number of replicas otherwise the index creation will fail. @@ -255,10 +255,12 @@ If the value of this property is not less than the number of index nodes in the == Usage +// Nothing + === Monitoring Primary Indexes Index metadata provides a state field. -This state field and other index metadata can be queried using {querying-indexes}[system:indexes]. +You can query this state field and other index metadata using {querying-indexes}[system:indexes]. The index state may be `scheduled for creation`, `deferred`, `building`, `pending`, `online`, `offline`, or `abridged`. You can also monitor the index state using the Couchbase Web Console. @@ -280,7 +282,7 @@ You must drop the failed index using the `DROP INDEX` command. For a primary index scan on any keyspace size, the query engine guarantees that the client is not exposed to scan timeout if the indexer throws a scan timeout after it has returned a greater than zero sized subset of primary keys. To complete the scan, the query engine performs successive scans of the primary index until all the primary keys have been returned. -It is possible that the indexer throws scan timeout without returning any primary keys, and in this event the query engine returns scan timeout to the client. +It's possible that the indexer may throw scan timeout without returning any primary keys, and in this event the query engine returns scan timeout to the client. For example, if the indexer cannot find a snapshot that satisfies the consistency guarantee of the query within the timeout limit, it will timeout without returning any primary keys. diff --git a/modules/n1ql/pages/n1ql-language-reference/createvectorindex.adoc b/modules/n1ql/pages/n1ql-language-reference/createvectorindex.adoc index 6174e2db..cb3d2e47 100644 --- a/modules/n1ql/pages/n1ql-language-reference/createvectorindex.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/createvectorindex.adoc @@ -48,7 +48,7 @@ include::createindex.adoc[tags=prerequisites] include::partial$grammar/ddl.ebnf[tag=create-vector-index] ---- -image::n1ql-language-reference/create-vector-index.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/create-vector-index.png["Syntax diagram: see source code listing", align=left] // TODO: Automatic links in EBNF. @@ -92,7 +92,7 @@ include::createindex.adoc[tags=keyspace-ref] include::partial$grammar/ddl.ebnf[tags=index-key-and-attrib] ---- -image::n1ql-language-reference/index-key-and-attrib.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/index-key-and-attrib.png["Syntax diagram: see source code listing", align=left] Hyperscale vector indexes only have one key, which must be a vector field. The index key takes one attribute, the VECTOR keyword. @@ -112,7 +112,7 @@ See <>. include::partial$grammar/ddl.ebnf[tag=index-key] ---- -image::n1ql-language-reference/index-key.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/index-key.png["Syntax diagram: see source code listing", align=left] The index key is a {sqlpp} {expression}[expression] referring to a vector field, or an ARRAY expression on the vector field. @@ -135,7 +135,7 @@ For details, see {indexing-arrays}[]. include::partial$grammar/ddl.ebnf[tag=index-vector] ---- -image::n1ql-language-reference/index-vector.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/index-vector.png["Syntax diagram: see source code listing", align=left] Indicates that the index key is a vector field. @@ -147,7 +147,7 @@ Indicates that the index key is a vector field. include::partial$grammar/ddl.ebnf[tag=index-include] ---- -image::n1ql-language-reference/index-include.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/index-include.png["Syntax diagram: see source code listing", align=left] Used to include scalar fields in the index, which you can use to filter the vector search. The INCLUDE clause cannot include a vector field. diff --git a/modules/n1ql/pages/n1ql-language-reference/dropindex.adoc b/modules/n1ql/pages/n1ql-language-reference/dropindex.adoc index 8bd945f4..155e69a1 100644 --- a/modules/n1ql/pages/n1ql-language-reference/dropindex.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/dropindex.adoc @@ -19,7 +19,7 @@ include::partial$n1ql-language-reference/horizontal-style.adoc[] Dropping an index that has replicas will drop all of the replica indexes too. The {drop-vector-index}[DROP VECTOR INDEX] statement is a synonym for the DROP INDEX statement. -The two statements have the same functionality. +Both statements have the same functionality. [NOTE] To drop a primary index, use the {drop-primary-index}[DROP PRIMARY INDEX] statement. @@ -31,8 +31,8 @@ For compatibility with legacy versions of Couchbase Server, you can also use DRO [discrete] ===== RBAC Privileges -To use the {doctitle} statement, you must have the _Query Manage Index_ privilege on the keyspace or bucket. -For more details about user roles, see +To use the {doctitle} statement, you must have the `Query Manage Index` privilege on the keyspace or bucket. +For more information about user roles, see {authorization-overview}[Authorization]. // end::prerequisites[] @@ -43,7 +43,7 @@ For more details about user roles, see include::partial$grammar/ddl.ebnf[tag=drop-index] ---- -image::n1ql-language-reference/drop-index.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/drop-index.png["Syntax diagram: see source code listing", align=left] //tag::syntax-arguments[] The {doctitle} statement provides two possible syntaxes for specifying the index and the keyspace where the index is located. @@ -70,7 +70,7 @@ See <>. include::partial$grammar/ddl.ebnf[tag=index-path-and-name] ---- -image::n1ql-language-reference/index-path-and-name.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/index-path-and-name.png["Syntax diagram: see 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. @@ -91,7 +91,7 @@ See the examples on this page. include::partial$grammar/ddl.ebnf[tag=index-path] ---- -image::n1ql-language-reference/index-path.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/index-path.png["Syntax diagram: see source code listing", align=left] The index path may be a <>, a <>, or a <>. @@ -103,7 +103,7 @@ The index path may be a <>, a <>, or include::partial$grammar/ddl.ebnf[tag=keyspace-full] ---- -image::n1ql-language-reference/keyspace-full.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-full.png["Syntax diagram: see source code listing", align=left] If the index is built on a named collection, the index path may be a full keyspace path, including namespace, bucket, scope, and collection, followed by the index name. In this case, the {query-context}[query context] is ignored. @@ -134,7 +134,7 @@ For example, `default:{backtick}travel-sample{backtick}.inventory.airline.{backt include::partial$grammar/ddl.ebnf[tag=keyspace-prefix] ---- -image::n1ql-language-reference/keyspace-prefix.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-prefix.png["Syntax diagram: see source code listing", align=left] If the index is built on the default collection in the default scope within a bucket, the index path may be just an optional namespace and the bucket name, followed by the index name. In this case, the {query-context}[query context] should not be set. @@ -160,7 +160,7 @@ For example, `default:{backtick}travel-sample{backtick}.def_type` indicates the include::partial$grammar/dql.ebnf[tag=keyspace-partial] ---- -image::n1ql-language-reference/keyspace-partial.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-partial.png["Syntax diagram: see source code listing", align=left] Alternatively, if the keyspace is a named collection, the index path may be just the collection name, followed by the index name. In this case, you must set the {query-context}[query context] to indicate the required namespace, bucket, and scope. @@ -181,7 +181,7 @@ For example, `airline.{backtick}idx-name{backtick}` indicates the `idx-name` ind include::partial$grammar/ddl.ebnf[tags=index-name-on-keyspace] ---- -image::n1ql-language-reference/index-name-on-keyspace.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/index-name-on-keyspace.png["Syntax diagram: see source code listing", align=left] 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. @@ -201,7 +201,7 @@ See the examples on this page. include::partial$grammar/dql.ebnf[tag=keyspace-ref] ---- -image::n1ql-language-reference/keyspace-ref.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-ref.png["Syntax diagram: see source code listing", align=left] The keyspace reference may be a <> or a <>. @@ -213,7 +213,7 @@ The keyspace reference may be a <> or a <>. include::partial$grammar/dql.ebnf[tag=keyspace-path] ---- -image::n1ql-language-reference/keyspace-path.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-path.png["Syntax diagram: see source code listing", align=left] If the keyspace is a named collection, or the default collection in the default scope within a bucket, the keyspace reference may be a keyspace path. In this case, the {query-context}[query context] should not be set. @@ -249,7 +249,7 @@ Similarly, `{backtick}idx-name{backtick} ON default:{backtick}travel-sample{back include::partial$grammar/dql.ebnf[tag=keyspace-partial] ---- -image::n1ql-language-reference/keyspace-partial.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-partial.png["Syntax diagram: see source code listing", align=left] Alternatively, if the keyspace is a named collection, the keyspace reference may be just the collection name. In this case, you must set the {query-context}[query context] to indicate the required namespace, bucket, and scope. @@ -267,7 +267,7 @@ For example, `{backtick}idx-name{backtick} ON airline` indicates the `idx-name` [[if-exists]] === IF EXISTS Clause -The optional `IF EXISTS` clause enables the statement to complete successfully when the specified index doesn't exist. +The optional `IF EXISTS` clause enables the statement to complete successfully when the specified index does not exist. If the index does not exist within the specified keyspace, then: * If this clause is not present, an error is generated. @@ -284,7 +284,7 @@ If the index does not exist within the specified keyspace, then: include::partial$grammar/ddl.ebnf[tag=index-using] ---- -image::n1ql-language-reference/index-using.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/index-using.png["Syntax diagram: see source code listing", align=left] The index type for a secondary index must be Global Secondary Index (GSI). The `USING GSI` keywords are optional and may be omitted. @@ -327,7 +327,7 @@ Once the index creation statement comes back, query `system:indexes` for the sta include::example$n1ql-language-reference/drop-idx-default.n1ql[tag=tmp] ---- -Subsequently, drop the index and check that it is no longer reported in the `system:indexes` output. +Subsequently, drop the index and check that it's no longer reported in the `system:indexes` output. [source,sqlpp] ---- diff --git a/modules/n1ql/pages/n1ql-language-reference/dropprimaryindex.adoc b/modules/n1ql/pages/n1ql-language-reference/dropprimaryindex.adoc index c4f759c3..3c79373b 100644 --- a/modules/n1ql/pages/n1ql-language-reference/dropprimaryindex.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/dropprimaryindex.adoc @@ -21,8 +21,8 @@ NOTE: For compatibility with legacy versions of Couchbase Server, you can also u [discrete] ===== RBAC Privileges -To execute the DROP PRIMARY INDEX statement, you must have the _Query Manage Index_ privilege granted on the keyspace. -For more details about user roles, see {roles}[Roles]. +To execute the DROP PRIMARY INDEX statement, you must have the `Query Manage Index` privilege granted on the keyspace. +For more information about user roles, see {roles}[Roles]. == Syntax @@ -31,13 +31,13 @@ For more details about user roles, see {roles}[Roles]. include::partial$grammar/ddl.ebnf[tag=drop-primary-index] ---- -image::n1ql-language-reference/drop-primary-index.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/drop-primary-index.png["Syntax diagram: see source code listing", align=left] // TODO: Automatic links in EBNF. [horizontal] index-name:: (Optional) A unique name that identifies the index. -If you don't specify a name, the index with the default name of `#primary` is deleted. +If you do not specify a name, the index with the default name of `#primary` is deleted. keyspace-ref:: (Required) Specifies the keyspace where the index is located. See <>. @@ -48,7 +48,7 @@ See <>. [[if-exists]] === IF EXISTS Clause -The optional `IF EXISTS` clause enables the statement to complete successfully when the specified primary index doesn't exist. +The optional `IF EXISTS` clause enables the statement to complete successfully when the specified primary index does not exist. If the primary index does not exist within the specified keyspace, then: * If this clause is not present, an error is generated. @@ -63,7 +63,7 @@ If the primary index does not exist within the specified keyspace, then: include::partial$grammar/dql.ebnf[tag=keyspace-ref] ---- -image::n1ql-language-reference/keyspace-ref.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-ref.png["Syntax diagram: see source code listing", align=left] Specifies the keyspace for the primary index to drop. The keyspace reference may be a <> or a <>. @@ -79,7 +79,7 @@ See the examples on this page. include::partial$grammar/dql.ebnf[tag=keyspace-path] ---- -image::n1ql-language-reference/keyspace-path.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-path.png["Syntax diagram: see source code listing", align=left] If the keyspace is a named collection, or the default collection in the default scope within a bucket, the keyspace reference may be a keyspace path. In this case, the {query-context}[query context] should not be set. @@ -115,7 +115,7 @@ Similarly, `default:{backtick}travel-sample{backtick}.inventory.airline` indicat include::partial$grammar/dql.ebnf[tag=keyspace-partial] ---- -image::n1ql-language-reference/keyspace-partial.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/keyspace-partial.png["Syntax diagram: see source code listing", align=left] Alternatively, if the keyspace is a named collection, the keyspace reference may be just the collection name with no path. In this case, you must set the {query-context}[query context] to indicate the required namespace, bucket, and scope. @@ -136,7 +136,7 @@ For example, `airline` indicates the `airline` collection, assuming the query co include::partial$grammar/ddl.ebnf[tag=index-using] ---- -image::n1ql-language-reference/index-using.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/index-using.png["Syntax diagram: see source code listing", align=left] The index type for a primary index must be Global Secondary Index (GSI). The `USING GSI` keywords are optional and may be omitted. @@ -155,7 +155,7 @@ Once the index creation statement comes back, query `system:indexes` for status include::example$n1ql-language-reference/create-pri-nameless.n1ql[tags=**] ---- -Subsequently, drop the unnamed primary index with the following statement so that it is no longer reported in the `system:indexes` output. +Subsequently, drop the unnamed primary index with the following statement so that it's no longer reported in the `system:indexes` output. [source,sqlpp] ---- diff --git a/modules/n1ql/pages/n1ql-language-reference/dropvectorindex.adoc b/modules/n1ql/pages/n1ql-language-reference/dropvectorindex.adoc index ba3442ac..38cf96d9 100644 --- a/modules/n1ql/pages/n1ql-language-reference/dropvectorindex.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/dropvectorindex.adoc @@ -20,7 +20,7 @@ include::partial$n1ql-language-reference/horizontal-style.adoc[] Dropping an index that has replicas will drop all of the replica indexes too. The {drop-index}[DROP INDEX] statement is a synonym for the DROP VECTOR INDEX statement. -The two statements have the same functionality. +Both statements have the same functionality. [NOTE] To drop a primary index, use the {drop-primary-index}[DROP PRIMARY INDEX] statement. @@ -35,7 +35,7 @@ include::dropindex.adoc[tags=prerequisites] include::partial$grammar/ddl.ebnf[tag=drop-vector-index] ---- -image::n1ql-language-reference/drop-vector-index.png["Syntax diagram: refer to source code listing", align=left] +image::n1ql-language-reference/drop-vector-index.png["Syntax diagram: see source code listing", align=left] include::dropindex.adoc[tags=syntax-arguments] diff --git a/modules/n1ql/pages/n1ql-language-reference/vectorfun.adoc b/modules/n1ql/pages/n1ql-language-reference/vectorfun.adoc index c25d098b..9f82a3d1 100644 --- a/modules/n1ql/pages/n1ql-language-reference/vectorfun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/vectorfun.adoc @@ -10,7 +10,7 @@ [abstract] {description} -Vector functions include similarity functions to find the distance between two vectors, functions that check for a vector value, and functions that transform vector values. +Vector functions include similarity functions to find the distance between two vectors, functions that check for a vector value, and functions that modify vector values. For more information about vectors and vector indexes, see xref:vector-index:vectors-and-indexes-overview.adoc[]. @@ -26,7 +26,7 @@ Finds the approximate distance between a provided vector and the content of a sp This function works best with a hyperscale vector index or composite vector index. If a query contains this function, and all of the following are true: -* There is a hyperscale vector index or a composite vector index with a vector index key which is the same as the vector field referenced by the function +* The cluster has a hyperscale vector index or a composite vector index with a vector index key which is the same as the vector field referenced by the function * The vector index key uses a similarity setting which is the same as the distance metric referenced by the function @@ -234,7 +234,7 @@ include::vector-index:example$hyperscale-idx-data.json[tag=exact-query-results] ---- Compare this with the result of <>. -In this case, the approximate vector distance does not give very accurate results. +In this case, the approximate vector distance does not give accurate results. ==== [#approx_vector_distance_ex_nprobe] @@ -284,7 +284,7 @@ The query returns 3 colors where the embedded vector associated with the color d include::vector-index:example$hyperscale-idx-data.json[tag=rerank-after] ---- -For more details and examples, see xref:vector-index:hyperscale-reranking.adoc[]. +For more information and examples, see xref:vector-index:hyperscale-reranking.adoc[]. ==== [[decode_vector,DECODE_VECTOR()]] @@ -301,8 +301,8 @@ Reverses the encoding done by the <> function. vector:: String, or any {sqlpp} expression that evaluates to a string, representing the base64 encoding of a vector value. byte_order:: [Optional] A boolean which determines the byte order of the vector value. -If `true`, it is big-endian. -If `false`, it is little-endian. +If `true`, it's big-endian. +If `false`, it's little-endian. The default is `false`. === Return Value @@ -359,8 +359,8 @@ Returns the https://en.wikipedia.org/wiki/Base64[base64] encoding of a vector va vector:: An array of floating point numbers, or any {sqlpp} expression that evaluates to an array of floating point numbers. byte_order:: [Optional] A boolean which determines the byte order of the vector value. -If `true`, it is big-endian. -If `false`, it is little-endian. +If `true`, it's big-endian. +If `false`, it's little-endian. The default is `false`. === Return Value @@ -402,7 +402,7 @@ SELECT ENCODE_VECTOR([1, 2, 3, 4]) AS little_endian, === Description Checks if the supplied expression is an array of floating point numbers with the specified number of dimensions. -This can be used to determine whether a field contains contains a vector value. +This can be used to determine whether a field contains a vector value. === Arguments @@ -656,7 +656,7 @@ The query returns 10 colors where the embedded vector associated with the color include::vector-index:example$hyperscale-idx-data.json[tag=exact-query-results] ---- -For more details and examples, see xref:vector-index:vector-index-best-practices.adoc#recall-accuracy[Determine Recall Rate]. +For more information and examples, see xref:vector-index:vector-index-best-practices.adoc#recall-accuracy[Determine Recall Rate]. ==== [#aliases] From 36b8a71c6093c4d8a0d6954942336d1d9e2f7f3d Mon Sep 17 00:00:00 2001 From: Simon Dew Date: Mon, 29 Sep 2025 16:42:10 +0100 Subject: [PATCH 2/2] Update Search Vector workflow diagram --- modules/vector-index/partials/fts-vector-app-workflow.puml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/modules/vector-index/partials/fts-vector-app-workflow.puml b/modules/vector-index/partials/fts-vector-app-workflow.puml index d7948cd4..e3c54567 100644 --- a/modules/vector-index/partials/fts-vector-app-workflow.puml +++ b/modules/vector-index/partials/fts-vector-app-workflow.puml @@ -58,6 +58,9 @@ Models -> Logic: Vector deactivate Models autonumber resume Logic -> Search: Search +' It's actually a self call from the Search Service +' But this way the alignment is neater +Data -[#transparent]> Data: Index Scan Search -> Logic:Results deactivate Search deactivate Logic