Replication

     

Prerequisites

• Concepts: Replication Architecture

Weaviate instances can be replicated to increase availability and read throughput, and to enable zero-downtime upgrades. On this page, you will learn how to set replication for your Weaviate instance.

For more about how replication is designed and built in Weaviate, see the Replication Architecture pages.

How to configure: Schema

Replication is disabled by default and can be enabled per data class in the schema. This means you can set different replication factors per class in your dataset. To enable replication on a class, the replication factor has to be set, which looks like the following:

{
  "class": "ExampleClass",
  "properties": [
    {
      "name": "exampleProperty",
      "dataType": [
        "text"
      ]
    }
  ],
  "replicationConfig": {
    "factor": 3   # Integer, default 1. How many copies of this class will be stored.
  }
}

Here's an example for all clients:

Python

import weaviate

client = weaviate.Client("http://localhost:8080")

class_obj = {
    "class": "Article",
    "properties": [
        {
            "dataType": [
                "string"
            ],
            "name": "title",
        },
    ],
    "replicationConfig": {
      "factor": 3
    }
}

client.schema.create_class(class_obj)

JavaScript

const weaviate = require('weaviate-client');

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

let classObj = {
    class: 'Article',
    properties: [
        {
            dataType: [
                'string'
            ],
            description: 'Title of the article',
            name: 'title'
        }
    ],
    replicationConfig: {
      factor: 3
    }
};

client
  .schema
  .classCreator()
  .withClass(classObj)
  .do()
  .then(res => {
    console.log(res)
  })
  .catch(err => {
    console.error(err)
  });

Go

package main

import (
  "context"

  "github.com/weaviate/weaviate-go-client/v4/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)
  }
}

Java

package io.weaviate;

import java.util.ArrayList;
import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.schema.model.DataType;
import io.weaviate.client.v1.schema.model.Property;
import io.weaviate.client.v1.schema.model.WeaviateClass;
import io.weaviate.client.v1.misc.model.ReplicationConfig;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    ReplicationConfig replicationConfig = ReplicationConfig.builder()
      .factor(3)
      .build();

    WeaviateClass clazz = WeaviateClass.builder()
      .className("Article")
      .replicationConfig(replicationConfig)
      .properties(new ArrayList() { {
        add(Property.builder()
          .dataType(new ArrayList(){ { add(DataType.STRING); } })
          .name("title")
          .build());
      } })
      .build();

    Result<Boolean> result = client.schema().classCreator().withClass(clazz).run();
    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

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

When you set this replication factor in the data schema before you add data, you will have 3 replicas of the data stored. Weaviate can also handle changing this setting after you imported the data. Then the data is copied to the new replica nodes (if there are enough nodes), but note that this is experimental and will be more stable in the future.

Note:

Changing the replication factor after adding data is an experimental feature as of v1.17 and will become more stable in the future.

The data schema has a write consistency level of ALL, which means when you upload or update a schema, this will be sent to ALL nodes (via a coordinator node). The coordinator node waits for a successful acknowledgement from ALL nodes before sending a success message back to the client. This ensures a highly consistent schema in your distributed Weaviate setup.

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 acknowledgement 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 /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).

Python

import weaviate
from weaviate.data.replication import ConsistencyLevel

client = weaviate.Client("http://localhost:8080")

data_object = (
  client.data_object.get_by_id(
    uuid="36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
    class_name="MyClass",
    consistency_level=ConsistencyLevel.ONE,
  )
)

# The parameter "consistency_level" can be one of ConsistencyLevel.ALL,
# ConsistencyLevel.QUORUM (default), or ConsistencyLevel.ONE. Determines how many
# replicas must acknowledge a request before it is considered successful.

print(data_object)

JavaScript

const weaviate = require('weaviate-client');

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

client
    .data
    .getterById()
    .withClassName('MyClass')
    .withId('36ddd591-2dee-4e7e-a3cc-eb86d30a4303')
    .withConsistencyLevel('ONE')  // default QUORUM
    .do()
    .then(res => {
        console.log(res)
    })
    .catch(err => {
        console.error(err)
    });

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

package main

import (
    "context"
    "fmt"

    "github.com/weaviate/weaviate-go-client/v4/weaviate/data/replication"  // for consistency levels
    "github.com/weaviate/weaviate-go-client/v4/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

package io.weaviate;

import java.util.List;
import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.data.model.WeaviateObject;
import io.weaviate.client.v1.data.replication.model.ConsistencyLevel;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    Result<List<WeaviateObject>> result = client.data().objectsGetter()
      .withClassName("MyClass")
      .withID("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")
      .withConsistencyLevel(ConsistencyLevel.ONE)  // default QUORUM
      .run();

    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

// The parameter passed to `withConsistencyLevel` can be one of:
// * ConsistencyLevel.ALL,
// * ConsistencyLevel.QUORUM (default), or
// * ConsistencyLevel.ONE.
//
// It determines how many replicas must acknowledge a request
// before it is considered successful.

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

More Resources

If you can't find the answer to your question here, please look at the:

1. Frequently Asked Questions. Or,
2. Knowledge base of old issues. Or,
3. For questions: Stackoverflow. Or,
4. For issues: GitHub. Or,
5. Ask your question in the Slack channel.