REST - /v1/objects

List data objects

Do you want to list all objects from Weaviate?

Use the after operator.

List data objects in reverse order of creation. The data will be returned as an array of objects.

After a class object count?

A: This Aggregate query will output a total object count in a class.

import weaviate

client = weaviate.Client("https://some-endpoint.weaviate.network")

client.query.aggregate(<ClassName>).with_meta_count().do()

import weaviate from 'weaviate-ts-client';

const client = weaviate.client({
  scheme: 'https',
  host: 'some-endpoint.weaviate.network',
});

const response = await client.graphql
  .aggregate()
  .withClassName(<ClassName>)
  .withFields('meta { count }')
  .do();
console.log(JSON.stringify(response, null, 2));

package main

import (
  "context"
  "fmt"

  "github.com/weaviate/weaviate-go-client/v4/weaviate"
  "github.com/weaviate/weaviate-go-client/v4/weaviate/graphql"
)

func main() {
  cfg := weaviate.Config{
    Host:   "some-endpoint.weaviate.network",
    Scheme: "https",
  }
  client := weaviate.New(cfg)

  meta := graphql.Field{
    Name: "meta", Fields: []graphql.Field{
      {Name: "count"},
    },
  }

  result, err := client.GraphQL().Aggregate().
    WithClassName("<ClassName>").
    WithFields(meta).
    Do(context.Background())
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}

package io.weaviate;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.graphql.model.GraphQLResponse;
import io.weaviate.client.v1.graphql.query.fields.Field;

public class App {
  public static void main(String[] args) {
    Config config = new Config("https", "some-endpoint.weaviate.network");
    WeaviateClient client = new WeaviateClient(config);
    Field meta = Field.builder()
      .name("meta")
      .fields(new Field[]{
        Field.builder().name("count").build()
      }).build();
    Result<GraphQLResponse> result = client.graphQL().aggregate()
      .withClassName(<ClassName>)
      .withFields(meta)
      .run();
    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

echo '{
  "query": "{
    Aggregate {
      <ClassName> {
        meta {
          count
        }
      }
    }
  }"
}' | curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -d @- \
  https://some-endpoint.weaviate.network/v1/graphql

{ Aggregate { <ClassName> { meta { count } } } }

Method and URL

Without any restrictions (across classes, default limit = 25):

GET /v1/objects

With optional query params:

GET /v1/objects?class={ClassName}&limit={limit}&include={include}

Parameters

All parameters below are optional URL query parameters

Name	Type	Description
`class`	string	List objects by class using the class name.
`limit`	integer	The maximum number of data objects to return. Default 25.
`offset`	integer	The offset of objects returned (the starting index of the returned objects). Cannot be used with `after`. Should be used in conjunction with `limit`.
`after`	string	ID of the object after which (i.e. non-inclusive ID) objects are to be listed. Must be used with `class` Cannot be used with `offset` or `sort`. Should be used in conjunction with `limit`.
`include`	string	Include additional information, such as classification info. Allowed values include: `classification`, `vector`, `featureProjection` and other module-specific additional properties.
`sort`	string	Name of the property to sort by - i.e. `sort=city` You can also provide multiple names – i.e. `sort=country,city`
`order`	string	Order in which to sort by. Possible values: `asc` (default) and `desc`. Should be used in conjunction with `sort`.

Paging: `offset`

tip

You can use limit and offset for paging results.

The offset parameter is a flexible way to page results as it allows use with parameters such as sort. It is limited by the value of QUERY_MAXIMUM_RESULTS which sets the maximum total number of objects that can be listed using this parameter.

Get the first 10 objects:

GET /v1/objects?class=MyClass&limit=10

Get the second batch of 10 objects:

GET /v1/objects?class=MyClass&limit=10&offset=10

Get the next batch of 10 objects:

GET /v1/objects?class=MyClass&limit=10&offset=20

Exhaustive listing using a cursor: `after`

tip

Available from version v1.18.0.
You can use class, limit and after for listing an entire object set from a class.
The after operator is based on the order of ids. It can therefore only be applied to list queries without sorting.

You can use the after operator to retrieve all objects from a Weaviate instance . The after operator ("Cursor API") retrieves objects of a class based on the order of ids. You can pass the id of the last retrieved object as a cursor to start the next page.

It is not possible to use the after operator without specifying a class.

For a null value similar to offset=0, set after= or after (i.e. with an empty string) in the request.

Examples

Get the first 10 objects of MyClass:

GET /v1/objects?class=MyClass&limit=10

If the last object in the retrieved set above was b1645a32-0c22-5814-8f35-58f142eadf7e, you can retrieve the next 10 objects of MyClass after it as below:

GET /v1/objects?class=MyClass&limit=10&after=b1645a32-0c22-5814-8f35-58f142eadf7e

Example sorting

tip

You can use sort and order to sort your results.

Ascending sort by author_name:

GET /v1/objects?class=Book&sort=author_name

Descending sort by author_name:

GET /v1/objects?class=Book&sort=author_name&order=desc

Sort by by author_name, and then title.

GET /v1/objects?class=Book&sort=author_name,title

Sort by author_name, and then title with order:

GET /v1/objects?class=Book&sort=author_name,title&order=desc,asc

Response fields

The response of a GET query of a data object will give you information about all objects (or a single object). Next to general information about the data objects, like schema information and property values, meta information will be shown depending on the include fields or additional properties of your request.

Response format

{
  "objects": [/* list of objects, see below */],
  "deprecations": null,
}

Object fields

