/v1/batch

Weaviate on Stackoverflow badge Weaviate issues on Github badge Weaviate total Docker pulls badge

💡 You are looking at older or release candidate documentation. The current Weaviate version is v1.15.1

With batch you can upload a lot of data objects in bulk. This saves time compared to a lot of single request.


Batch data objects

For sending data objects to Weaviate in bulk.

Method and URL

POST /v1/batch/objects

Parameters

The body requires the following field:

nametyperequireddescription
objectslist of data objectsyesa list of data objects, which correspond to the data object body

Example request

  import weaviate

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

first_object_props = {
    "name": "Jane Doe",
    "writesFor": [{
        "beacon": "weaviate://localhost/f81bfe5e-16ba-4615-a516-46c2ae2e5a80"
    }]
}

second_object_props = {
    "name": "John Doe",
    "writesFor": [{
        "beacon": "weaviate://localhost/f81bfe5e-16ba-4615-a516-46c2ae2e5a80"
    }]
}

# Python client specific configurations can be set with `client.batch.configure`
# the settings can be applied to both `objects` AND `references`.
# You have to only set them once.
client.batch.configure(
  # `batch_size` takes an `int` value to enable auto-batching
  # (`None` is used for manual batching)
  batch_size=100, 
  # dynamically update the `batch_size` based on import speed
  dynamic=False,
  # `timeout_retries` takes an `int` value to retry on time outs
  timeout_retries=3,
  # checks for batch-item creation errors
  # this is the default in weaviate-client >= 3.6.0
  callback=weaviate.util.check_batch_result,
)

with client.batch as batch:
  # Add object without a custom vector.
  # When using vectorization modules this can be used
  # or when you don't want to set a vector
  batch.add_data_object(first_object_props, 'Author', "36ddd591-2dee-4e7e-a3cc-eb86d30a4303")
  # Add object with a custom vector
  batch.add_data_object(second_object_props, 'Author', "36ddd591-2dee-4e7e-a3cc-eb86d30a4304", vector=[0.1, 0.2, 0.3])
  const weaviate = require("weaviate-client");

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

var toImport = [{
  class: "Author",
  id: '36ddd591-2dee-4e7e-a3cc-eb86d30a4303',
  properties: {
    name: "Jane Doe",
    writesFor: [{
      beacon: "weaviate://localhost/f81bfe5e-16ba-4615-a516-46c2ae2e5a80"
    }]
  }
},
{
  class: "Author",
  id: '36ddd591-2dee-4e7e-a3cc-eb86d30a4304',
  properties: {
    name: "John Doe",
    writesFor: [{
      beacon: "weaviate://localhost/f81bfe5e-16ba-4615-a516-46c2ae2e5a80"
    }]
  }
}];

client.batch
  .objectsBatcher()
  .withObject(toImport[0])
  .withObject(toImport[1])
  .do()
  .then(res => {
      console.log(res)
  })
  .catch(err => {
      console.error(err)
  });

/* The following is also possible:
const weaviate = require("weaviate-client");

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

const toImport = [
  client.data
    .creator()
    .withClassName('Author')
    .withId('36ddd591-2dee-4e7e-a3cc-eb86d30a4303')
    .withProperties({
      name: "Jane Doe",
      writesFor: [{
        beacon: "weaviate://localhost/f81bfe5e-16ba-4615-a516-46c2ae2e5a80"
      }]
    })
    .payload(), // note the .payload(), not .do()!
  client.data
    .creator()
    .withClassName('Author')
    .withId('36ddd591-2dee-4e7e-a3cc-eb86d30a4304')
    .withProperties({
      name: "John Doe",
      writesFor: [{
        beacon: "weaviate://localhost/f81bfe5e-16ba-4615-a516-46c2ae2e5a80"
      }]
    })
    .payload(), // note the .payload(), not .do()!
  ];

client.batch
      .objectsBatcher()
      .withObject(toImport[0])
      .withObject(toImport[1])
      .do()
      .then(res => {
        console.log(res)
      })
      .catch(err => {
          console.error(err)
      });
*/
  package main

