Skip to content

NO ISSUE: Capella-specific GSI fixes #449

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 5 commits into from
Oct 14, 2025
Merged

NO ISSUE: Capella-specific GSI fixes #449

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
8622e16
Update links to Capella
simon-dew Oct 14, 2025
b015756
Hide service-level settings
simon-dew Oct 14, 2025
8358db1
Update replica examples
simon-dew Oct 14, 2025
6334ff7
Remove page edition
simon-dew Oct 14, 2025
31d4692
ALTER INDEX example nodes
simon-dew Oct 14, 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
2 changes: 1 addition & 1 deletion modules/n1ql/examples/n1ql-language-reference/alter-idx-move.n1ql
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
ALTER INDEX def_inventory_airport_faa ON airport
WITH {"action": "move", "nodes": ["192.168.10.11:8091"]};
WITH {"action": "move", "nodes": ["svc-dqi-node-002:18091"]};
78 changes: 44 additions & 34 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 @@ -4,8 +4,8 @@
:page-toclevels: 2
:imagesdir: ../../assets/images

:rebalancing-the-index-service: xref:server:learn:clusters-and-availability/rebalance.adoc#rebalancing-the-index-service
:console-indexes: xref:server:manage:manage-ui/manage-ui.adoc#console-indexes
:rebalancing-the-index-service: xref:clusters:scale-database.adoc#rebalance
:console-indexes: xref:clusters:index-service/manage-indexes.adoc
:query-context: xref:n1ql:n1ql-intro/queriesandresults.adoc#query-context
:identifiers: xref:n1ql-language-reference/identifiers.adoc
:logical-hierarchy: xref:n1ql:n1ql-intro/queriesandresults.adoc#logical-hierarchy
Expand Down Expand Up @@ -382,18 +382,19 @@ 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's 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 page in the Couchbase Capella UI] or query the {querying-indexes}[system:indexes] catalog.

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.

ifdef::flag-devex-rest-api[]
=== Index Redistribution

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 Capella redistributes indexes automatically on rebalance.
For more information, see {rebalancing-the-index-service}[Rebalance].
ifdef::flag-devex-rest-api[]
The index redistribution setting enables you to specify how
endif::flag-devex-rest-api[]
Couchbase Capella redistributes indexes automatically on rebalance.
For more information, see {rebalancing-the-index-service}[Rebalance].
//end::usage[]

//tag::return-value[]
Expand Down Expand Up @@ -451,12 +452,10 @@ include::ROOT:partial$query-context.adoc[tag=section]

.Move the `def_inventory_airport_faa` index from one node to another
====
Create a cluster of 3 nodes and then go to menu:Settings[Sample buckets] to install the `travel-sample` bucket.
Create a cluster of 3 nodes and install the `travel-sample` bucket.
The indexes are then installed in a round-robin fashion and distributed over the 3 nodes.

image::alter-index_servers_step1.png["The Indexes tab showing def_inventory_airport_faa on 192.168.10.10"]

Then move the `def_inventory_airport_faa` index from its original node (192.168.10.*10* in this example) to a new node (192.168.10.*11* in this example).
Then move the `def_inventory_airport_faa` index from its original node (`svc-dqi-node-001` in this example) to a new node (`svc-dqi-node-002` in this example).

[source,sqlpp]
----
Expand All @@ -469,48 +468,55 @@ You should see:
----
include::example$n1ql-language-reference/alter-idx-move.jsonc[]
----

image::alter-index_servers_step2.png["The Indexes tab showing def_inventory_airport_faa on 192.168.10.11"]
====

.Create and move an index replica from one node to another
====
Create an index on node 192.168.10.10 with a replica on node 192.168.10.11, then move its replica from node 192.168.10.*11* to 192.168.10.*12*.
Create an index on node `svc-dqi-node-001` with a replica on node `svc-dqi-node-002`, then move its replica from node `svc-dqi-node-002` to `svc-dqi-node-003`.

[source,sqlpp]
----
CREATE INDEX country_idx ON airport(country, city)
USING GSI
WITH {"nodes": ["192.168.10.10:8091", "192.168.10.11:8091"]};
WITH {"nodes": ["svc-dqi-node-001:18091",
"svc-dqi-node-002:18091"]};

ALTER INDEX country_idx ON airport
WITH {"action": "move", "nodes": ["192.168.10.10:8091", "192.168.10.12:8091"]};
WITH {"action": "move",
"nodes": ["svc-dqi-node-001:18091",
"svc-dqi-node-003:18091"]};
----
====