Field name	Data type	Required `include` or `additional` field	Description
`class`	string	none	The class name.
`creationTimeUnix`	unix timestamp	none	The time stamp of creation of the data object.
`id`	uuid	none	The uuid of the data object.
`lastUpdateTimeUnix`	unix timestamp	none	The time stamp when the data object was last updated.
`properties` > `{propertyName}`	dataType	none	The name and value of an individual property.
`properties` > `{crefPropertyName}` > `classification` > `closestLosingDistance`	float	`classification`	The lowest distance of a neighbor in the losing group. Optional. If `k` equals the size of the winning group, there is no losing group.
`properties` > `{crefPropertyName}` > `classification` > `closestOverallDistance`	float	`classification`	The lowest distance of any neighbor, regardless of whether they were in the winning or losing.
`properties` > `{crefPropertyName}` > `classification` > `closestWinningDistance`	float	`classification`	Closest distance of a neighbor from the winning group.
`properties` > `{crefPropertyName}` > `classification` > `losingCount`	integer	`classification`	Size of the losing group, can be 0 if the winning group size equals `k`.
`properties` > `{crefPropertyName}` > `classification` > `meanLosingDistance`	float	`classification`	The mean distance of the losing group. It is a normalized distance (between 0 and 1), where 0 means equal and 1 would mean a perfect opposite.
`properties` > `{crefPropertyName}` > `classification` > `meanWinningDistance`	float	`classification`	The mean distance of the winning group. It is a normalized distance (between 0 and 1), where 0 means equal and 1 would mean a perfect opposite.
`properties` > `{crefPropertyName}` > `classification` > `overallCount`	integer	`classification`	Overall neighbors checked as part of the classification. In most cases this will equal `k`, but could be lower than `k` - for example if not enough data was present.
`properties` > `{crefPropertyName}` > `classification` > `winningCount`	integer	`classification`	Size of the winning group, a number between 1 and `k`.
`vector`	list of floats	`vector`	The vector embedding computed for the object.
`classification` > `basedOn`	string	`classification`	The property name where the classification was based on.
`classification` > `classifiedFields`	string	`classification`	The classified property.
`classification` > `completed`	timestamp	`classification`	The time of classification completion.
`classification` > `id`	uuid	`classification`	The classification id.
`classification` > `scope`	list of strings	`classification`	The initial fields to classify.
`featureProjection` > `vector`	list of floats	`featureProjection`	The 2D or 3D vector coordinates of the feature projection.

Status codes and error cases

Cause	Description	Result
No objects present	No `?class` is provided. There are no objects present in the entire Weaviate instance.	`200 OK` - No error
Valid class, no objects present	`?class` is provided, class exists. There are no objects present for this class.	`200 OK` - No error
Invalid class	`?class` is provided, class does not exist.	`404 Not Found`
Validation	Otherwise invalid user request.	`422 Unprocessable Entity`
Authorization	Not allowed to view resource.	`403 Forbidden`
Server-Side error	Correct user input, but request failed for another reason.	`500 Internal Server Error` - contains detailed error message

Example request

Python
JavaScript/TypeScript
Go
Java
Curl

import weaviate

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

all_objects = client.data_object.get(class_name="MyClass")
print(all_objects)

import weaviate from 'weaviate-ts-client';

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

const response = await client.data
  .getter()
  .withClassName('MyClass')
  .withLimit(2)
  .do();
console.log(JSON.stringify(response, null, 2));

package main

import (
    "context"
    "fmt"

    "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").
        WithAdditional("classification").
        Do(context.Background())

    if err != nil {
        panic(err)
    }
    fmt.Printf("%v", data)
}

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;

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")
      .withAdditional("classification")
      .run();

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

curl http://localhost:8080/v1/objects?limit=2&include=classification&class=MyClass

Create a data object

Create a new data object. The provided meta-data and schema values are validated.

`objects` vs `batch`

tip

The objects endpoint is meant for individual object creations.

If you plan on importing a large number of objects, it's much more efficient to use the /v1/batch endpoint. Otherwise, sending multiple single requests sequentially would incur a large performance penalty:

Each sequential request would be handled by a single thread server-side while most of the server resources are idle. In addition, if you only send the second request once the first has been completed, you will wait for a lot of network overhead.
It's much more efficient to parallelize imports. This will minimize the connection overhead and use multiple threads server-side for indexing.
You do not have to do the parallelization yourself, you can use the /v1/batch endpoint for this. Even if you are sending batches from a single client thread, the objects within a batch will be handled by multiple server threads.
Import speeds, especially for large datasets, will drastically improve when using the batching endpoint.

Idempotence of POST requests in objects and batch

The idempotence behavior differs between these two endpoints. POST /batch/objects is idempotent, and will overwrite any existing object given an id. POST /objects will fail if an id is provided which already exists in the class.

To update an existing object with the objects endpoint, use the PUT or PATCH method.

Method and URL

POST /v1/objects[?consistency_level=ONE|QUORUM|ALL]

note

The class name is not specified in the URL, as it is part of the request body.

Parameters

The URL supports an optional consistency level query parameter:

Name	Location	Type	Description
`consistency_level`	query param	string	Optional consistency level: `ONE`, `QUORUM` (default) or `ALL`.

The request body for a new object has the following fields:

Name	Type	Required	Description
`class`	string	yes	The class name as defined in the schema
`properties`	array	yes	An object with the property values of the new data object
`properties` > `{propertyName}`	dataType	yes	The property and its value according to the set dataType
`id`	v4 UUID	no	Optional id for the object
`vector`	`[float]`	no	Optional custom vector
`tenant`	`string`	no	Optional tenant name. Multi-tenancy must be enabled first.

Example request

Python
JavaScript/TypeScript
Go
Java
Curl

import weaviate

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

data_obj = {
    "name": "Jodi Kantor",
    "writesFor": [{
        "beacon": "weaviate://localhost/Article/f81bfe5e-16ba-4615-a516-46c2ae2e5a80"
    }]
}

data_uuid = client.data_object.create(
  data_obj,
  "Author",
  uuid="36ddd591-2dee-4e7e-a3cc-eb86d30a4303",  # optional; if not provided, one will be generated
  consistency_level=weaviate.data.replication.ConsistencyLevel.ALL,  # default QUORUM
)

import weaviate from 'weaviate-ts-client';

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

const response = await client.data
  .creator()
  .withClassName('Author')
  .withId('36ddd591-2dee-4e7e-a3cc-eb86d30a4303')
  .withProperties({
    'name': 'Jodi Kantor',
    'writesFor': [{
      'beacon': 'weaviate://localhost/f81bfe5e-16ba-4615-a516-46c2ae2e5a80',
    }],
  })
  .withConsistencyLevel('ALL')  // default QUORUM
  .do();
console.log(JSON.stringify(response, null, 2));

package main

import (
  "context"
  "fmt"

  "github.com/weaviate/weaviate-go-client/v4/weaviate"
  "github.com/weaviate/weaviate-go-client/v4/weaviate/data/replication"  // for consistency levels
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client, err := weaviate.NewClient(cfg)
  if err != nil {
    panic(err)
  }

  dataSchema := map[string]interface{}{
    "name": "Jodi Kantor",
    "writesFor": map[string]string{
      "beacon": "weaviate://localhost/f81bfe5e-16ba-4615-a516-46c2ae2e5a80",
    },
  }

  created, err := client.Data().Creator().
    WithClassName("Author").
    WithID("36ddd591-2dee-4e7e-a3cc-eb86d30a4303").
    WithProperties(dataSchema).
    WithConsistencyLevel(replication.ConsistencyLevel.ALL).  // default QUORUM
    Do(context.Background())

  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", created)
}