import (
  "context"
  "fmt"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
  "github.com/semi-technologies/weaviate/entities/models"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  objects := []*models.Object{
    {
      Class: "Author",
      ID:    "36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
      Properties: map[string]interface{}{
        "name": "Jane Doe",
        "writesFor": map[string]string{
          "beacon": "weaviate://localhost/f81bfe5e-16ba-4615-a516-46c2ae2e5a80",
        },
      },
    },
    {
      Class: "Author",
      ID:    "36ddd591-2dee-4e7e-a3cc-eb86d30a4304",
      Properties: map[string]interface{}{
        "name": "John Doe",
        "writesFor": map[string]string{
          "beacon": "weaviate://localhost/f81bfe5e-16ba-4615-a516-46c2ae2e5a80",
        },
      },
    },
  }

  result, err := client.Batch().ObjectsBatcher().
    WithObject(objects[0]).
    WithObject(objects[1]).
    Do(context.Background())

  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
  package technology.semi.weaviate;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.batch.model.ObjectGetResponse;
import technology.semi.weaviate.client.v1.data.model.WeaviateObject;

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

    List<WeaviateObject> objects = new ArrayList() {
      {
        add(
          WeaviateObject.builder()
            .className("Author")
            .id("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")
            .properties(new HashMap() {
              {
                put("name", "Jane Doe");
                put("writesFor", new HashMap() {
                  {
                    put("beacon", "weaviate://localhost/f81bfe5e-16ba-4615-a516-46c2ae2e5a80");
                  }
                });
              }
            })
            .build()
        );
        add(
          WeaviateObject.builder()
            .className("Author")
            .id("36ddd591-2dee-4e7e-a3cc-eb86d30a4304")
            .properties(new HashMap() {
              {
                put("name", "John Doe");
                put("writesFor", new HashMap() {
                  {
                    put("beacon", "weaviate://localhost/f81bfe5e-16ba-4615-a516-46c2ae2e5a80");
                  }
                });
              }
            })
            .build()
        );
      }
    };

    Result<ObjectGetResponse[]> result = client.batch().objectsBatcher()
      .withObject(objects.get(0))
      .withObject(objects.get(1))
      .run();

    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}
  $ curl \
-X POST \
-H "Content-Type: application/json" \
-d '{
  "objects": [{
    "class": "Author",
    "id": "36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
    "properties": {
        "name": "Jane Doe",
        "writesFor": [{
          "beacon": "weaviate://localhost/f81bfe5e-16ba-4615-a516-46c2ae2e5a80"
        }]
    }
  }, {
    "class": "Author",
    "id": "36ddd591-2dee-4e7e-a3cc-eb86d30a4304",
    "properties": {
        "name": "John Doe",
        "writesFor": [{
          "beacon": "weaviate://localhost/f81bfe5e-16ba-4615-a516-46c2ae2e5a80"
        }]
    }
  }]
}' \
http://localhost:8080/v1/batch/objects

Batch references

For batching cross-references between data objects in bulk.

Method and URL

POST /v1/batch/references

Parameters

The body of the data object for a new object is a list of objects containing:

nametyperequireddescription
frombeaconyesThe beacon, in the form of weaviate://{host}/{Classname}/{id}/{cref_property_name}
tobeaconyesThe beacon, in the form of weaviate://{host}/{id}

Example request

  import weaviate

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

# Python client specific configurations can be set with `client.batch.configure`
# the settings can be applied to both `objects` AND `references`.
# You have to only set them once.
client.batch.configure(
  # `batch_size` takes an `int` value to enable auto-batching
  # (`None` is used for manual batching)
  batch_size=100, 
  # dynamically update the `batch_size` based on import speed
  dynamic=False,
  # `timeout_retries` takes an `int` value to retry on time outs
  timeout_retries=3,
  # checks for batch-item creation errors
  # this is the default in weaviate-client >= 3.6.0
  callback=weaviate.util.check_batch_result,
)

