REST - /v1/objects
List data objectsโ
Use the after
parameter.
List data objects in reverse order of creation. The data will be returned as an array of objects.
A: This Aggregate
query will output a total object count in a class.
- Python
- JavaScript
- Go
- Java
- Curl
- GraphQL
import weaviate
client = weaviate.Client("https://some-endpoint.weaviate.network")
client.query.aggregate(<ClassName>).with_meta_count().do()
const weaviate = require("weaviate-client");
const client = weaviate.client({
scheme: 'https',
host: 'some-endpoint.weaviate.network',
});
client.graphql
.aggregate()
.withClassName(<ClassName>)
.withFields('meta { count }')
.do()
.then(res => {
console.log(JSON.stringify(res, null, 2))
})
.catch(err => {
console.error(JSON.stringify(err, 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
}
}
}
}"
}' | tr -d "\n" | 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โ
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
โ
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
โ
- Available from version
v1.18.0
. - You can use
class
,limit
andafter
for listing an entire object set from a class. - The
after
parameter is based on the order of ids. It can therefore only be applied to list queries without sorting.
You can use the after
parameter to retrieve all objects from a Weaviate instance . The after
parameter ("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
parameter 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โ
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 long vector of the location of the object in the 300-dimensional space. |
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
- Go
- Java
- Curl
import weaviate
client = weaviate.Client("http://localhost:8080")
all_objects = client.data_object.get(class_name="MyClass")
print(all_objects)
const weaviate = require('weaviate-client');
const client = weaviate.client({
scheme: 'http',
host: 'localhost:8080',
});
client
.data
.getter()
.withClassName('MyClass')
.withLimit(2)
.do()
.then(res => {
console.log(res)
})
.catch(err => {
console.error(err)
});
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
โ
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.
Method and URLโ
POST /v1/objects[?consistency_level=ONE|QUORUM|ALL]
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 |
Example requestโ
- Python
- JavaScript
- 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
)
const weaviate = require('weaviate-client');
const client = weaviate.client({
scheme: 'http',
host: 'localhost:8080',
});
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()
.then(res => {
console.log(res)
})
.catch(err => {
console.error(err)
});
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
- 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
)
const weaviate = require('weaviate-client');
const client = weaviate.client({
scheme: 'http',
host: 'localhost:8080',
});
client.data
.creator()
.withClassName('Publication')
.withId('df48b9f6-ba48-470c-bf6a-57657cb07390')
.withProperties({
'name': 'Elsevier',
'headquartersGeoLocation': {
'latitude': 52.3932696,
'longitude': 4.8374263
})
.do()
.then(res => {
console.log(res)
})
.catch(err => {
console.error(err)
});
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 classvectorizer
setting will override theDEFAULT_VECTORIZER_MODULE
parameter).
- set the default vectorizer module to
- 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.
- set the vectorizer to the same vectorizer with identical settings used to generate the custom vector
- If you are not using a vectorizer at all, configure the class accordingly. To do this, you can:
- Then, attach the vector in a special
"vector"
field during object creation. For example, if adding a single object, you can:
- Python
- JavaScript
- 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`.
)
const weaviate = require('weaviate-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];
client.data
.creator()
.withClassName('Publication')
.withId('df48b9f6-ba48-470c-bf6a-57657cb07390')
.withProperties({
'name': 'Elsevier',
'headquartersGeoLocation': {
'latitude': 52.3932696,
'longitude': 4.8374263
})
.withVector(vector)
.do()
.then(res => {
console.log(res)
})
.catch(err => {
console.error(err)
});
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
You can set custom vectors for batch imports as well as single object creation.
See also how to search using custom vectors.
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]
Available for backward compatibility and deprecated:
GET /v1/objects/{id}
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 it is also feasible to have duplicate IDs across classes. However, when manipulating exactly one object by its ID (such as an update or delete), the ID may not be unique. 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 . |
Example requestโ
The response fields are explained in the corresponding section above.
- Python
- JavaScript
- 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)
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.
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]
Available for backward compatibility and deprecated:
HEAD /v1/objects/{id}
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 it is also feasible to have duplicate IDs across classes. However, when manipulating exactly one object by its ID (such as an update or delete), the ID may not be unique. 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 . |
Example requestโ
- Python
- JavaScript
- 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)
const weaviate = require('weaviate-client');
const client = weaviate.client({
scheme: 'http',
host: 'localhost:8080',
});
client.data
.checker()
.withClassName('MyClass')
.withId('df48b9f6-ba48-470c-bf6a-57657cb07390')
.withConsistencyLevel('QUORUM')
.do()
.then((exists) => {
console.log(exists)
})
.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.
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]
Available for backward compatibility and deprecated:
PUT /v1/objects/{id}
PATCH /v1/objects/{id}
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 it is also feasible to have duplicate IDs across classes. However, when manipulating exactly one object by its ID (such as an update or delete), the ID may not be unique. It is thus recommended to always include the class name when manipulating objects.
Where Weaviate is configured with a vectorizer, it will only obtain a new vector if an object 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 |
Example requestโ
- Python
- JavaScript
- 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
)
const weaviate = require('weaviate-client');
const client = weaviate.client({
scheme: 'http',
host: 'localhost:8080',
});
var className = 'Author';
var id = '36ddd591-2dee-4e7e-a3cc-eb86d30a4303';
client.data
.getterById()
.withClassName(className)
.withId(id)
.do()
.then(res => {
// alter the schema
const schema = res.schema;
schema.name = 'J. Kantor';
return client.data
.updater()
.withId(id)
.withClassName(thingClassName)
.withProperties(schema)
.withConsistencyLevel('ALL') // default QUORUM
.do();
})
.then(res => {
console.log(res)
})
.catch(err => {
console.error(err)
});
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]
Available for backward compatibility and deprecated:
DELETE /v1/objects/{id}
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 it is also feasible to have duplicate IDs across classes. However, when manipulating exactly one object by its ID (such as an update or delete), the ID may not be unique. 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 . |
Example requestโ
- Python
- JavaScript
- 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
)
const weaviate = require('weaviate-client');
const client = weaviate.client({
scheme: 'http',
host: 'localhost:8080',
});
client.data
.deleter()
.withClassName('MyClass')
.withId('36ddd591-2dee-4e7e-a3cc-eb86d30a4303')
.withConsistencyLevel('QUORUM')
.do()
.then(res => {
console.log(res)
})
.catch(err => {
console.error(err)
});
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
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
- Go
- Java
- Curl
import weaviate
client = weaviate.Client("http://localhost:8080")
schema = {"name": "New York Times"}
valid_thing = client.data_object.validate(
schema,
"Publication",
"f81bfe5e-16ba-4615-a516-46c2ae2e5a80"
)
print(valid_thing)
const weaviate = require('weaviate-client');
const client = weaviate.client({
scheme: 'http',
host: 'localhost:8080',
});
var schema = {'name': 'New York Times'};
client.data
.validator()
.withId('f81bfe5e-16ba-4615-a516-46c2ae2e5a80')
.withClassName('Publication')
.withProperties(schema)
.do()
.then(res => {
console.log(res)
})
.catch(err => {
console.error(err)
});
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("f81bfe5e-16ba-4615-a516-46c2ae2e5a80").
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("f81bfe5e-16ba-4615-a516-46c2ae2e5a80")
.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": "f81bfe5e-16ba-4615-a516-46c2ae2e5a80",
"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.
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]
Available for backward compatibility and deprecated:
POST /v1/objects/{id}/references/{propertyName}
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 it is also feasible to have duplicate IDs across classes. However, when manipulating exactly one object by its ID (such as an update or delete), the ID may not be unique. 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 . |
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> |
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.
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
- 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
)
const weaviate = require('weaviate-client');
const client = weaviate.client({
scheme: 'http',
host: 'localhost:8080',
});
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()
.then(res => {
console.log(res)
})
.catch(err => {
console.error(err)
});
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]
Available for backward compatibility and deprecated:
PUT /v1/objects/{id}/references/{propertyName}
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 it is also feasible to have duplicate IDs across classes. However, when manipulating exactly one object by its ID (such as an update or delete), the ID may not be unique. 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 . |
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> |
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.
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
- 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
)
const weaviate = require('weaviate-client');
const client = weaviate.client({
scheme: 'http',
host: 'localhost:8080',
});
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()
.then(res => {
console.log(res)
})
.catch(err => {
console.error(err)
});
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]
Available for backward compatibility and deprecated:
DELETE /v1/objects/{id}/references/{propertyName}
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 it is also feasible to have duplicate IDs across classes. However, when manipulating exactly one object by its ID (such as an update or delete), the ID may not be unique. 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 . |
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> |
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.
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
- 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
)
const weaviate = require('weaviate-client');
const client = weaviate.client({
scheme: 'http',
host: 'localhost:8080',
});
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()
.then(res => {
console.log(res)
})
.catch(err => {
console.error(err)
});
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.