package io.weaviate;

import java.util.HashMap;
import java.util.Map;
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);

    Map<String, Object> dataSchema = new HashMap<>();
    dataSchema.put("name", "Jodi Kantor");
    dataSchema.put("writesFor", new HashMap() { {
      put("beacon", "weaviate://localhost/f81bfe5e-16ba-4615-a516-46c2ae2e5a80");
    } });

    Result<WeaviateObject> result = client.data().creator()
      .withClassName("Author")
      .withID("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")
      .withProperties(dataSchema)
      .withConsistencyLevel(ConsistencyLevel.ALL)  // default QUORUM
      .run();

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

curl \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
      "class": "Author",
      "properties": {
          "name": "Jodi Kantor",
          "writesFor": [{
            "beacon": "weaviate://localhost/f81bfe5e-16ba-4615-a516-46c2ae2e5a80"
          }]
      },
      "id": "36ddd591-2dee-4e7e-a3cc-eb86d30a4303"
    }' \
    http://localhost:8080/v1/objects?consistency_level=ALL

With geoCoordinates

If you want to supply a geoCoordinates property, you need to specify the latitude and longitude as floating point decimal degrees:

Python
JavaScript/TypeScript
Go
Java
Curl

import weaviate

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

data_obj = {
  "name": "Elsevier",
  "headquartersGeoLocation": {
    "latitude": 52.3932696,
    "longitude": 4.8374263
  }
}

data_uuid = client.data_object.create(
  data_obj,
  "Publication",
  uuid="df48b9f6-ba48-470c-bf6a-57657cb07390", # optional, if not provided, one is going to be generated
)

import weaviate from 'weaviate-ts-client';

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

const response = await client.data
  .creator()
  .withClassName('Publication')
  .withId('df48b9f6-ba48-470c-bf6a-57657cb07390')
  .withProperties({
    'name': 'Elsevier',
    'headquartersGeoLocation': {
      'latitude': 52.3932696,
      'longitude': 4.8374263,
    },
  })
  .do();
console.log(JSON.stringify(response, null, 2));

package main

import (
  "context"
  "fmt"

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

  dataSchema := map[string]interface{}{
    "name": "Elsevier",
    "headquartersGeoLocation": map[string]float32{
      "latitude":  52.3932696,
      "longitude": 4.8374263,
    },
  }

  created, err := client.Data().Creator().
    WithClassName("Publication").
    WithID("df48b9f6-ba48-470c-bf6a-57657cb07390").
    WithProperties(dataSchema).
    Do(context.Background())

  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", created)
}

package io.weaviate;

import java.util.HashMap;
import java.util.Map;
import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.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);

    Map<String, Object> dataSchema = new HashMap<>();
    dataSchema.put("name", "Elsevier");
    dataSchema.put("headquartersGeoLocation", new HashMap() { {
      put("latitude", 52.3932696f);
      put("longitude", 4.8374263f);
    } });

    Result<WeaviateObject> result = client.data().creator()
      .withClassName("Publication")
      .withID("df48b9f6-ba48-470c-bf6a-57657cb07390")
      .withProperties(dataSchema)
      .run();

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

curl \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
      "class": "Publication",
      "id": "df48b9f6-ba48-470c-bf6a-57657cb07390",
      "properties": {
          "name": "Elsevier",
          "headquartersGeoLocation": {
            "latitude": 52.3932696,
            "longitude": 4.8374263
          }
      }
  }' \
    http://localhost:8080/v1/objects

With a custom vector

When creating a data object, you can configure Weaviate to generate a vector with a vectorizer module, or you can provide the vector yourself. We sometimes refer to this as a "custom" vector.

You can provide a custom vector during object creation either when:

you are not using a vectorizer for that class, or
you are using a vectorizer, but you wish to bypass it during the object creation stage.

You can create a data object with a custom vector as follows:

Set the "vectorizer" in the relevant class in the data schema.
- If you are not using a vectorizer at all, configure the class accordingly. To do this, you can:
  - set the default vectorizer module to "none" (DEFAULT_VECTORIZER_MODULE="none"), or
  - set the "vectorizer" for the class to "none" ("vectorizer": "none") (note: the class vectorizer setting will override the DEFAULT_VECTORIZER_MODULE parameter).
- If you wish to bypass the vectorizer for object creation:
  - set the vectorizer to the same vectorizer with identical settings used to generate the custom vector
    Note: There is NO validation of this vector besides checking the vector length.
Then, attach the vector in a special "vector" field during object creation. For example, if adding a single object, you can:

Python
JavaScript/TypeScript
Go
Java
Curl

import weaviate

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

data_obj = {
    "foo": "bar"
}

data_uuid = client.data_object.create(
  data_obj,
  "YourClass",
  uuid="36ddd591-2dee-4e7e-a3cc-eb86d30a0923", # optional, if not provided, one is going to be generated
  vector = [0.3, 0.2, 0.1, .... 0.9], # supported types are `list`, `numpy.ndarray`, `torch.Tensor` and `tf.Tensor`.
)

import weaviate from 'weaviate-ts-client';

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

const vector = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9];

const response = await client.data
  .creator()
  .withClassName('Publication')
  .withId('df48b9f6-ba48-470c-bf6a-57657cb07390')
  .withProperties({
    'name': 'Elsevier',
    'headquartersGeoLocation': {
      'latitude': 52.3932696,
      'longitude': 4.8374263,
    },
  })
  .withVector(vector)
  .do();
console.log(JSON.stringify(response, null, 2));

package main

import (
  "context"
  "fmt"

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

  dataSchema := map[string]interface{}{
    "foo": "bar",
  }

  vector := []float32{0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9}

  created, err := client.Data().Creator().
    WithClassName("YourClass").
    WithID("36ddd591-2dee-4e7e-a3cc-eb86d30a0923").
    WithProperties(dataSchema).
    WithVector(vector).
    Do(context.Background())

  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", created)
}

package io.weaviate;

