Table of documentation contents

/v1/objects

You can get, add, update, and delete individual data objects to and from a Weaviate via this end-point. If you want to add multiple data objects in one request, checkout the batch endpoint. To query and search through the data checkout the GraphQL section.

List all data objects

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

Method and URL

GET /v1/objects

Parameters

namelocationtypedescription
limitURLintegerThe maximum number of data objects to return, should be 25 or lower. If you want to retrieve more objects, we recommend using GraphQL.
includeURLstringInclude additional information, such as classification info. Allowed values include: classification, vector, featureProjection and other module-specific additional properties.

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.

field namedatatyperequired include or additional fielddescription
classstringnonethe class name
creationTimeUnixunix timestampnonethe time stamp of creation of the data object
iduuidnonethe uuid of the data object
lastUpdateTimeUnixunix timestampnonethe time stamp when the data object was last updated
properties > {property_name}dataTypenonethe name and value of an individual property
properties > {cref_property_name} > classification > closestLosingDistancefloatclassificationThe lowest distance of a neighbor in the losing group. Optional. If k equals the size of the winning group, there is no losing group. See for more info here.
properties > {cref_property_name} > classification > closestOverallDistancefloatclassificationThe lowest distance of any neighbor, regardless of whether they were in the winning or losing. See for more info here.
properties > {cref_property_name} > classification > closestWinningDistancefloatclassificationClosest distance of a neighbor from the winning group. See for more info here.
properties > {cref_property_name} > classification > losingCountintegerclassificationSize of the losing group, can be 0 if the winning group size equals k. See for more info here.
properties > {cref_property_name} > classification > meanLosingDistancefloatclassificationThe 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. See for more info here.
properties > {cref_property_name} > classification > meanWinningDistancefloatclassificationThe 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. See for more info here.
properties > {cref_property_name} > classification > overallCountintegerclassificationOverall 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. See for more info here.
properties > {cref_property_name} > classification > winningCountintegerclassificationSize of the winning group, a number between 1 and k. See for more info here.
vectorlist of floatsvectorthe long vector of the location of the object in the 300 dimensional space
classification > basedOnstringclassificationthe property name where the classification was based on
classification > classifiedFieldsstringclassificationthe classified property
classification > completedtimestampclassificationthe time of classification completion
classification > iduuidclassificationthe classification id
classification > scopelist of stringsclassificationthe initial fields to classify
featureProjection > vectorlist of floatsfeatureProjectionthe 2D or 3D vector coordinates of the feature projection

Example request

  import weaviate

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

all_objects = client.data_object.get()
print(all_objects)

Create a data object

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

Method and URL

POST /v1/objects

Parameters

The body of the data object for a new object takes the following fields:

nametyperequireddescription
classstringyesthe class name as defined in the schema
propertiesarrayyesan object with the property values of the new data object
properties > {property_name}dataTypeyesthe property and its value according to the set dataType
idv4 UUIDnothe given id of the data object

Example request

  import weaviate

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

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

client.data_object.create(data_obj, "Author", "36ddd591-2dee-4e7e-a3cc-eb86d30a4303")

Create an object with geoCoordinates

If you want to fill the value of a geoCoordinates property, you need to specify the latitude and longitude as decimal degrees in floats:

  import weaviate

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

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

client.data_object.create(data_obj, "Publication", "df48b9f6-ba48-470c-bf6a-57657cb07390")

Create a data object with custom vectors

When you don’t want to use a vectorizer to calculate a vector for your data object, and want to enter the vector yourself, you can this this as follows.

  1. First, make sure that the "vectorizer" is set to "none" in the right class in the data schema ("vectorizer": "none"). This is important so Weaviate knows not to do rely on any of it’s modules to do model inference.
  2. Then, attach the vector in a special "vector" field. An example of this looks like:
  import weaviate

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

data_obj = {
    "foo": "bar"
}

