Skip to content

NO ISSUE: Style fixes #432

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 29, 2025
Merged

NO ISSUE: Style fixes #432

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cea9af1
Apply Vale suggestions for DDL and DML
simon-dew Sep 29, 2025
36b8a71
Update Search Vector workflow diagram
simon-dew Sep 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 29 additions & 29 deletions modules/n1ql/pages/n1ql-language-reference/alterindex.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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[]

Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -101,7 +101,7 @@ See <<index-with>>.
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.
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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 <<keyspace-path>> or a <<keyspace-partial>>.
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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.

Expand Down Expand Up @@ -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].
Expand All @@ -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.
Expand All @@ -377,29 +377,29 @@ 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

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[]
Expand All @@ -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.

Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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]
Expand Down
6 changes: 3 additions & 3 deletions modules/n1ql/pages/n1ql-language-reference/altervectorindex.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]

Expand All @@ -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]

Expand Down Expand Up @@ -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]
Expand Down
Loading