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.

How to configure

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, the replication factor of a shard can be changed.

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.

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

Replication factor for a collection

PythonJavaScript/TypeScriptGoCurl

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

from weaviate.classes.config import Configure

client.collections.create(
    "Article",
    replication_config=Configure.replication(
        factor=3,
    ),
)

import { configure } from 'weaviate-client';

await client.collections.create({
  name: 'Article',
  replication: configure.replication({
    factor: 1
  }),
})

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.

Data consistency

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:

PythonJavaScript/TypeScriptCurl

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

import { configure } from 'weaviate-client';

await client.collections.create({
  name: 'Article',
  // Async replication runs by default when the replication factor is greater than 1
  replication: configure.replication({
    factor: 1,
  }),
})

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

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

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.

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

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.

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

note

In v1.17, only read queries that get data 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).

PythonJavaScript/TypeScriptGoJavaC#Curl

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

from weaviate.classes.config import ConsistencyLevel

questions = client.collections.use(collection_name).with_consistency_level(
    consistency_level=ConsistencyLevel.QUORUM
)
response = collection.query.fetch_object_by_id("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")

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

for o in response.objects:
    print(o.properties)  # Inspect returned objects

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"

Replica movement and status

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

Related pages

• Concepts: Replication Architecture
• Configuring Async Replication

Questions and feedback

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

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.