Weaviate instances can be replicated. Replication can improve read throughput, improve availability, and enable zero-downtime upgrades. For more details on how replication is designed and built in Weaviate, see [Replication Architecture](../replication-architecture/index.md). ## How to configure :::callout{intent="warning" title="Replication factor change"} The replication factor of a collection cannot be updated by updating the collection's definition. From `v1.32` by using [replica movement](replica-movement.md), the [replication factor](../reference-configuration/collections.md#replication) of a shard can be changed. ::: Replication is disabled by default. It can be enabled per collection in the [collection configuration](../how-to-manage-collections/multi-node-setup.md#replication-settings). This means you can set different replication factors per class in your dataset. To enable replication, you can set one or both of the following: - `REPLICATION_MINIMUM_FACTOR` environment variable for the entire Weaviate instance, or - `replicationFactor` parameter for a collection. ### Weaviate-wide minimum replication factor The `REPLICATION_MINIMUM_FACTOR` environment variable sets the minimum replication factor for all collections in the Weaviate instance. If you set the [replication factor for a collection](#replication-factor-for-a-collection), the collection's replication factor overrides the minimum replication factor. ### Replication factor for a collection :::code-group{sync="languages"} ```python title="Python" {5-7} from weaviate.classes.config import Configure client.collections.create( "Article", replication_config=Configure.replication( factor=3, ), ) ``` ```typescript title="JavaScript/TypeScript" import { configure } from 'weaviate-client'; ``` ```go title="Go" package main import ( "context" "github.com/weaviate/weaviate-go-client/v5/weaviate" "github.com/weaviate/weaviate/entities/models" ) func main() { cfg := weaviate.Config{ Host: "localhost:8080", Scheme: "http", } client, err := weaviate.NewClient(cfg) if err != nil { panic(err) } classObj := &models.Class{ Class: "Article", Properties: []*models.Property{ { DataType: []string{"string"}, Name: "title", } }, ReplicationConfig: &models.ReplicationConfig{ Factor: 3, } } err := client.Schema().ClassCreator().WithClass(classObj).Do(context.Background()) if err != nil { panic(err) } } ``` ```bash title="Curl" curl \ -X POST \ -H "Content-Type: application/json" \ -d '{ "class": "Article", "properties": [ { "dataType": [ "string" ], "description": "Title of the article", "name": "title" } ], "replicationConfig": { "factor": 3 } }' \ http://localhost:8080/v1/schema ``` ::: In this example, there are three replicas. If you set the replication factor before you import data, all of the data is replicated three times. The replication factor can be modified after you add data to a collection. If you modify the replication factor afterwards, new data is copied across the new and pre-existing replica nodes. The example data schema has a [write consistency](../replication-architecture/consistency.md#tunable-write-consistency) level of `ALL`. When you upload or update a schema, the changes are sent to `ALL` nodes (via a coordinator node). The coordinator node waits for a successful acknowledgment from `ALL` nodes before sending a success message back to the client. This ensures a highly consistent schema in your distributed Weaviate setup. ## Data consistency When Weaviate detects inconsistent data across nodes, it attempts to repair the out of sync data. Weaviate offers [async replication](../replication-architecture/consistency.md#async-replication) to proactively detect inconsistencies. In earlier versions, Weaviate uses a [repair-on-read](../replication-architecture/consistency.md#repair-on-read) strategy to repair inconsistencies at read time. Repair-on-read is automatic. As of Weaviate `v1.38`, async replication is also **enabled by default** for any collection with a replication factor greater than `1`. There is no longer a per-collection flag to switch it on. To turn it off cluster-wide, set the [`ASYNC_REPLICATION_DISABLED`](../database-configuration/overview.md#async-replication) environment variable to `true`. The `replicationConfig` section is used to set the replication factor and to fine-tune async replication via `asyncConfig`: :::code-group{sync="languages"} ```python title="Python" {5-8} from weaviate.classes.config import Configure client.collections.create( "Article", # Async replication runs by default when the replication factor is greater than 1 replication_config=Configure.replication( factor=3, ), ) ``` ```typescript title="JavaScript/TypeScript" import { configure } from 'weaviate-client'; ``` ```bash title="cURL" curl \ -X POST \ -H "Content-Type: application/json" \ -d '{ "class": "Article", "properties": [ { "dataType": [ "string" ], "description": "Title of the article", "name": "title" } ], "replicationConfig": { "factor": 3 } }' \ http://localhost:8080/v1/schema ``` ::: ### Configure async replication settings :::callout{intent="info" title="Collection-level configuration — Added in `v1.36`"} Async replication runs by default for any collection with a replication factor greater than `1` (as of `v1.38`). To fine-tune its behavior for a specific collection, set the `asyncConfig` object in `replicationConfig`. Cluster-wide environment variable settings override per-collection settings. See [Collection `asyncConfig` parameters](../reference-configuration/collections.md#asyncconfig-parameters) for details. ::: Async replication helps achieve consistency for data replicated across multiple nodes. Update the following [environment variables](../database-configuration/overview.md#async-replication) to configure async replication for your particular use case. #### Worker limits - **Set the scheduler worker pool size:** `ASYNC_REPLICATION_SCHEDULER_WORKERS` Set the number of workers in the cluster-wide pool that run async replication work across all shards and tenants. Default: `10`, maximum: `100`. As of `v1.38` this replaces the removed `ASYNC_REPLICATION_CLUSTER_MAX_WORKERS` variable and the per-collection `maxWorkers` option; collections share this single pool. - **Set hash tree init concurrency:** `ASYNC_REPLICATION_HASHTREE_INIT_CONCURRENCY` Set how many shards may build their hash tree concurrently when async replication starts up. Default: `100`. #### Logging - **Set the frequency of the logger:** `ASYNC_REPLICATION_LOGGING_FREQUENCY` Define how often the async replication background process will log events. #### Data comparison - **Set the frequency of comparisons:** `ASYNC_REPLICATION_FREQUENCY` Define how often each node compares its local data with other nodes. - **Set comparison timeout:** `ASYNC_REPLICATION_DIFF_PER_NODE_TIMEOUT` Optionally configure a timeout for how long to wait during comparison when a node is unresponsive. - **Configure hash tree height:** `ASYNC_REPLICATION_HASHTREE_HEIGHT` Specify the size of the hash tree, which helps narrow down data differences by comparing hash digests at multiple levels instead of scanning entire datasets. See [this page](../replication-architecture/consistency.md#memory-and-performance-considerations-for-async-replication) for more information on the memory and performance considerations for async replication. - **Batch size for digest comparison:** `ASYNC_REPLICATION_DIFF_BATCH_SIZE` Define the number of objects whose digest (e.g., last update time) is compared between nodes before propagating actual objects. :::callout{intent="note" title="Removed in `v1.38`"} The `ASYNC_REPLICATION_CLUSTER_MAX_WORKERS` (replaced by `ASYNC_REPLICATION_SCHEDULER_WORKERS`) and `ASYNC_REPLICATION_ALIVE_NODES_CHECKING_FREQUENCY` environment variables were removed in `v1.38` when async replication moved to a centralized scheduler. ::: #### Data synchronization Once differences between nodes are detected, Weaviate propagates outdated or missing data. Configure synchronization as follows: - **Set the frequency of propagation:** `ASYNC_REPLICATION_FREQUENCY_WHILE_PROPAGATING` After synchronization is completed on a node, temporarily adjust the data comparison frequency to the set value. - **Set pre-propagation timeout:** `ASYNC_REPLICATION_PRE_PROPAGATION_TIMEOUT` Configure a delay before propagation begins to allow in-progress write operations to complete across nodes. - **Set propagation timeout:** `ASYNC_REPLICATION_PROPAGATION_TIMEOUT` Optionally configure a timeout for how long to wait during propagation when a node is unresponsive. - **Set propagation delay:** `ASYNC_REPLICATION_PROPAGATION_DELAY` Define a delay period to allow asynchronous write operations to reach all nodes before propagating new or updated objects. - **Batch size for data propagation:** `ASYNC_REPLICATION_PROPAGATION_BATCH_SIZE` Define the number of objects that are sent in each synchronization batch during the propagation phase. - **Set propagation limits:** `ASYNC_REPLICATION_PROPAGATION_LIMIT` Enforce a limit on the number of out-of-sync objects to be propagated per replication iteration. - **Set propagation concurrency:** `ASYNC_REPLICATION_PROPAGATION_CONCURRENCY` Specify the number of concurrent workers that can send batches of objects to other nodes, allowing multiple propagation batches to be sent simultaneously. :::callout{intent="tip"} Tweak these settings based on your cluster size and network latency to achieve optimal performance. Smaller batch sizes and shorter timeouts may be beneficial for high-traffic clusters, while larger clusters might require more conservative settings. ::: ## How to use: Queries When you add (write) or query (read) data, one or more replica nodes in the cluster will respond to the request. How many nodes need to send a successful response and acknowledgment to the coordinator node depends on the `consistency_level`. Available [consistency levels](../replication-architecture/consistency.md) are `ONE`, `QUORUM` (replication\_factor / 2 + 1) and `ALL`. The `consistency_level` can be specified at query time: ```bash # Get an object by ID, with consistency level ONE curl "http://localhost:8080/v1/objects/{ClassName}/{id}?consistency_level=ONE" ``` :::callout{intent="note"} In v1.17, only [read queries that get data by ID](../how-to-manage-objects/read.md#get-an-object-by-id) had a tunable consistency level. All other object-specific REST endpoints (read or write) used the consistency level `ALL`. Starting with v1.18, all write and read queries are tunable to either `ONE`, `QUORUM` (default) or `ALL`. GraphQL endpoints use the consistency level `ONE` (in both versions). ::: :::code-group{sync="languages"} ```python title="Python" from weaviate.classes.config import ConsistencyLevel ``` ```typescript title="JavaScript/TypeScript" {1} const myCollection = client.collections.use('Article').withConsistency('QUORUM'); const result = await myCollection.query.fetchObjectById("36ddd591-2dee-4e7e-a3cc-eb86d30a4303") console.log(JSON.stringify(result, null, 2)); // The parameter passed to `withConsistencyLevel` can be one of: // * 'ALL', // * 'QUORUM' (default), or // * 'ONE'. // // It determines how many replicas must acknowledge a request // before it is considered successful. ``` ```go title="Go" package main import ( "context" "fmt" "github.com/weaviate/weaviate-go-client/v5/weaviate/data/replication" // for consistency levels "github.com/weaviate/weaviate-go-client/v5/weaviate" ) func main() { cfg := weaviate.Config{ Host: "localhost:8080", Scheme: "http", } client, err := weaviate.NewClient(cfg) if err != nil { panic(err) } data, err := client.Data().ObjectsGetter(). WithClassName("MyClass"). WithID("36ddd591-2dee-4e7e-a3cc-eb86d30a4303"). WithConsistencyLevel(replication.ConsistencyLevel.ONE). // default QUORUM Do(context.Background()) if err != nil { panic(err) } fmt.Printf("%v", data) } // The parameter passed to "WithConsistencyLevel" can be one of: // * replication.ConsistencyLevel.ALL, // * replication.ConsistencyLevel.QUORUM (default), or // * replication.ConsistencyLevel.ONE. // // It determines how many replicas must acknowledge a request // before it is considered successful. ``` ```java title="Java" {3} var jeopardyWithConsistency = client.collections.use("JeopardyQuestion") .withConsistencyLevel(ConsistencyLevel.QUORUM); var response = jeopardyWithConsistency.query.fetchObjectById(uuid); System.out.println(response.get().properties()); ``` ```csharp title="C#" var jeopardy = client .Collections.Use("JeopardyQuestion") .WithConsistencyLevel(ConsistencyLevels.Quorum); var response = await jeopardy.Query.FetchObjectByID((Guid)validId); // The parameter passed to `withConsistencyLevel` can be one of: // * 'ALL', // * 'QUORUM' (default), or // * 'ONE'. // // It determines how many replicas must acknowledge a request // before it is considered successful. Console.WriteLine(response); ``` ```bash title="Curl" curl "http://localhost:8080/v1/objects/MyClass/36ddd591-2dee-4e7e-a3cc-eb86d30a4303?consistency_level=QUORUM" # The parameter "consistency_level" can be one of ALL, QUORUM (default), or ONE. Determines how many # replicas must acknowledge a request before it is considered successful. # curl "/v1/objects/{ClassName}/{id}?consistency_level=ONE" ``` ::: ## Replica movement and status :::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#tag/replication) or [programmatically through client libraries](replica-movement.md). ## Related pages - [Concepts: Replication Architecture](../replication-architecture/index.md) - [Configuring Async Replication](async-rep.md) ## 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=