client.data_object.create(
  data_obj, 
  "YourClass", 
  "36ddd591-2dee-4e7e-a3cc-eb86d30a0923",
  "vector": [0.3, 0.2, 0.1, .... 0.9], # supported types are `list`, 'numpy.ndarray`, `torch.Tensor` and `tf.Tensor`. Make sure the length matches with your Weaviate settings.
)

Learn here how you can search through custom vectors.

Get a data object

Collect an individual data object.

Method and URL

GET /v1/objects/{id}

Parameters

namelocationtypedescription
{id}URLuuidThe uuid of the data object to retrieve.
includeURLstringInclude additional information, such as classification info. Allowed values include: classification, vector

Example request

See here the explanation of the response fields.

  import weaviate

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

data_object = client.data_object.get_by_id("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")
print(data_object)

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.

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

Parameters

namelocationtypedescription
{id}URLuuidThe uuid of the data object to update.

The body of the data object for a replacing (some) properties of a object takes the following fields:

nametyperequireddescription
classstringyesthe class name as defined in the schema
propertiesarrayyesan object with the property values of the new data object
properties > {property_name}dataTypeyesthe property and its value according to the set dataType

Example request

  import weaviate

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

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

# Similar to RESTful PUT request: schema will be replaced by "updated-schema"
client.data_object.update(updated_schema, "Author", "36ddd591-2dee-4e7e-a3cc-eb86d30a4303")

# Similar to RESTful PATCH request: "updated_schema" will be merged with the existing schema, replacing only the properties in "updated_schema"
client.data_object.merge(updated_schema, "Author", "36ddd591-2dee-4e7e-a3cc-eb86d30a4303")

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

Delete a data object

Delete an individual data object from Weaviate.

Method and URL

DELETE /v1/objects/{id}

Parameters

namelocationtypedescription
{id}URLuuidThe uuid of the data object to delete.

Example request

  import weaviate

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

client.data_object.delete("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")

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

Validate a data object

You can validate a data object’s schema and meta data.

Method and URL

POST /v1/objects/validate

Parameters

The body of the data object for a new data object is an object taking the following field:

nametyperequireddescription
classstringyesthe class name as defined in the schema
propertiesarrayyesan object with the property values of the new data object
properties > {property_name}dataTypeyesthe property and its value according to the set dataType
idv4 uuidno*The id of the data object. *An ID is required by the clients.

Example request

  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)

If the schema of the object is valid, this request should return True/true in case of the clients and nothing with a plain RESTful request.

Cross-references

Add a cross reference

Method and URL

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

Parameters

namelocationtypedescription
{id}URLuuidThe uuid of the data object to add the reference to.
{property_name}URLyesThe name of the cross-reference property

The body of the data object for a new data object is an object taking the following field:

nametyperequireddescription
beaconv4 UUIDyesthe beacon URL of the reference

Example request

  import weaviate

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

client.data_object.reference.add("36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
    "wroteArticles", "6bb06a43-e7f0-393e-9ecf-3c0f4e129064")

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

Update a cross reference

A PUT request updates all references of a property of a data object.

Method and URL

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

Parameters

namelocationtypedescription
{id}URLuuidThe uuid of the data object to add the reference to.
{property_name}URLyesThe name of the cross-reference property

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

nametyperequireddescription
beaconv4 UUIDyesthe beacon URL of the reference

Example request

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

If the addition 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 this property of a data object has.

Method and URL

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

Parameters

namelocationtypedescription
{id}URLuuidThe uuid of the data object to add the reference to.
{property_name}URLyesThe name of the cross-reference property

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

nametyperequireddescription
beaconv4 UUIDyesthe beacon URL of the reference

Example request

  import weaviate

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

client.data_object.reference.delete("36ddd591-2dee-4e7e-a3cc-eb86d30a4303", "wroteArticles", "6bb06a43-e7f0-393e-9ecf-3c0f4e129064")

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

Tags
  • RESTful API
  • references
  • class