import java.util.HashMap;
import java.util.Map;
import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.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);

    Map<String, Object> dataSchema = new HashMap<>();
    dataSchema.put("name", "Jodi Kantor");
    dataSchema.put("writesFor", new HashMap() { {
      put("beacon", "weaviate://localhost/f81bfe5e-16ba-4615-a516-46c2ae2e5a80");
    } });

    Float[] vector = new Float[]{0.1f, 0.2f, 0.3f, 0.4f, 0.5f, 0.6f, 0.7f, 0.8f, 0.9f};

    Result<WeaviateObject> result = client.data().creator()
      .withClassName("Author")
      .withID("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")
      .withVector(vector)
      .withProperties(dataSchema)
      .run();

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

curl \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
      "class": "YourClass",
      "vector": [0.3, -0.012, 0.071, ..., -0.09],
      "properties": {
          "foo": "bar"
      }
  }' \
    http://localhost:8080/v1/objects

note

You can set custom vectors for batch imports as well as single object creation.

Get a data object

Collect an individual data object.

Method and URL

Available since v1.14 and the preferred way:

GET /v1/objects/{ClassName}/{id}[?consistency_level=ONE|QUORUM|ALL&tenant={tenant}]

Getting a data object without a class name is deprecated

The below syntax is only available for backward compatibility and deprecated:

GET /v1/objects/{id}

Class Name in Object CRUD Operations

Prior to Weaviate v1.14 it was possible to manipulate objects using only their ID without specifying the class name. This way is still supported for backward compatibility, but is considered deprecated now. Avoid using the deprecated endpoints, as they will be removed with Weaviate v2.0.0.

The reason for the deprecation is that classes generally act like namespaces, therefore duplicate IDs are possible.

Additionally, where multi-tenancy (available from v1.20.0) is enabled, the tenant name is required.

It is thus recommended to always include the class name when manipulating objects.

URL parameters

Name	Location	Type	Description
`{ClassName}`	path	string	The name of the class that the object belongs to.
`{id}`	query param	uuid	The uuid of the data object to retrieve.
`include`	query param	string	Include additional information, such as classification info. Allowed values include: `classification`, `vector`.
`consistency_level`	query param	string	Optional consistency level: `ONE`, `QUORUM` (default) or `ALL`.
`tenant`	query param	string	Optional tenant key. Multi-tenancy must be enabled first.

Example request

The response fields are explained in the corresponding section above.

Python
JavaScript/TypeScript
Go
Java
Curl

import weaviate

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

data_object = client.data_object.get_by_id(
  "36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
  class_name="MyClass",
  consistency_level=weaviate.data.replication.ConsistencyLevel.ONE,  # default QUORUM
)

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

import weaviate from 'weaviate-ts-client';

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

const response = await client.data
  .getterById()
  .withClassName('MyClass')
  .withId('36ddd591-2dee-4e7e-a3cc-eb86d30a4303')
  .withConsistencyLevel('ONE')  // default QUORUM
  .do();