.Moving multiple replicas
====
Create an index on node 192.168.10.10 with replicas on nodes 192.168.10.*11* and 192.168.10.*12*, then move the replicas to nodes 192.168.10.*13* and 192.168.10.*14*.
Create an index on node `svc-dqi-node-001` with replicas on nodes `svc-dqi-node-002` and `svc-dqi-node-003`, then move the replicas to nodes `svc-dqi-node-004` and `svc-dqi-node-005`.

[source,sqlpp]
----
CREATE INDEX country_idx ON airport(country, city)
WITH {"nodes": ["192.168.10.10:8091", "192.168.10.11:8091", "192.168.10.12:8091"]};
WITH {"nodes": ["svc-dqi-node-001:18091",
"svc-dqi-node-002:18091",
"svc-dqi-node-003:18091"]};

ALTER INDEX country_idx ON airport
WITH {"action": "move",
"nodes": ["192.168.10.10:8091", "192.168.10.13:8091", "192.168.10.14:8091"]};
"nodes": ["svc-dqi-node-001:18091",
"svc-dqi-node-004:18091",
"svc-dqi-node-005:18091"]};
----
====

.Increasing the number of replicas
====
Create an index on node 192.168.10.10 with replicas on nodes 192.168.10.*11* and 192.168.10.*12*, then increase the number of replicas to 4 and specify that new replicas may be placed on any available index nodes in the cluster.
Create an index on node `svc-dqi-node-001` with replicas on nodes `svc-dqi-node-002` and `svc-dqi-node-003`, then increase the number of replicas to 4 and specify that new replicas may be placed on any available index nodes in the cluster.

[source,sqlpp]
----
CREATE INDEX country_idx ON airport(country, city)
WITH {"nodes": ["192.168.10.10:8091", "192.168.10.11:8091", "192.168.10.12:8091"]};
WITH {"nodes": ["svc-dqi-node-001:18091",
"svc-dqi-node-002:18091",
"svc-dqi-node-003:18091"]};

ALTER INDEX country_idx ON airport
WITH {"action": "replica_count", "num_replica": 4};
Expand All @@ -519,32 +525,36 @@ WITH {"action": "replica_count", "num_replica": 4};

.Increasing the number of replicas and restricting the nodes
====
Create an index on node 192.168.10.10 with replicas on nodes 192.168.10.*11* and 192.168.10.*12*, then increase the number of replicas to 4, and specify that replicas may now also be placed on nodes 192.168.10.*13* and 192.168.10.*14*.
Create an index on node `svc-dqi-node-001` with replicas on nodes `svc-dqi-node-002` and `svc-dqi-node-003`, then increase the number of replicas to 4, and specify that replicas may now also be placed on nodes `svc-dqi-node-004` and `svc-dqi-node-005`.

[source,sqlpp]
----
CREATE INDEX country_idx ON airport(country, city)
WITH {"nodes": ["192.168.10.10:8091", "192.168.10.11:8091", "192.168.10.12:8091"]};
WITH {"nodes": ["svc-dqi-node-001:18091",
"svc-dqi-node-002:18091",
"svc-dqi-node-003:18091"]};

ALTER INDEX country_idx ON airport
WITH {"action": "replica_count",
"num_replica": 4,
"nodes": ["192.168.10.10:8091",
"192.168.10.11:8091",
"192.168.10.12:8091",
"192.168.10.13:8091",
"192.168.10.14:8091"]};
"nodes": ["svc-dqi-node-001:18091",
"svc-dqi-node-002:18091",
"svc-dqi-node-003:18091",
"svc-dqi-node-004:18091",
"svc-dqi-node-005:18091"]};
----
====

.Decreasing the number of replicas
====
Create an index on node 192.168.10.10 with replicas on nodes 192.168.10.*11* and 192.168.10.*12*, then decrease the number of replicas to 1.
Create an index on node `svc-dqi-node-001` with replicas on nodes `svc-dqi-node-002` and `svc-dqi-node-003`, then decrease the number of replicas to 1.

[source,sqlpp]
----
CREATE INDEX country_idx ON airport(country, city)
WITH {"nodes": ["192.168.10.10:8091", "192.168.10.11:8091", "192.168.10.12:8091"]};
WITH {"nodes": ["svc-dqi-node-001:18091",
"svc-dqi-node-002:18091",
"svc-dqi-node-003:18091"]};

