# Replica movement :::callout{intent="info" title="Added in `v1.32`"} ::: Beyond setting the initial replication factor, you can actively manage the placement of shard replicas within your Weaviate cluster. This is useful for rebalancing data after scaling, decommissioning nodes, or optimizing data locality. Replica movement is managed through a set of dedicated [RESTful API endpoints](/weaviate/api/rest) or through the client library API described below. :::callout{intent="info" title="Enable replica movement"} Replica movement is disabled by default. To use this feature, set the [`REPLICA_MOVEMENT_ENABLED`](../database-configuration/overview.md#REPLICA_MOVEMENT_ENABLED) environment variable to `true` on all nodes in your cluster. ::: When a replica movement is initiated, it changes the replication factor of that shard _only_, not the entire collection. A collection has a particular replication factor, but a shard (a subset of a collection), can have its own replication factor which can be different. If a replica COPY operation is made, this can be incremented. ## Check shard state Before initiating any movement, you might want to inspect the current distribution of replicas. You can retrieve the sharding state of an entire collection, or its specific shard. :::code-group{sync="languages"} ```python title="Python" sharding_state = client.cluster.query_sharding_state( collection=collection_name, # shard=shard_name, # Optional: specify a shard to filter results ) print(f"Shards in '{collection_name}': {[s.name for s in sharding_state.shards]}") for shard in sharding_state.shards: print(f"Nodes for shard '{shard.name}': {shard.replicas}") ``` ```typescript title="JavaScript/TypeScript" // JS/TS support coming soon ``` ```go title="Go" // Go support coming soon ``` ::: :::accordion{title="Code output"} ``` Shards in 'MyReplicatedDocCollection': ['0QK7V2bbAHQ2', 'arxzWNklLIU7', 'w5OcBGbNvRt4'] Nodes for shard '0QK7V2bbAHQ2': ['node3', 'node1'] Nodes for shard 'arxzWNklLIU7': ['node1', 'node2'] Nodes for shard 'w5OcBGbNvRt4': ['node2', 'node3'] ``` ::: ## Initiate a replica movement Copy or move a shard replica by specifying the the source node, destination node, collection name, shard ID and operation type (`MOVE` or `COPY`). :::code-group{sync="languages"} ```python title="Python" from weaviate.cluster.models import ReplicationType operation_id = client.cluster.replicate( collection=collection_name, shard=shard_name, source_node=source_node_name, target_node=target_node_name, replication_type=ReplicationType.COPY, # For copying a shard # replication_type=ReplicationType.MOVE, # For moving a shard ) print(f"Replication initiated, ID: {operation_id}") ``` ```typescript title="JavaScript/TypeScript" // JS/TS support coming soon ``` ```go title="Go" // Go support coming soon ``` ::: :::accordion{title="Code output"} ``` Replication initiated, ID: 32536c0e-09e1-4ea1-a2c5-e85af10a9d58 ``` ::: ## Check the status of a replication operation Shard replication operations are asynchronous. An operation status can be queried, with an option to view the full operation history. :::code-group{sync="languages"} ```python title="Python" op_status = client.cluster.replications.get( uuid=operation_id, include_history=True ) print(f"Status for {operation_id}: {op_status.status}") print(f"History for {operation_id}: {op_status.status_history}") ``` ```typescript title="JavaScript/TypeScript" // JS/TS support coming soon ``` ```go title="Go" // Go support coming soon ``` ::: :::accordion{title="Code output"} ``` Status for f771aae1-f3c4-4fac-bae6-90597e8c70bd: ReplicateOperationStatus(state=, errors=[]) History for f771aae1-f3c4-4fac-bae6-90597e8c70bd: [ReplicateOperationStatus(state=, errors=[]), ReplicateOperationStatus(state=, errors=[])] ``` ::: :::callout{intent="note"} The movement operation can have one of the following states: - `REGISTERED` - `HYDRATING` - `FINALIZING` - `INTEGRATING` - `DEHYDRATING` - `READY` - `CANCELLED` `INTEGRATING` was added in `v1.38.0`. On earlier versions the operation goes straight from `FINALIZING` to `DEHYDRATING` for a move, or to `READY` for a copy. To learn more about the replication states, check out [Concepts: Replication architecture](../replication-architecture/consistency.md#replica-movement). ::: ## List replication operations List all ongoing and completed operations. This can be filtered by node, collection and shard. :::code-group{sync="languages"} ```python title="Python" all_ops = client.cluster.replications.list_all() print(f"Total replication operations: {len(all_ops)}") filtered_ops = client.cluster.replications.query( collection=collection_name, target_node=target_node_name, ) print( f"Filtered operations for collection '{collection_name}' on '{target_node_name}': {len(filtered_ops)}" ) ``` ```typescript title="JavaScript/TypeScript" // JS/TS support coming soon ``` ```go title="Go" // Go support coming soon ``` ::: :::accordion{title="Code output"} ``` Total replication operations: 1 Filtered operations for collection 'MyReplicatedDocCollection' on 'node3': 1 ``` ::: ## Cancel a replication operation The operation will be stopped if possible. If successfully cancelled, its state will change to `CANCELLED`. :::code-group{sync="languages"} ```python title="Python" client.cluster.replications.cancel(uuid=operation_id) ``` ```typescript title="JavaScript/TypeScript" // JS/TS support coming soon ``` ```go title="Go" // Go support coming soon ``` ::: ## Delete a replication operation Remove a replication operation from the logs. If the operation is active, it will be cancelled first. :::code-group{sync="languages"} ```python title="Python" client.cluster.replications.delete(uuid=operation_id) ``` ```typescript title="JavaScript/TypeScript" // JS/TS support coming soon ``` ```go title="Go" // Go support coming soon ``` ::: ## Delete all replication operations Remove all replication operations from the logs. If any operations are active, they will be cancelled first. :::code-group{sync="languages"} ```python title="Python" client.cluster.replications.delete_all() ``` ```typescript title="JavaScript/TypeScript" // JS/TS support coming soon ``` ```go title="Go" // Go support coming soon ``` ::: ## Further resources - [RESTful API: Replication endpoints](/weaviate/api/rest) - [Concepts: Replication architecture](../replication-architecture/consistency.md#replica-movement) ## Questions and feedback Have a question or feedback? Here's how to reach us. ::::card-grid :::card{title="Community Forum" href="https://forum.weaviate.io/c/support" icon="messages-square"} Ask questions and connect with other developers on our **Community forum**. ::: :::card{title="Support" href="/guides/support-overview" icon="life-buoy"} Weaviate Cloud user or customer? Find the right channel on the **Support page**. ::: :::: ## Related pages - [Agents](./agents-index.md) - [AI-assisted Weaviate code generation](./ai-assisted-vibe-coding-index.md) - [APIs](./apis-index.md) - [Authorization and authentication](./authorization-and-authentication-index.md) - [Benchmarks](./benchmarks-index.md) - [Best practices](./best-practices-index.md) - [Client libraries](./clients-index.md) - [Client Libraries / SDKs](./client-libraries-index.md) - [Cloud](./cloud-index.md) - [Cloud account management](./cloud-account-management-index.md) # Agent Instructions This portal answers questions programmatically. To receive a synthesized, source-cited answer instead of crawling page by page, append the `?ask=` query parameter to any page URL on this site: /guides/quickstart?ask=how+do+I+authenticate Optional parameters: - `&goal=` steers the answer toward your objective (e.g. `&goal=write+a+python+client`). - `&version=