console.log(JSON.stringify(response, 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/v4/weaviate"
    "github.com/weaviate/weaviate-go-client/v4/weaviate/data/replication"  // for consistency levels
)

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.

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 http://localhost:8080/v1/objects/MyClass/36ddd591-2dee-4e7e-a3cc-eb86d30a4303?consistency_level=ONE

Check if a data object exists

The same endpoint above can be used with the HEAD HTTP method to check if a data object exists without retrieving it. Internally it skips reading the object from disk (other than checking if it is present), thus not using resources on marshalling, parsing, etc. Additionally, the resulting HTTP request has no body; the existence of an object is indicated solely by the status code (204 when the object exists, 404 when it doesn't, 422 on invalid ID).

Method and URL

Available since v1.14 and the preferred way:

HEAD /v1/objects/{ClassName}/{id}[?consistency_level=ONE|QUORUM|ALL]

Checking if a data object exists without a class name is deprecated

The below syntax is only available for backward compatibility and deprecated:

HEAD /v1/objects/{id}

Class Name in Object CRUD Operations

The reason for the deprecation is that classes generally act like namespaces, therefore duplicate IDs are possible.

Additionally, where multi-tenancy (available from v1.20.0) is enabled, the tenant name is required.

It is thus recommended to always include the class name when manipulating objects.

URL parameters

Name	Location	Type	Description
`{ClassName}`	path	string	The name of the class that the object belongs to
`{id}`	path	uuid	The uuid of the data object to retrieve
`consistency_level`	query param	string	Optional consistency level: `ONE`, `QUORUM` (default) or `ALL`.
`tenant`	query param	string	Optional tenant name. Multi-tenancy must be enabled first.

Example request

Python
JavaScript/TypeScript
Go
Java
Curl

import weaviate

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

exists = client.data_object.exists(
  "36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
  class_name="MyClass",
  consistency_level=weaviate.data.replication.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(exists)

import weaviate from 'weaviate-ts-client';

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

const response = await client.data
  .checker()
  .withClassName('MyClass')
  .withId('df48b9f6-ba48-470c-bf6a-57657cb07390')
  // .withConsistencyLevel('QUORUM')  // may not work yet - https://github.com/weaviate/typescript-client/issues/79
  .do();
console.log(response);

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

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client, err := weaviate.NewClient(cfg)
  if err != nil {
    panic(err)
  }

  exists, err := client.Data().Checker().
    WithClassName("MyClass").
    WithID("36ddd591-2dee-4e7e-a3cc-eb86d30a0923").
    WithConsistencyLevel(replication.ConsistencyLevel.ONE).  // default QUORUM
    Do(context.Background())

  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", exists)
}

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

package io.weaviate;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
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<Boolean> result = client.data().checker()
      .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, or
// * ConsistencyLevel.ONE.
//
// It determines how many replicas must acknowledge a request
// before it is considered successful.

curl -I http://localhost:8080/v1/objects/MyClass/f3e20a86-0b44-4558-a336-bd137d866387?consistency_level=QUORUM

Update a data object

Update an individual data object based on its uuid.

Method and URL

In the RESTful API, both PUT and PATCH methods are accepted. PUT replaces all property values of the data object, while PATCH only overwrites the given properties.

Available since v1.14 and the preferred way:

PUT /v1/objects/{ClassName}/{id}[?consistency_level=ONE|QUORUM|ALL]
PATCH /v1/objects/{ClassName}/{id}[?consistency_level=ONE|QUORUM|ALL]

Updating a data object without a class name are deprecated

The below are only available for backward compatibility and deprecated:

PUT /v1/objects/{id}
PATCH /v1/objects/{id}

Class Name in Object CRUD Operations

The reason for the deprecation is that classes generally act like namespaces, therefore duplicate IDs are possible.

Additionally, where multi-tenancy (available from v1.20.0) is enabled, the tenant name is required.

It is thus recommended to always include the class name when manipulating objects.

Recalculating vectors on update

If the class is configured with a vectorizer, Weaviate will only compute a new vector for an updated object if the update changes the underlying text to be vectorized.

Parameters

The URL has two required path parameters and supports an optional query parameter for the consistency level:

Name	Location	Type	Description
`{ClassName}`	path	string	The name of the class that the object belongs to
`{id}`	path	uuid	The uuid of the data object to update
`consistency_level`	query param	string	Optional consistency level: `ONE`, `QUORUM` (default) or `ALL`.

The request body for replacing (some) properties of an object has the following fields:

Name	Type	Required	Description
`class`	string	yes	The class name as defined in the schema
`id`	string	?	Required for `PUT` to be the same id as the one passed in the URL
`properties`	array	yes	An object with the property values of the new data object
`properties` > `{propertyName}`	dataType	yes	The property and its value according to the set dataType
`vector`	`[float]`	no	Optional custom vector
`tenant`	`string`	no	Optional tenant name. Multi-tenancy must be enabled first.

Example request

Python
JavaScript/TypeScript
Go
Java
Curl

import weaviate

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

updated_schema = {
    "name": "J. Kantor"
}

# Update only the properties in variable "updated_schema"
client.data_object.update(
    updated_schema,
    class_name="Author",
    uuid="36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
    consistency_level=weaviate.data.replication.ConsistencyLevel.ALL,  # default QUORUM
)

# Replaces the whole data object with the "updated_schema"
client.data_object.replace(
    updated_schema,
    "Author",
    "36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
    consistency_level=weaviate.data.replication.ConsistencyLevel.ALL,  # default QUORUM
)

import weaviate from 'weaviate-ts-client';

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

const className = 'Author';
const id = '36ddd591-2dee-4e7e-a3cc-eb86d30a4303';

const response = await client.data
  .getterById()
  .withClassName(className)
  .withId(id)
  .do()
  .then(res => {
    // alter the schema
    const schema = res.properties;
    schema.name = 'J. Kantor';
    return client.data
      .updater()
      .withId(id)
      .withClassName(className)
      .withProperties(schema)
      .withConsistencyLevel('ALL')  // default QUORUM
      .do();
  });
console.log(JSON.stringify(response, null, 2));

package main

import (
    "context"

    "github.com/weaviate/weaviate-go-client/v4/weaviate"
    "github.com/weaviate/weaviate-go-client/v4/weaviate/data/replication"  // for consistency levels
)

func main() {
    cfg := weaviate.Config{
        Host:   "localhost:8080",
        Scheme: "http",
    }
    client, err := weaviate.NewClient(cfg)
    if err != nil {
        panic(err)
    }

    dataSchema := map[string]interface{}{
        "name": "J. Kantor",
    }

    err := client.Data().Updater().
        WithID("36ddd591-2dee-4e7e-a3cc-eb86d30a4303").
        WithClassName("Author").
        WithProperties(dataSchema).
        WithConsistencyLevel(replication.ConsistencyLevel.ALL).  // default QUORUM
        Do(context.Background())

    if err != nil {
        panic(err)
    }
}

package io.weaviate;

import java.util.HashMap;
import java.util.Map;
import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
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);

    Map<String, Object> properties = new HashMap<>();
    properties.put("name", "J. Kantor");

    Result<Boolean> result = client.data().updater()
      .withID("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")
      .withClassName("Author")
      .withProperties(properties)
      .withConsistencyLevel(ConsistencyLevel.ALL)  // default QUORUM
      .run();

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

curl \
    -X PATCH \
    -H "Content-Type: application/json" \
    -d '{
      "class": "Author",
      "id": "36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
      "properties": {
          "name": "J. Kantor"
      }
  }' \
    http://localhost:8080/v1/objects/Author/36ddd591-2dee-4e7e-a3cc-eb86d30a4303?consistency_level=ALL

If the update was successful, no content will be returned.

Delete a data object

Delete an individual data object from Weaviate.

Method and URL

Available since v1.14 and preferred way:

DELETE /v1/objects/{ClassName}/{id}[?consistency_level=ONE|QUORUM|ALL]

Deleting a data object without a class name is deprecated

The below syntax is only available for backward compatibility and deprecated:

DELETE /v1/objects/{id}

Class Name in Object CRUD Operations

The reason for the deprecation is that classes generally act like namespaces, therefore duplicate IDs are possible.

Additionally, where multi-tenancy (available from v1.20.0) is enabled, the tenant name is required.

It is thus recommended to always include the class name when manipulating objects.

URL parameters

Name	Location	Type	Description
`{ClassName}`	path	string	The name of the class that the object belongs to
`{id}`	path	uuid	The uuid of the data object to delete
`consistency_level`	query param	string	Optional consistency level: `ONE`, `QUORUM` (default) or `ALL`.
`tenant`	query param	string	Optional tenant name. Multi-tenancy must be enabled first.

Example request

Python
JavaScript/TypeScript
Go
Java
Curl

import weaviate

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

client.data_object.delete(
  "36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
  class_name="MyClass",
  consistency_level=weaviate.data.replication.ConsistencyLevel.ALL,  # default QUORUM
)

import weaviate from 'weaviate-ts-client';

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

await client.data
  .deleter()
  .withClassName('MyClass')
  .withId('36ddd591-2dee-4e7e-a3cc-eb86d30a4303')
  .withConsistencyLevel('QUORUM')
  .do();

package main

import (
  "context"

  "github.com/weaviate/weaviate-go-client/v4/weaviate"
  "github.com/weaviate/weaviate-go-client/v4/weaviate/data/replication"  // for consistency levels
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client, err := weaviate.NewClient(cfg)
  if err != nil {
    panic(err)
  }

  err := client.Data().Deleter().
    WithClassName("MyClass").
    WithID("36ddd591-2dee-4e7e-a3cc-eb86d30a4303").
    WithConsistencyLevel(replication.ConsistencyLevel.ALL).  // default QUORUM
    Do(context.Background())

  if err != nil {
    panic(err)
  }
}

package io.weaviate;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
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<Boolean> result = client.data().deleter()
      .withID("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")
      .withClassName("MyClass")
      .withConsistencyLevel(ConsistencyLevel.ALL)  // default QUORUM
      .run();

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