with client.batch as batch:
    # Format for batching is as follows:
    # client.batch.add_reference(
    #   from_object_uuid=<from_object_uuid>,
    #   from_object_class_name=<from_object_class_name>,
    #   from_property_name=<from_property_name>
    #   to_object_uuid=<to_object_uuid>,
    #   to_object_class_name=<to_object_class_name>,
    # )
    batch.add_reference(
      from_object_uuid="36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
      from_object_class_name="Author",
      from_property_name="wroteArticles",
      to_object_uuid="6bb06a43-e7f0-393e-9ecf-3c0f4e129064",
      to_object_class_name="Article",
    )
    batch.add_reference(
      from_object_uuid="36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
      from_object_class_name="Author",
      from_property_name="wroteArticles",
      to_object_uuid="b72912b9-e5d7-304e-a654-66dc63c55b32",
      to_object_class_name="Article",
    )
  const weaviate = require("weaviate-client");

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

client.batch
      .referencesBatcher()
      .withReference({
        from: `weaviate://localhost/Author/36ddd591-2dee-4e7e-a3cc-eb86d30a4303/wroteArticles`,
        to: `weaviate://localhost/Article/6bb06a43-e7f0-393e-9ecf-3c0f4e129064`,
        // prior to v1.14 omit the class name as part of the "to" beacon and specify it as weaviate://localhost/<id>
      })
      .withReference({
        from: `weaviate://localhost/Author/36ddd591-2dee-4e7e-a3cc-eb86d30a4303/wroteArticles`,
        to: `weaviate://localhost/Article/b72912b9-e5d7-304e-a654-66dc63c55b32`,
        // prior to v1.14 omit the class name as part of the "to" beacon and specify it as weaviate://localhost/<id>
      })
      .withReference({
        from: `weaviate://localhost/Author/36ddd591-2dee-4e7e-a3cc-eb86d30a4304/wroteArticles`,
        to: `weaviate://localhost/Article/b72912b9-e5d7-304e-a654-66dc63c55b32`,
        // prior to v1.14 omit the class name as part of the "to" beacon and specify it as weaviate://localhost/<id>
      })
      .do()
      .then(res => {
        console.log(res)
      })
      .catch(err => {
          console.error(err)
      });

/* This is also possible with a builder pattern:
const weaviate = require("weaviate-client");

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

client.batch
      .referencesBatcher()
      .withReference(
        client.batch
          .referencePayloadBuilder()
          .withFromClassName("Author")
          .withFromRefProp('wroteArticles')
          .withFromId("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")
          .withToClassName("Article") // prior to v1.14 omit .withToClassName()
          .withToId("6bb06a43-e7f0-393e-9ecf-3c0f4e129064")
          .payload()
      )
      .withReference(
        client.batch
          .referencePayloadBuilder()
          .withFromClassName("Author")
          .withFromRefProp('wroteArticles')
          .withFromId("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")
          .withToClassName("Article") // prior to v1.14 omit .withToClassName()
          .withToId("b72912b9-e5d7-304e-a654-66dc63c55b32")
          .payload()
      )
      .withReference(
        client.batch
          .referencePayloadBuilder()
          .withFromClassName("Author")
          .withFromRefProp('wroteArticles')
          .withFromId("36ddd591-2dee-4e7e-a3cc-eb86d30a4304")
          .withToClassName("Article") // prior to v1.14 omit .withToClassName()
          .withToId("b72912b9-e5d7-304e-a654-66dc63c55b32")
          .payload()
      )
      .do()
      .then(res => {
        console.log(res)
      })
      .catch(err => {
          console.error(err)
      });
*/
  package main