ALTER INDEX country_idx ON airport
WITH {"action": "replica_count", "num_replica": 1};
Expand All @@ -553,18 +563,18 @@ WITH {"action": "replica_count", "num_replica": 1};

.Dropping a specific replica
====
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.
Create an index with 2 replicas, and specify that nodes `svc-dqi-node-001`, `svc-dqi-node-002`, `svc-dqi-node-003`, and `svc-dqi-node-004` should be available for index and replica placement.
Then delete replica 2.

[source,sqlpp]
----
CREATE INDEX country_idx ON airport(country, city)
USING GSI
WITH {"num_replica": 2,
"nodes": ["192.168.10.10:8091",
"192.168.10.11:8091",
"192.168.10.12:8091",
"192.168.10.13:8091"]};
"nodes": ["svc-dqi-node-001:18091",
"svc-dqi-node-002:18091",
"svc-dqi-node-003:18091",
"svc-dqi-node-004:18091"]};

ALTER INDEX country_idx ON airport
WITH {"action": "drop_replica", "replicaId": 2};
Expand Down
50 changes: 28 additions & 22 deletions modules/n1ql/pages/n1ql-language-reference/altervectorindex.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
= ALTER VECTOR INDEX
:description: The ALTER VECTOR INDEX statement moves the placement of an existing index or replica among different GSI nodes.
:page-edition: Enterprise Edition
:page-status: Couchbase Server 8.0
:page-toclevels: 2
:imagesdir: ../../assets/images
Expand Down Expand Up @@ -56,7 +55,7 @@ include::alterindex.adoc[tags=return-value]
To try the examples in this section, you must do the following:

. Create a cluster of 3 nodes.
The examples in this section assume that the 3 nodes have the IP addresses 172.19.0.2, 172.19.0.3, and 172.19.0.4.
The examples in this section assume that the 3 nodes have the names `svc-dqi-node-001`, `svc-dqi-node-002`, and `svc-dqi-node-003`.
The nodes in your cluster may have different names or IP addresses.

. Install the vector sample data as described in {prerequisites}[Prerequisites].
Expand All @@ -66,7 +65,7 @@ For more information, see xref:n1ql:n1ql-intro/queriesandresults.adoc#query-cont

.Create and move an index from one node to another
====
Create a Hyperscale Vector index on node 172.19.0.2.
Create a Hyperscale Vector index on node `svc-dqi-node-001`.

[source,sqlpp]
----
Expand All @@ -75,23 +74,23 @@ CREATE VECTOR INDEX hyperscale_idx_move
WITH {"dimension": 1536,
"similarity": "L2",
"description": "IVF8,SQ4",
"nodes": "172.19.0.2:8091"}
"nodes": "svc-dqi-node-001:18091"}
----

Then move the index from its original node (172.19.0.*2* in this example) to a new node (172.19.0.*3* in this example).
Then move the index from its original node (`svc-dqi-node-001` in this example) to a new node (`svc-dqi-node-002` in this example).

[source,sqlpp]
----
ALTER VECTOR INDEX hyperscale_idx_move ON rgb
WITH {"action": "move", "nodes": ["172.19.0.3:8091"]};
WITH {"action": "move", "nodes": ["svc-dqi-node-002:18091"]};
----

To check the node where the index is located, see xref:manage:manage-indexes/manage-indexes.adoc[].
====

.Create and move an index replica from one node to another
====
Create a Hyperscale Vector index on node 172.19.0.2 with a replica on node 172.19.0.3, then move its replica from node 172.19.0.*3* to 172.19.0.*4*.
Create a Hyperscale Vector index on node `svc-dqi-node-001` with a replica on node `svc-dqi-node-002`, then move its replica from node `svc-dqi-node-002` to `svc-dqi-node-003`.

[source,sqlpp]
----
Expand All @@ -100,16 +99,19 @@ CREATE VECTOR INDEX hyperscale_rep_move
WITH {"dimension": 1536,
"similarity": "L2",
"description": "IVF8,SQ4",
"nodes": ["172.19.0.2:8091", "172.19.0.3:8091"]};
"nodes": ["svc-dqi-node-001:18091",
"svc-dqi-node-002:18091"]};

ALTER VECTOR INDEX hyperscale_rep_move ON rgb
WITH {"action": "move", "nodes": ["172.19.0.2:8091", "172.19.0.4:8091"]};
WITH {"action": "move",
"nodes": ["svc-dqi-node-001:18091",
"svc-dqi-node-003:18091"]};
----
====