curl -X DELETE http://localhost:8080/v1/objects/MyClass/36ddd591-2dee-4e7e-a3cc-eb86d30a4303?consistency_level=QUORUM

If the deletion was successful, no content will be returned.

Validate a data object

You can validate an object's schema and metadata without creating it. If the schema of the object is valid, the request should return True/true in case of the clients, and nothing with a plain RESTful request. Otherwise, an error object will be returned.

Method and URL

POST /v1/objects/validate

note

As with creating an object, the class name is not specified through the URL, as it is part of the request body.

Parameters

The request body for validating an object has the following fields:

Name	Type	Required	Description
`class`	string	yes	The class name as defined in the schema
`properties`	array	yes	An object with the property values of the new data object
`properties` > `{propertyName}`	dataType	yes	The property and its value according to the set dataType
`id`	v4 uuid	no^*	The id of the data object. ^{*An ID is required by the clients.}

Example request

Python
JavaScript/TypeScript
Go
Java
Curl

import weaviate

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

schema = {"name": "New York Times"}

valid_thing = client.data_object.validate(
  schema,
  "Publication",
  "12345678-1234-1234-1234-123456789012"
)
print(valid_thing)

import weaviate from 'weaviate-ts-client';

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

const schema = {
  name: 'New York Times',
};

const response = await client.data
  .validator()
  .withId('12345678-1234-1234-1234-123456789012')
  .withClassName('Publication')
  .withProperties(schema)
  .do();
console.log(response);

package main

import (
  "context"

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

  dataSchema := map[string]interface{}{
    "name": "New York Times",
  }

  err := client.Data().Validator().
    WithID("12345678-1234-1234-1234-123456789012").
    WithClassName("Publication").
    WithProperties(dataSchema).
    Do(context.Background())

  if err != nil {
    panic(err)
  }
}

package io.weaviate;

import java.util.HashMap;
import java.util.Map;
import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;

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

    Map<String, Object> dataSchema = new HashMap<>();
    dataSchema.put("name", "New York Times");

    Result<Boolean> result = client.data().validator()
      .withID("12345678-1234-1234-1234-123456789012")
      .withClassName("Publication")
      .withProperties(dataSchema)
      .run();

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

curl \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
        "class": "Publication",
        "id": "12345678-1234-1234-1234-123456789012",
        "properties": {
            "name": "New York Times"
        }
    }' \
    http://localhost:8080/v1/objects/validate

Cross-references

Cross-references are object properties for establishing links from the source object to another object via a beacon.

Cross-references do not affect vectors

Creating cross-references does not affect object vectors in either direction.

Add a cross-reference

POST request that adds a reference to the array of cross-references of the given property in the source object specified by its class name and id.

Method and URL

Available since v1.14 and the preferred way:

POST /v1/objects/{ClassName}/{id}/references/{propertyName}[?consistency_level=ONE|QUORUM|ALL]

Adding a cross-reference without a class name is deprecated

The below syntax is only available for backward compatibility and deprecated:

POST /v1/objects/{id}/references/{propertyName}

Class Name in Object CRUD Operations

The reason for the deprecation is that classes generally act like namespaces, therefore duplicate IDs are possible.

Additionally, where multi-tenancy (available from v1.20.0) is enabled, the tenant name is required.

It is thus recommended to always include the class name when manipulating objects.

Parameters

The URL includes three required path parameters and supports an optional query parameter for the consistency level:

Name	Location	Type	Description
`{ClassName}`	path	string	The name of the class that the object belongs to, e.g. `Article`
`{id}`	path	uuid	The uuid of the object to add the reference to
`{propertyName}`	path	string	The name of the cross-reference property, e.g. `author`
`consistency_level`	query param	string	Optional consistency level: `ONE`, `QUORUM` (default) or `ALL`.
`tenant`	query param	string	Optional tenant name. Multi-tenancy must be enabled first.

The request body is an object with the following field:

Name	Type	Required	Description
`beacon`	Weaviate Beacon	yes	The beacon URL of the reference, in the format `weaviate://localhost/<ClassName>/<id>`

caution

In the beacon format, you need to always use localhost as the host, rather than the actual hostname. localhost refers to the fact that the beacon's target is on the same Weaviate instance, as opposed to a foreign instance.

note

For backward compatibility, you can omit the class name in the beacon format and specify it as weaviate://localhost/<id>. This is, however, considered deprecated and will be removed with a future release, as duplicate IDs across classes could mean that this beacon is not uniquely identifiable.

Example request

Python
JavaScript/TypeScript
Go
Java
Curl

import weaviate
# weaviate.__version__ >= 3.7.0

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

client.data_object.reference.add(
  "36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
  "wroteArticles",
  "6bb06a43-e7f0-393e-9ecf-3c0f4e129064",
  from_class_name="SourceClass",
  to_class_name="TargetClass",
  consistency_level=weaviate.data.replication.ConsistencyLevel.ALL,  # default QUORUM
)

import weaviate from 'weaviate-ts-client';

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

const response = await client.data
  .referenceCreator()
  .withClassName('SourceClass')
  .withId('36ddd591-2dee-4e7e-a3cc-eb86d30a4303')
  .withReferenceProperty('wroteArticles')
  .withReference(
    client.data
      .referencePayloadBuilder()
      .withClassName('TargetClass')
      .withId('6bb06a43-e7f0-393e-9ecf-3c0f4e129064')
      .payload(),
  )
  .withConsistencyLevel('ALL')  // default QUORUM
  .do();
console.log(JSON.stringify(response, null, 2));

package main

import (
  "context"

  "github.com/weaviate/weaviate-go-client/v4/weaviate"
  "github.com/weaviate/weaviate-go-client/v4/weaviate/data/replication"  // for consistency levels
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client, err := weaviate.NewClient(cfg)
  if err != nil {
    panic(err)
  }

  reference := client.Data().ReferencePayloadBuilder().
    WithClassName("TargetClass").
    WithID("6bb06a43-e7f0-393e-9ecf-3c0f4e129064").Payload()

  err := client.Data().ReferenceCreator().
    WithClassName("SourceClass").
    WithID("36ddd591-2dee-4e7e-a3cc-eb86d30a4303").
    WithReferenceProperty("wroteArticles").
    WithReference(reference).
    WithConsistencyLevel(replication.ConsistencyLevel.ALL).  // default QUORUM
    Do(context.Background())

  if err != nil {
    panic(err)
  }
}