import (
  "context"
  "fmt"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
  "github.com/semi-technologies/weaviate/entities/models"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  ref := []*models.BatchReference{
    {
      From: "weaviate://localhost/Author/36ddd591-2dee-4e7e-a3cc-eb86d30a4303/wroteArticles",
      To:   "weaviate://localhost/Article/6bb06a43-e7f0-393e-9ecf-3c0f4e129064",
      // prior to v1.14 omit the class name as part of the "to" beacon and specify it as weaviate://localhost/<id>
    },
    {
      From: "weaviate://localhost/Author/36ddd591-2dee-4e7e-a3cc-eb86d30a4303/wroteArticles",
      To:   "weaviate://localhost/Article/b72912b9-e5d7-304e-a654-66dc63c55b32",
      // prior to v1.14 omit the class name as part of the "to" beacon and specify it as weaviate://localhost/<id>
    },
    {
      From: "weaviate://localhost/Author/36ddd591-2dee-4e7e-a3cc-eb86d30a4304/wroteArticles",
      To:   "weaviate://localhost/Article/b72912b9-e5d7-304e-a654-66dc63c55b32",
      // prior to v1.14 omit the class name as part of the "to" beacon and specify it as weaviate://localhost/<id>
    },
  }

  result, err := client.Batch().ReferencesBatcher().
    WithReference(ref[0]).
    WithReference(ref[1]).
    WithReference(ref[2]).
    Do(context.Background())

  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
  package technology.semi.weaviate;

import java.util.ArrayList;
import java.util.List;
import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.batch.model.BatchReference;
import technology.semi.weaviate.client.v1.batch.model.BatchReferenceResponse;

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

    List<BatchReference> refs = new ArrayList() {
      {
        add(
          BatchReference.builder()
            .from("weaviate://localhost/Author/36ddd591-2dee-4e7e-a3cc-eb86d30a4303/wroteArticles")
            .to("weaviate://localhost/Article/6bb06a43-e7f0-393e-9ecf-3c0f4e129064")
            // prior to v1.14 omit the class name as part of the "to" beacon and specify it as weaviate://localhost/<id>
            .build()
        );
        add(
          BatchReference.builder()
            .from("weaviate://localhost/Author/36ddd591-2dee-4e7e-a3cc-eb86d30a4303/wroteArticles")
            .to("weaviate://localhost/Article/b72912b9-e5d7-304e-a654-66dc63c55b32")
            // prior to v1.14 omit the class name as part of the "to" beacon and specify it as weaviate://localhost/<id>
            .build()
        );
        add(
          BatchReference.builder()
            .from("weaviate://localhost/Author/36ddd591-2dee-4e7e-a3cc-eb86d30a4304/wroteArticles")
            .to("weaviate://localhost/Article/b72912b9-e5d7-304e-a654-66dc63c55b32")
            // prior to v1.14 omit the class name as part of the "to" beacon and specify it as weaviate://localhost/<id>
            .build()
        );
      }
    };

    Result<BatchReferenceResponse[]> result = client.batch().referencesBatcher()
      .withReference(refs.get(0))
      .withReference(refs.get(1))
      .withReference(refs.get(2))
      .run();

    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}
  # Note that for this query to work with Weaviate versions older than v1.14 you
# need to omit the class name in the "to" beacon and specify it as
# weaviate://localhost/<id>. The long-form beacon used in "from" is unchanged.
$ curl \
-X POST \
-H "Content-Type: application/json" \
-d '[{
    "from": "weaviate://localhost/Author/36ddd591-2dee-4e7e-a3cc-eb86d30a4303/wroteArticles",
    "to": "weaviate://localhost/Article/6bb06a43-e7f0-393e-9ecf-3c0f4e129064"
  }, {
    "from": "weaviate://localhost/Author/36ddd591-2dee-4e7e-a3cc-eb86d30a4303/wroteArticles",
    "to": "weaviate://localhost/Article/b72912b9-e5d7-304e-a654-66dc63c55b32"
  }, {
    "from": "weaviate://localhost/Author/36ddd591-2dee-4e7e-a3cc-eb86d30a4304/wroteArticles",
    "to": "weaviate://localhost/Article/b72912b9-e5d7-304e-a654-66dc63c55b32"
  }]' \
http://localhost:8080/v1/batch/references