.Increase the number of replicas
====
Create a Hyperscale Vector index on node 172.19.0.2 with a replica on nodes 172.19.0.*3*, then increase the number of replicas to 2 and specify that new replicas may be placed on any available index nodes in the cluster.
Create a Hyperscale Vector index on node `svc-dqi-node-001` with a replica on nodes `svc-dqi-node-002`, then increase the number of replicas to 2 and specify that new replicas may be placed on any available index nodes in the cluster.

[source,sqlpp]
----
Expand All @@ -118,7 +120,8 @@ CREATE VECTOR INDEX hyperscale_rep_multi
WITH {"dimension": 1536,
"similarity": "L2",
"description": "IVF8,SQ4",
"nodes": ["172.19.0.2:8091", "172.19.0.3:8091"]};
"nodes": ["svc-dqi-node-001:18091",
"svc-dqi-node-002:18091"]};

ALTER VECTOR INDEX hyperscale_rep_multi ON rgb
WITH {"action": "replica_count", "num_replica": 2};
Expand All @@ -127,7 +130,7 @@ WITH {"action": "replica_count", "num_replica": 2};

.Increase the number of replicas and specify the nodes
====
Create a Hyperscale Vector index on node 172.19.0.2 with a replica on node 172.19.0.3, then increase the number of replicas to 2, and specify that replicas may be placed on nodes 172.19.0.*3* and 172.19.0.*4*.
Create a Hyperscale Vector index on node `svc-dqi-node-001` with a replica on node `svc-dqi-node-002`, then increase the number of replicas to 2, and specify that replicas may be placed on nodes `svc-dqi-node-002` and `svc-dqi-node-003`.

[source,sqlpp]
----
Expand All @@ -136,20 +139,21 @@ CREATE VECTOR INDEX hyperscale_rep_increase
WITH {"dimension": 1536,
"similarity": "L2",
"description": "IVF8,SQ4",
"nodes": ["172.19.0.2:8091", "172.19.0.3:8091"]};
"nodes": ["svc-dqi-node-001:18091",
"svc-dqi-node-002:18091"]};

ALTER VECTOR INDEX hyperscale_rep_increase ON rgb
WITH {"action": "replica_count",
"num_replica": 2,
"nodes": ["172.19.0.2:8091",
"172.19.0.3:8091",
"172.19.0.4:8091"]};
"nodes": ["svc-dqi-node-001:18091",
"svc-dqi-node-002:18091",
"svc-dqi-node-003:18091"]};
----
====

.Decrease the number of replicas
====
Create a Hyperscale Vector index on node 172.19.0.2 with replicas on nodes 172.19.0.*3* and 172.19.0.*4*, then decrease the number of replicas to 1.
Create a Hyperscale Vector index on node `svc-dqi-node-001` with replicas on nodes `svc-dqi-node-002` and `svc-dqi-node-003`, then decrease the number of replicas to 1.

[source,sqlpp]
----
Expand All @@ -158,7 +162,9 @@ CREATE VECTOR INDEX hyperscale_rep_decrease
WITH {"dimension": 1536,
"similarity": "L2",
"description": "IVF8,SQ4",
"nodes": ["172.19.0.2:8091", "172.19.0.3:8091", "172.19.0.4:8091"]};
"nodes": ["svc-dqi-node-001:18091",
"svc-dqi-node-002:18091",
"svc-dqi-node-003:18091"]};

ALTER VECTOR INDEX hyperscale_rep_decrease ON rgb
WITH {"action": "replica_count", "num_replica": 1};
Expand All @@ -167,7 +173,7 @@ WITH {"action": "replica_count", "num_replica": 1};

.Drop a specific replica
====
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.
Create a Hyperscale Vector index with 2 replicas, and specify that nodes `svc-dqi-node-001`, `svc-dqi-node-002`, and `svc-dqi-node-003` should be available for index and replica placement.
Then delete replica 2.

[source,sqlpp]
Expand All @@ -178,9 +184,9 @@ CREATE VECTOR INDEX hyperscale_rep_drop
"similarity": "L2",
"description": "IVF8,SQ4",
"num_replica": 2,
"nodes": ["172.19.0.2:8091",
"172.19.0.3:8091",
"172.19.0.4:8091"]};
"nodes": ["svc-dqi-node-001:18091",
"svc-dqi-node-002:18091",
"svc-dqi-node-003:18091"]};

ALTER VECTOR INDEX hyperscale_rep_drop ON rgb
WITH {"action": "drop_replica", "replicaId": 2};
Expand Down
Loading