package io.weaviate;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.data.model.SingleRef;
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);

    SingleRef reference = client.data().referencePayloadBuilder()
      .withClassName("TargetClass")
      .withID("6bb06a43-e7f0-393e-9ecf-3c0f4e129064")
      .payload();

    Result<Boolean> result = client.data().referenceCreator()
      .withClassName("SourceClass")
      .withID("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")
      .withReferenceProperty("wroteArticles")
      .withReference(reference)
      .withConsistencyLevel(ConsistencyLevel.ALL)  // default QUORUM
      .run();

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

curl \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
      "beacon": "weaviate://localhost/TargetClass/6bb06a43-e7f0-393e-9ecf-3c0f4e129064"
      }' \
    http://localhost:8080/v1/objects/SourceClass/36ddd591-2dee-4e7e-a3cc-eb86d30a4303/references/wroteArticles?consistency_level=ALL

If the addition was successful, no content will be returned.

Update a cross-reference

PUT request that updates all references in a specified property of an object specified by its class name and id.

Method and URL

Available since v1.14 and the preferred way:

PUT /v1/objects/{ClassName}/{id}/references/{propertyName}[?consistency_level=ONE|QUORUM|ALL]

Updating a cross-reference without a class name is deprecated

The below syntax is only available for backward compatibility and deprecated:

PUT /v1/objects/{id}/references/{propertyName}

Class Name in Object CRUD Operations

The reason for the deprecation is that classes generally act like namespaces, therefore duplicate IDs are possible.

Additionally, where multi-tenancy (available from v1.20.0) is enabled, the tenant name is required.

It is thus recommended to always include the class name when manipulating objects.

Parameters

The URL includes three required path parameters and supports an optional query parameter for the consistency level:

Name	Location	Type	Description
`{ClassName}`	path	string	The name of the class that the object belongs to
`{id}`	path	uuid	The uuid of the object to update the reference(s) of
`{propertyName}`	path	string	The name of the cross-reference property
`consistency_level`	query param	string	Optional consistency level: `ONE`, `QUORUM` (default) or `ALL`.
`tenant`	query param	string	Optional tenant name. Multi-tenancy must be enabled first.

The PUT request body is a list of beacons:

Name	Type	Required	Description
`beacon`	Weaviate Beacon array	yes	Array of beacons in the format `weaviate://localhost/<ClassName>/<id>`

caution

note

Example request

Python
JavaScript/TypeScript
Go
Java
Curl

import weaviate

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

client.data_object.reference.update(
  "36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
  "wroteArticles",
  ["6bb06a43-e7f0-393e-9ecf-3c0f4e129064", "b72912b9-e5d7-304e-a654-66dc63c55b32"]
  from_class_name="SourceClass",
  to_class_name="TargetClass",
  consistency_level=weaviate.data.replication.ConsistencyLevel.ALL,  # default QUORUM
)

import weaviate from 'weaviate-ts-client';

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

const response = await client.data
  .referenceReplacer()
  .withClassName('SourceClass')
  .withId('36ddd591-2dee-4e7e-a3cc-eb86d30a4303')
  .withReferenceProperty('wroteArticles')
  .withReferences([
    client.data
      .referencePayloadBuilder()
      .withClassName('TargetClass')
      .withId('6bb06a43-e7f0-393e-9ecf-3c0f4e129064')
      .payload(),
    client.data
      .referencePayloadBuilder()
      .withClassName('TargetClass')
      .withId('b72912b9-e5d7-304e-a654-66dc63c55b32')
      .payload(),
  ])
  .withConsistencyLevel('ALL')  // default QUORUM
  .do();
console.log(JSON.stringify(response, null, 2));

package main

import (
  "context"

  "github.com/weaviate/weaviate-go-client/v4/weaviate"
  "github.com/weaviate/weaviate/entities/models"
  "github.com/weaviate/weaviate-go-client/v4/weaviate/data/replication"  // for consistency levels
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client, err := weaviate.NewClient(cfg)
  if err != nil {
    panic(err)
  }

  references := &models.MultipleRef{
    client.Data().ReferencePayloadBuilder().
      WithVector(vector).
      WithClassName("TargetClass").
      WithID("6bb06a43-e7f0-393e-9ecf-3c0f4e129064").
      Payload(),
    client.Data().ReferencePayloadBuilder().
      WithClassName("TargetClass").
      WithID("b72912b9-e5d7-304e-a654-66dc63c55b32").
      Payload(),
  }

  err := client.Data().ReferenceReplacer().
    WithClassName("SourceClass").
    WithID("36ddd591-2dee-4e7e-a3cc-eb86d30a4303").
    WithReferenceProperty("wroteArticles").
    WithReferences(references).
    WithConsistencyLevel(replication.ConsistencyLevel.ALL).  // default QUORUM
    Do(context.Background())

  if err != nil {
    panic(err)
  }
}

package io.weaviate;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.data.model.SingleRef;
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);

    SingleRef[] references = new SingleRef[]{
      client.data().referencePayloadBuilder()
        .withClassName("TargetClass")
        .withID("6bb06a43-e7f0-393e-9ecf-3c0f4e129064")
        .payload(),
      client.data().referencePayloadBuilder()
        .withClassName("TargetClass")
        .withID("b72912b9-e5d7-304e-a654-66dc63c55b32")
        .payload()
    };

    Result<Boolean> result = client.data().referenceReplacer()
      .withClassName("SourceClass")
      .withID("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")
      .withReferenceProperty("wroteArticles")
      .withReferences(references)
      .withConsistencyLevel(ConsistencyLevel.ALL)  // default QUORUM
      .run();

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

curl \
    -X PUT \
    -H "Content-Type: application/json" \
    -d '[{
        "beacon": "weaviate://localhost/TargetClass/6bb06a43-e7f0-393e-9ecf-3c0f4e129064"
      }, {
        "beacon": "weaviate://localhost/TargetClass/c707d9bc-840f-3997-a09a-da6dba7d0e87"
      }]' \
    http://localhost:8080/v1/objects/SourceClass/36ddd591-2dee-4e7e-a3cc-eb86d30a4303/references/wroteArticles?consistency_level=ALL

If the update was successful, no content will be returned.

Delete a cross-reference

Delete the single reference that is given in the body from the list of references that the specified property of a given object has, if it exists in the list. Returns 204 No Content either way.

Method and URL

Available since v1.14 and the preferred way:

DELETE /v1/objects/{ClassName}/{id}/references/{propertyName}[?consistency_level=ONE|QUORUM|ALL]

Deleting a cross-reference without a class name is deprecated

