Replication

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 is disabled by default. It can be enabled per collection in the collection configuration. 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.

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, the collection's replication factor overrides the minimum replication factor.

from weaviate.classes.config import Configureclient.collections.create(    "Article",    replication_config=Configure.replication(        factor=3,    ),)

import { configure } from 'weaviate-client';

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)
  }
}

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 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.

When Weaviate detects inconsistent data across nodes, it attempts to repair the out of sync data.

Weaviate offers async replication to proactively detect inconsistencies. In earlier versions, Weaviate uses a 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 environment variable to true. The replicationConfig section is used to set the replication factor and to fine-tune async replication via asyncConfig:

from weaviate.classes.config import Configureclient.collections.create(    "Article",    # Async replication runs by default when the replication factor is greater than 1    replication_config=Configure.replication(        factor=3,    ),)

import { configure } from 'weaviate-client';

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

Async replication helps achieve consistency for data replicated across multiple nodes.

Update the following environment variables to configure async replication for your particular use case.

• 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.

• Set the frequency of the logger: ASYNC_REPLICATION_LOGGING_FREQUENCY Define how often the async replication background process will log events.

• 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 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.

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.

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 are ONE, QUORUM (replication_factor / 2 + 1) and ALL.

The consistency_level can be specified at query time:

# Get an object by ID, with consistency level ONE
curl "http://localhost:8080/v1/objects/{ClassName}/{id}?consistency_level=ONE"

from weaviate.classes.config import ConsistencyLevel

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.

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.

var jeopardyWithConsistency = client.collections.use("JeopardyQuestion")    .withConsistencyLevel(ConsistencyLevel.QUORUM);var response = jeopardyWithConsistency.query.fetchObjectById(uuid);System.out.println(response.get().properties());

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);

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"

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 or programmatically through client libraries.

• Concepts: Replication Architecture
• Configuring Async Replication

Have a question or feedback? Here's how to reach us.