The below syntax is only available for backward compatibility and deprecated:

DELETE /v1/objects/{id}/references/{propertyName}

Class Name in Object CRUD Operations

The reason for the deprecation is that classes generally act like namespaces, therefore duplicate IDs are possible.

Additionally, where multi-tenancy (available from v1.20.0) is enabled, the tenant name is required.

It is thus recommended to always include the class name when manipulating objects.

Parameters

The URL includes two required path parameters and supports an optional query parameter for the consistency level:

Name	Location	Type	Description
`{id}`	path	uuid	The uuid of the object to delete the reference from
`{propertyName}`	path	string	The name of the cross-reference property
`consistency_level`	query param	string	Optional consistency level: `ONE`, `QUORUM` (default) or `ALL`.
`tenant`	query param	string	Optional tenant name. Multi-tenancy must be enabled first.

The request body is a beacon object:

Name	Type	Required	Description
`beacon`	Weaviate Beacon	yes	The beacon URL of the reference, formatted as `weaviate://localhost/<ClassName>/<id>`

caution

note

For backward compatibility, beacons generally support an older, deprecated format without the class name, as well. This means you might find beacons with the old, deprecated format, as well as beacons with the new format in the same Weaviate instance. When deleting a reference, the beacon specified has to match the beacon to be deleted exactly. In other words, if a beacon is present using the old format (without class id) you also need to specify it the same way.

Example request

Python
JavaScript/TypeScript
Go
Java
Curl

import weaviate

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

client.data_object.reference.delete(
  "36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
  "wroteArticles",
  "6bb06a43-e7f0-393e-9ecf-3c0f4e129064"
  from_class_name="SourceClass",
  to_class_name="TargetClass",
  consistency_level=weaviate.data.replication.ConsistencyLevel.ALL,  # default QUORUM
)

import weaviate from 'weaviate-ts-client';

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

const response = await client.data
  .referenceDeleter()
  .withClassName('SourceClass')
  .withId('36ddd591-2dee-4e7e-a3cc-eb86d30a4303')
  .withReferenceProperty('wroteArticles')
  .withReference(
    client.data
      .referencePayloadBuilder()
      .withClassName('TargetClass')
      .withId('6bb06a43-e7f0-393e-9ecf-3c0f4e129064')
      .payload(),
  )
  .withConsistencyLevel('ALL')  // default QUORUM
  .do();
console.log(JSON.stringify(response, null, 2));

package main

import (
    "context"

    "github.com/weaviate/weaviate-go-client/v4/weaviate"
    "github.com/weaviate/weaviate-go-client/v4/weaviate/data/replication"  // for consistency levels
)

func main() {
    cfg := weaviate.Config{
        Host:   "localhost:8080",
        Scheme: "http",
    }
    client, err := weaviate.NewClient(cfg)
    if err != nil {
        panic(err)
    }

    reference := client.Data().ReferencePayloadBuilder().
      WithClassName("TargetClass").
      WithID("6bb06a43-e7f0-393e-9ecf-3c0f4e129064").Payload()

    err := client.Data().ReferenceDeleter().
      WithClassName("SourceClass").
      WithID("36ddd591-2dee-4e7e-a3cc-eb86d30a4303").
      WithReferenceProperty("wroteArticles").
      WithReference(reference).
      WithConsistencyLevel(replication.ConsistencyLevel.ALL).  // default QUORUM
      Do(context.Background())

    if err != nil {
        panic(err)
    }
}

package io.weaviate;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.data.model.SingleRef;
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);

    SingleRef reference = client.data().referencePayloadBuilder()
      .withClassName("TargetClass")
      .withID("6bb06a43-e7f0-393e-9ecf-3c0f4e129064")
      .payload();

    Result<Boolean> result = client.data().referenceDeleter()
      .withClassName("SourceClass")
      .withID("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")
      .withReferenceProperty("wroteArticles")
      .withReference(reference)
      .withConsistencyLevel(ConsistencyLevel.ALL)  // default QUORUM
      .run();

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

curl \
    -X DELETE \
    -H "Content-Type: application/json" \
    -d '{
        "beacon": "weaviate://localhost/TargetClass/6bb06a43-e7f0-393e-9ecf-3c0f4e129064"
    }' \
    http://localhost:8080/v1/objects/SourceClass/36ddd591-2dee-4e7e-a3cc-eb86d30a4303/references/wroteArticles?consistency_level=ALL

If the addition was successful, no content will be returned.

Multi-tenancy

When using multi-tenancy, cross-references can only be made:

From a multi-tenancy object to a non-multi-tenancy object.
From a multi-tenancy object to a multi-tenancy object, as long as they belong to the same tenant.

More Resources

For additional information, try these sources.

List data objects​

Method and URL​

Parameters​

Paging: offset​

Exhaustive listing using a cursor: after​

Examples​

Example sorting​

Response fields​

Response format​

Object fields​

Status codes and error cases​

Example request​

Create a data object​

objects vs batch​

Method and URL​

Parameters​

Example request​

With geoCoordinates​

With a custom vector​

Get a data object​

Method and URL​

URL parameters​

Example request​

Check if a data object exists​

Method and URL​

URL parameters​

Example request​

Update a data object​

Method and URL​

Parameters​

Example request​

Delete a data object​

Method and URL​

URL parameters​

Example request​

Validate a data object​

Method and URL​

Parameters​

Example request​

Cross-references​

Add a cross-reference​

Method and URL​

Parameters​

Example request​

Update a cross-reference​

Method and URL​

Parameters​

Example request​

Delete a cross-reference​

Method and URL​

Parameters​

Example request​

Multi-tenancy​

More Resources​

List data objects

Method and URL

Parameters

Paging: `offset`

Exhaustive listing using a cursor: `after`

Examples

Example sorting

Response fields

Response format

Object fields

Status codes and error cases

Example request

Create a data object

`objects` vs `batch`

Method and URL

Parameters

Example request

With geoCoordinates

With a custom vector

Get a data object

Method and URL

URL parameters

Example request

Check if a data object exists

Method and URL

URL parameters

Example request

Update a data object

Method and URL

Parameters

Example request

Delete a data object

Method and URL

URL parameters

Example request

Validate a data object

Method and URL

Parameters

Example request

Cross-references

Add a cross-reference

Method and URL

Parameters

Example request

Update a cross-reference

Method and URL

Parameters

Example request

Delete a cross-reference

Method and URL

Parameters

Example request

Multi-tenancy

More Resources