weaviate.data package

Data module used to create, read, update and delete object and references.

class weaviate.data.ConsistencyLevel(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

ALL = 'ALL'
ONE = 'ONE'
QUORUM = 'QUORUM'
class weaviate.data.DataObject(connection: Connection)[source]

Bases: object

DataObject class used to manipulate object to/from Weaviate.

Attributes

referenceweaviate.data.references.Reference

A Reference object to create objects cross-references.

Initialize a DataObject class instance.

Parameters

connectionweaviate.connect.Connection

Connection object to an active and running Weaviate instance.

create(data_object: dict | str, class_name: str, uuid: str | UUID | None = None, vector: Sequence | None = None, consistency_level: ConsistencyLevel | None = None, tenant: str | None = None) str[source]

Takes a dict describing the object and adds it to Weaviate.

Parameters

data_objectdict or str

Object to be added. If type is str it should be either a URL or a file.

class_namestr

Class name associated with the object given.

uuidstr, uuid.UUID or None, optional

Object will be created under this uuid if it is provided. Otherwise, Weaviate will generate a uuid for this object, by default None.

vector: Sequence or None, optional

Embedding for the object. Can be used when:

  • a class does not have a vectorization module.

  • The given vector was generated using the _identical_ vectorization module that is configured for the

class. In this case this vector takes precedence.

Supported types are list, ‘numpy.ndarray`, torch.Tensor and tf.Tensor, by default None.

consistency_levelOptional[ConsistencyLevel], optional

Can be one of ‘ALL’, ‘ONE’, or ‘QUORUM’. Determines how many replicas must acknowledge

tenant: Optional[str], optional

The name of the tenant for which this operation is being performed.

Examples

Schema contains a class Author with only ‘name’ and ‘age’ primitive property.

>>> client.data_object.create(
...     data_object = {'name': 'Neil Gaiman', 'age': 60},
...     class_name = 'Author',
... )
'46091506-e3a0-41a4-9597-10e3064d8e2d'
>>> client.data_object.create(
...     data_object = {'name': 'Andrzej Sapkowski', 'age': 72},
...     class_name = 'Author',
...     uuid = 'e067f671-1202-42c6-848b-ff4d1eb804ab'
... )
'e067f671-1202-42c6-848b-ff4d1eb804ab'

Returns

str

Returns the UUID of the created object if successful.

Raises

TypeError

If argument is of wrong type.

ValueError

If argument contains an invalid value.

weaviate.ObjectAlreadyExistsException

If an object with the given uuid already exists within Weaviate.

weaviate.UnexpectedStatusCodeException

If creating the object in Weaviate failed for a different reason, more information is given in the exception.

requests.ConnectionError

If the network connection to Weaviate fails.

delete(uuid: str | UUID, class_name: str | None = None, consistency_level: ConsistencyLevel | None = None, tenant: str | None = None) None[source]

Delete an existing object from Weaviate.

Parameters

uuidstr or uuid.UUID

The ID of the object that should be deleted.

class_nameOptional[str], optional

The class name of the object with UUID uuid. Introduced in Weaviate version v1.14.0. STRONGLY recommended to set it with Weaviate >= 1.14.0. It will be required in future versions of Weaviate Server and Clients. Use None value ONLY for Weaviate < v1.14.0, by default None

consistency_levelOptional[ConsistencyLevel], optional

Can be one of ‘ALL’, ‘ONE’, or ‘QUORUM’. Determines how many replicas must acknowledge

tenant: str, optional

The name of the tenant for which this operation is being performed.

Examples

>>> client.data_object.get(
...     uuid="d842a0f4-ad8c-40eb-80b4-bfefc7b1b530",
...     class_name='Author', # ONLY with Weaviate >= 1.14.0
... )
{
    "additional": {},
    "class": "Author",
    "creationTimeUnix": 1617112817487,
    "id": "d842a0f4-ad8c-40eb-80b4-bfefc7b1b530",
    "lastUpdateTimeUnix": 1617112817487,
    "properties": {
        "age": 46,
        "name": "H.P. Lovecraft"
    },
    "vectorWeights": null
}
>>> client.data_object.delete(
...     uuid="d842a0f4-ad8c-40eb-80b4-bfefc7b1b530",
...     class_name='Author', # ONLY with Weaviate >= 1.14.0
... )
>>> client.data_object.get(
...     uuid="d842a0f4-ad8c-40eb-80b4-bfefc7b1b530",
...     class_name='Author', # ONLY with Weaviate >= 1.14.0
... )
None

Raises

requests.ConnectionError

If the network connection to Weaviate fails.

weaviate.UnexpectedStatusCodeException

If Weaviate reports a none OK status.

TypeError

If parameter has the wrong type.

ValueError

If uuid is not properly formed.

exists(uuid: str | UUID, class_name: str | None = None, consistency_level: ConsistencyLevel | None = None, tenant: str | None = None) bool[source]

Check if the object exist in Weaviate.

Parameters

uuidstr or uuid.UUID

The UUID of the object that may or may not exist within Weaviate.

class_nameOptional[str], optional

The class name of the object with UUID uuid. Introduced in Weaviate version 1.14.0. STRONGLY recommended to set it with Weaviate >= 1.14.0. It will be required in future versions of Weaviate Server and Clients. Use None value ONLY for Weaviate < 1.14.0, by default None

consistency_levelOptional[ConsistencyLevel], optional

Can be one of ‘ALL’, ‘ONE’, or ‘QUORUM’. Determines how many replicas must acknowledge

tenant: Optional[str], optional

The name of the tenant for which this operation is being performed.

Examples

>>> client.data_object.exists(
...     uuid='e067f671-1202-42c6-848b-ff4d1eb804ab',
...     class_name='Author',  # ONLY with Weaviate >= 1.14.0
... )
False
>>> client.data_object.create(
...     data_object = {'name': 'Andrzej Sapkowski', 'age': 72},
...     class_name = 'Author',
...     uuid = 'e067f671-1202-42c6-848b-ff4d1eb804ab'
... )
>>> client.data_object.exists(
...     uuid='e067f671-1202-42c6-848b-ff4d1eb804ab',
...     class_name='Author', # ONLY with Weaviate >= 1.14.0
... )
True

Returns

bool

True if object exists, False otherwise.

Raises

requests.ConnectionError

If the network connection to Weaviate fails.

weaviate.UnexpectedStatusCodeException

If Weaviate reports a none OK status.

TypeError

If parameter has the wrong type.

ValueError

If uuid is not properly formed.

get(uuid: str | UUID | None = None, additional_properties: List[str] | None = None, with_vector: bool = False, class_name: str | None = None, node_name: str | None = None, consistency_level: ConsistencyLevel | None = None, limit: int | None = None, after: str | UUID | None = None, offset: int | None = None, sort: Dict[str, str | bool | List[bool] | List[str]] | None = None, tenant: str | None = None) Dict[str, Any] | None[source]

Gets objects from Weaviate, the maximum number of objects returned is 100. If ‘uuid’ is None, all objects are returned. If ‘uuid’ is specified the result is the same as for get_by_uuid method.

Parameters

uuidstr, uuid.UUID or None, optional

The identifier of the object that should be retrieved.

additional_propertieslist of str, optional

list of additional properties that should be included in the request, by default None

with_vectorbool

If True the vector property will be returned too, by default False

class_name: Optional[str], optional

The class name of the object with UUID uuid. Introduced in Weaviate version v1.14.0. STRONGLY recommended to set it with Weaviate >= 1.14.0. It will be required in future versions of Weaviate Server and Clients. Use None value ONLY for Weaviate < v1.14.0, by default None

consistency_levelOptional[ConsistencyLevel], optional

Can be one of ‘ALL’, ‘ONE’, or ‘QUORUM’. Determines how many replicas must acknowledge a request before it is considered successful. Mutually exclusive with node_name param.

node_nameOptional[str], optional

The name of the target node which should fulfill the request. Mutually exclusive with consistency_level param.

limit: Optional[int], optional

The maximum number of data objects to return. by default None, which uses the Weaviate default of 100 entries

after: Optional[UUID], optional

Can be used to extract all elements by giving the last ID from the previous “page”. Requires limit to be set but cannot be combined with any other filters or search. Part of the Cursor API.

offset: Optional[int], optional

The offset of objects returned, i.e. the starting index of the returned objects. Should be used in conjunction with the ‘limit’ parameter.

sort: Optional[Dict]

A dictionary for sorting objects. sort[‘properties’]: str, List[str]

By which properties the returned objects should be sorted. When more than one property is given, the objects are sorted in order of the list. The order of the sorting can be given by using ‘sort[‘order_asc’]’.

sort[‘order_asc’]: bool, List[bool]

The order the properties given in ‘sort[‘properties’]’ should be returned in. When a single boolean is used, all properties are sorted in the same order. If a list is used, it needs to have the same length as ‘sort’. Each properties order is then decided individually. If ‘sort[‘order_asc’]’ is True, the properties are sorted in ascending order. If it is False, they are sorted in descending order. if ‘sort[‘order_asc’]’ is not given, all properties are sorted in ascending order.

tenant: Optional[str], optional

The name of the tenant for which this operation is being performed.

Returns

list of dicts

A list of all objects. If no objects where found the list is empty.

Raises

TypeError

If argument is of wrong type.

ValueError

If argument contains an invalid value.

requests.ConnectionError

If the network connection to Weaviate fails.

weaviate.UnexpectedStatusCodeException

If Weaviate reports a none OK status.

get_by_id(uuid: str | UUID, additional_properties: List[str] | None = None, with_vector: bool = False, class_name: str | None = None, node_name: str | None = None, consistency_level: ConsistencyLevel | None = None, tenant: str | None = None) dict | None[source]

Get an object as dict.

Parameters

uuidstr or uuid.UUID

The identifier of the object that should be retrieved.

additional_propertieslist of str, optional

List of additional properties that should be included in the request, by default None

with_vector: bool

If True the vector property will be returned too, by default False.

class_nameOptional[str], optional

The class name of the object with UUID uuid. Introduced in Weaviate version v1.14.0. STRONGLY recommended to set it with Weaviate >= 1.14.0. It will be required in future versions of Weaviate Server and Clients. Use None value ONLY for Weaviate < v1.14.0, by default None

tenant: str, optional

The name of the tenant for which this operation is being performed.

Examples

>>> client.data_object.get_by_id(
...     uuid="d842a0f4-ad8c-40eb-80b4-bfefc7b1b530",
...     class_name='Author', # ONLY with Weaviate >= 1.14.0
... )
{
    "additional": {},
    "class": "Author",
    "creationTimeUnix": 1617112817487,
    "id": "d842a0f4-ad8c-40eb-80b4-bfefc7b1b530",
    "lastUpdateTimeUnix": 1617112817487,
    "properties": {
        "age": 46,
        "name": "H.P. Lovecraft"
    },
    "vectorWeights": null
}

Returns

dict or None

dict in case the object exists. None in case the object does not exist.

Raises

TypeError

If argument is of wrong type.

ValueError

If argument contains an invalid value.

requests.ConnectionError

If the network connection to Weaviate fails.

weaviate.UnexpectedStatusCodeException

If Weaviate reports a none OK status.

replace(data_object: dict | str, class_name: str, uuid: str | UUID, vector: Sequence | None = None, consistency_level: ConsistencyLevel | None = None, tenant: str | None = None) None[source]

Replace an already existing object with the given data object. This method replaces the whole object.

Parameters

data_objectdict or str

Describes the new values. It may be an URL or path to a json or a python dict describing the new values.

class_namestr

Name of the class of the object that should be updated.

uuidstr or uuid.UUID

The UUID of the object that should be changed.

vector: Sequence or None, optional

Embedding for the object. Can be used when:

  • a class does not have a vectorization module.

  • The given vector was generated using the _identical_ vectorization module that is configured for the

class. In this case this vector takes precedence.

Supported types are list, ‘numpy.ndarray`, torch.Tensor and tf.Tensor, by default None.

consistency_levelOptional[ConsistencyLevel], optional

Can be one of ‘ALL’, ‘ONE’, or ‘QUORUM’. Determines how many replicas must acknowledge

tenant: Optional[str], optional

The name of the tenant for which this operation is being performed.

Examples

>>> author_id = client.data_object.create(
...     data_object = {'name': 'H. Lovecraft', 'age': 46},
...     class_name = 'Author'
... )
>>> client.data_object.get(author_id)
{
    "additional": {},
    "class": "Author",
    "creationTimeUnix": 1617112817487,
    "id": "d842a0f4-ad8c-40eb-80b4-bfefc7b1b530",
    "lastUpdateTimeUnix": 1617112817487,
    "properties": {
        "age": 46,
        "name": "H. Lovecraft"
    },
    "vectorWeights": null
}
>>> client.data_object.replace(
...     data_object = {'name': 'H.P. Lovecraft'},
...     class_name = 'Author',
...     uuid = author_id
... )
>>> client.data_object.get(author_id)
{
    "additional": {},
    "class": "Author",
    "id": "d842a0f4-ad8c-40eb-80b4-bfefc7b1b530",
    "lastUpdateTimeUnix": 1617112838668,
    "properties": {
        "name": "H.P. Lovecraft"
    },
    "vectorWeights": null
}

Raises

TypeError

If argument is of wrong type.

ValueError

If argument contains an invalid value.

requests.ConnectionError

If the network connection to Weaviate fails.

weaviate.UnexpectedStatusCodeException

If Weaviate reports a none OK status.

update(data_object: dict | str, class_name: str, uuid: str | UUID, vector: Sequence | None = None, consistency_level: ConsistencyLevel | None = None, tenant: str | None = None) None[source]

Update an already existing object in Weaviate with the given data object. Overwrites only the specified fields, the unspecified ones remain unchanged.

Parameters

data_objectdict or str

The object states the fields that should be updated. Fields not specified in the ‘data_object’ remain unchanged. Fields that are None will not be changed. If type is str it should be either an URL or a file.

class_namestr

The class name of the object.

uuidstr or uuid.UUID

The ID of the object that should be changed.

vector: Sequence or None, optional

Embedding for the object. Can be used when:

  • a class does not have a vectorization module.

  • The given vector was generated using the _identical_ vectorization module that is configured for the

class. In this case this vector takes precedence.

Supported types are list, ‘numpy.ndarray`, torch.Tensor and tf.Tensor, by default None.

consistency_levelOptional[ConsistencyLevel], optional

Can be one of ‘ALL’, ‘ONE’, or ‘QUORUM’. Determines how many replicas must acknowledge

tenant: Optional[str], optional

The name of the tenant for which this operation is being performed.

Examples

>>> author_id = client.data_object.create(
...     data_object = {'name': 'Philip Pullman', 'age': 64},
...     class_name = 'Author'
... )
>>> client.data_object.get(author_id)
{
    "additional": {},
    "class": "Author",
    "creationTimeUnix": 1617111215172,
    "id": "bec2bca7-264f-452a-a5bb-427eb4add068",
    "lastUpdateTimeUnix": 1617111215172,
    "properties": {
        "age": 64,
        "name": "Philip Pullman"
    },
    "vectorWeights": null
}
>>> client.data_object.update(
...     data_object = {'age': 74},
...     class_name = 'Author',
...     uuid = author_id
... )
>>> client.data_object.get(author_id)
{
    "additional": {},
    "class": "Author",
    "creationTimeUnix": 1617111215172,
    "id": "bec2bca7-264f-452a-a5bb-427eb4add068",
    "lastUpdateTimeUnix": 1617111215172,
    "properties": {
        "age": 74,
        "name": "Philip Pullman"
    },
    "vectorWeights": null
}

Raises

TypeError

If argument is of wrong type.

ValueError

If argument contains an invalid value.

requests.ConnectionError

If the network connection to Weaviate fails.

weaviate.UnexpectedStatusCodeException

If Weaviate reports a none successful status.

validate(data_object: dict | str, class_name: str, uuid: str | UUID | None = None, vector: Sequence | None = None) dict[source]

Validate an object against Weaviate.

Parameters

data_objectdict or str

Object to be validated. If type is str it should be either an URL or a file.

class_namestr

Name of the class of the object that should be validated.

uuidstr, uuid.UUID or None, optional

The UUID of the object that should be validated against Weaviate. by default None.

vector: Sequence or None, optional

The embedding of the object that should be validated. Can be used when:

  • a class does not have a vectorization module.

  • The given vector was generated using the _identical_ vectorization module that is configured for the

class. In this case this vector takes precedence.

Supported types are list, ‘numpy.ndarray`, torch.Tensor and tf.Tensor, by default None.

Examples

Assume we have a Author class only ‘name’ property, NO ‘age’.

>>> client1.data_object.validate(
...     data_object = {'name': 'H. Lovecraft'},
...     class_name = 'Author'
... )
{'error': None, 'valid': True}
>>> client1.data_object.validate(
...     data_object = {'name': 'H. Lovecraft', 'age': 46},
...     class_name = 'Author'
... )
{
    "error": [
        {
        "message": "invalid object: no such prop with name 'age' found in class 'Author'
            in the schema. Check your schema files for which properties in this class are
            available"
        }
    ],
    "valid": false
}

Returns

dict

Validation result. E.g. {“valid”: bool, “error”: None or list}

Raises

TypeError

If argument is of wrong type.

ValueError

If argument contains an invalid value.

weaviate.UnexpectedStatusCodeException

If validating the object against Weaviate failed with a different reason.

requests.ConnectionError

If the network connection to Weaviate fails.

Subpackages

Submodules

weaviate.data.crud_data module

DataObject class definition.

class weaviate.data.crud_data.DataObject(connection: Connection)[source]

Bases: object

DataObject class used to manipulate object to/from Weaviate.

Attributes

referenceweaviate.data.references.Reference

A Reference object to create objects cross-references.

Initialize a DataObject class instance.

Parameters

connectionweaviate.connect.Connection

Connection object to an active and running Weaviate instance.

create(data_object: dict | str, class_name: str, uuid: str | UUID | None = None, vector: Sequence | None = None, consistency_level: ConsistencyLevel | None = None, tenant: str | None = None) str[source]

Takes a dict describing the object and adds it to Weaviate.

Parameters

data_objectdict or str

Object to be added. If type is str it should be either a URL or a file.

class_namestr

Class name associated with the object given.

uuidstr, uuid.UUID or None, optional

Object will be created under this uuid if it is provided. Otherwise, Weaviate will generate a uuid for this object, by default None.

vector: Sequence or None, optional

Embedding for the object. Can be used when:

  • a class does not have a vectorization module.

  • The given vector was generated using the _identical_ vectorization module that is configured for the

class. In this case this vector takes precedence.

Supported types are list, ‘numpy.ndarray`, torch.Tensor and tf.Tensor, by default None.

consistency_levelOptional[ConsistencyLevel], optional

Can be one of ‘ALL’, ‘ONE’, or ‘QUORUM’. Determines how many replicas must acknowledge

tenant: Optional[str], optional

The name of the tenant for which this operation is being performed.

Examples

Schema contains a class Author with only ‘name’ and ‘age’ primitive property.

>>> client.data_object.create(
...     data_object = {'name': 'Neil Gaiman', 'age': 60},
...     class_name = 'Author',
... )
'46091506-e3a0-41a4-9597-10e3064d8e2d'
>>> client.data_object.create(
...     data_object = {'name': 'Andrzej Sapkowski', 'age': 72},
...     class_name = 'Author',
...     uuid = 'e067f671-1202-42c6-848b-ff4d1eb804ab'
... )
'e067f671-1202-42c6-848b-ff4d1eb804ab'

Returns

str

Returns the UUID of the created object if successful.

Raises

TypeError

If argument is of wrong type.

ValueError

If argument contains an invalid value.

weaviate.ObjectAlreadyExistsException

If an object with the given uuid already exists within Weaviate.

weaviate.UnexpectedStatusCodeException

If creating the object in Weaviate failed for a different reason, more information is given in the exception.

requests.ConnectionError

If the network connection to Weaviate fails.

delete(uuid: str | UUID, class_name: str | None = None, consistency_level: ConsistencyLevel | None = None, tenant: str | None = None) None[source]

Delete an existing object from Weaviate.

Parameters

uuidstr or uuid.UUID

The ID of the object that should be deleted.

class_nameOptional[str], optional

The class name of the object with UUID uuid. Introduced in Weaviate version v1.14.0. STRONGLY recommended to set it with Weaviate >= 1.14.0. It will be required in future versions of Weaviate Server and Clients. Use None value ONLY for Weaviate < v1.14.0, by default None

consistency_levelOptional[ConsistencyLevel], optional

Can be one of ‘ALL’, ‘ONE’, or ‘QUORUM’. Determines how many replicas must acknowledge

tenant: str, optional

The name of the tenant for which this operation is being performed.

Examples

>>> client.data_object.get(
...     uuid="d842a0f4-ad8c-40eb-80b4-bfefc7b1b530",
...     class_name='Author', # ONLY with Weaviate >= 1.14.0
... )
{
    "additional": {},
    "class": "Author",
    "creationTimeUnix": 1617112817487,
    "id": "d842a0f4-ad8c-40eb-80b4-bfefc7b1b530",
    "lastUpdateTimeUnix": 1617112817487,
    "properties": {
        "age": 46,
        "name": "H.P. Lovecraft"
    },
    "vectorWeights": null
}
>>> client.data_object.delete(
...     uuid="d842a0f4-ad8c-40eb-80b4-bfefc7b1b530",
...     class_name='Author', # ONLY with Weaviate >= 1.14.0
... )
>>> client.data_object.get(
...     uuid="d842a0f4-ad8c-40eb-80b4-bfefc7b1b530",
...     class_name='Author', # ONLY with Weaviate >= 1.14.0
... )
None

Raises

requests.ConnectionError

If the network connection to Weaviate fails.

weaviate.UnexpectedStatusCodeException

If Weaviate reports a none OK status.

TypeError

If parameter has the wrong type.

ValueError

If uuid is not properly formed.

exists(uuid: str | UUID, class_name: str | None = None, consistency_level: ConsistencyLevel | None = None, tenant: str | None = None) bool[source]

Check if the object exist in Weaviate.

Parameters

uuidstr or uuid.UUID

The UUID of the object that may or may not exist within Weaviate.

class_nameOptional[str], optional

The class name of the object with UUID uuid. Introduced in Weaviate version 1.14.0. STRONGLY recommended to set it with Weaviate >= 1.14.0. It will be required in future versions of Weaviate Server and Clients. Use None value ONLY for Weaviate < 1.14.0, by default None

consistency_levelOptional[ConsistencyLevel], optional

Can be one of ‘ALL’, ‘ONE’, or ‘QUORUM’. Determines how many replicas must acknowledge

tenant: Optional[str], optional

The name of the tenant for which this operation is being performed.

Examples

>>> client.data_object.exists(
...     uuid='e067f671-1202-42c6-848b-ff4d1eb804ab',
...     class_name='Author',  # ONLY with Weaviate >= 1.14.0
... )
False
>>> client.data_object.create(
...     data_object = {'name': 'Andrzej Sapkowski', 'age': 72},
...     class_name = 'Author',
...     uuid = 'e067f671-1202-42c6-848b-ff4d1eb804ab'
... )
>>> client.data_object.exists(
...     uuid='e067f671-1202-42c6-848b-ff4d1eb804ab',
...     class_name='Author', # ONLY with Weaviate >= 1.14.0
... )
True

Returns

bool

True if object exists, False otherwise.

Raises

requests.ConnectionError

If the network connection to Weaviate fails.

weaviate.UnexpectedStatusCodeException

If Weaviate reports a none OK status.

TypeError

If parameter has the wrong type.

ValueError

If uuid is not properly formed.

get(uuid: str | UUID | None = None, additional_properties: List[str] | None = None, with_vector: bool = False, class_name: str | None = None, node_name: str | None = None, consistency_level: ConsistencyLevel | None = None, limit: int | None = None, after: str | UUID | None = None, offset: int | None = None, sort: Dict[str, str | bool | List[bool] | List[str]] | None = None, tenant: str | None = None) Dict[str, Any] | None[source]

Gets objects from Weaviate, the maximum number of objects returned is 100. If ‘uuid’ is None, all objects are returned. If ‘uuid’ is specified the result is the same as for get_by_uuid method.

Parameters

uuidstr, uuid.UUID or None, optional

The identifier of the object that should be retrieved.

additional_propertieslist of str, optional

list of additional properties that should be included in the request, by default None

with_vectorbool

If True the vector property will be returned too, by default False

class_name: Optional[str], optional

The class name of the object with UUID uuid. Introduced in Weaviate version v1.14.0. STRONGLY recommended to set it with Weaviate >= 1.14.0. It will be required in future versions of Weaviate Server and Clients. Use None value ONLY for Weaviate < v1.14.0, by default None

consistency_levelOptional[ConsistencyLevel], optional

Can be one of ‘ALL’, ‘ONE’, or ‘QUORUM’. Determines how many replicas must acknowledge a request before it is considered successful. Mutually exclusive with node_name param.

node_nameOptional[str], optional

The name of the target node which should fulfill the request. Mutually exclusive with consistency_level param.

limit: Optional[int], optional

The maximum number of data objects to return. by default None, which uses the Weaviate default of 100 entries

after: Optional[UUID], optional

Can be used to extract all elements by giving the last ID from the previous “page”. Requires limit to be set but cannot be combined with any other filters or search. Part of the Cursor API.

offset: Optional[int], optional

The offset of objects returned, i.e. the starting index of the returned objects. Should be used in conjunction with the ‘limit’ parameter.

sort: Optional[Dict]

A dictionary for sorting objects. sort[‘properties’]: str, List[str]

By which properties the returned objects should be sorted. When more than one property is given, the objects are sorted in order of the list. The order of the sorting can be given by using ‘sort[‘order_asc’]’.

sort[‘order_asc’]: bool, List[bool]

The order the properties given in ‘sort[‘properties’]’ should be returned in. When a single boolean is used, all properties are sorted in the same order. If a list is used, it needs to have the same length as ‘sort’. Each properties order is then decided individually. If ‘sort[‘order_asc’]’ is True, the properties are sorted in ascending order. If it is False, they are sorted in descending order. if ‘sort[‘order_asc’]’ is not given, all properties are sorted in ascending order.

tenant: Optional[str], optional

The name of the tenant for which this operation is being performed.

Returns

list of dicts

A list of all objects. If no objects where found the list is empty.

Raises

TypeError

If argument is of wrong type.

ValueError

If argument contains an invalid value.

requests.ConnectionError

If the network connection to Weaviate fails.

weaviate.UnexpectedStatusCodeException

If Weaviate reports a none OK status.

get_by_id(uuid: str | UUID, additional_properties: List[str] | None = None, with_vector: bool = False, class_name: str | None = None, node_name: str | None = None, consistency_level: ConsistencyLevel | None = None, tenant: str | None = None) dict | None[source]

Get an object as dict.

Parameters

uuidstr or uuid.UUID

The identifier of the object that should be retrieved.

additional_propertieslist of str, optional

List of additional properties that should be included in the request, by default None

with_vector: bool

If True the vector property will be returned too, by default False.

class_nameOptional[str], optional

The class name of the object with UUID uuid. Introduced in Weaviate version v1.14.0. STRONGLY recommended to set it with Weaviate >= 1.14.0. It will be required in future versions of Weaviate Server and Clients. Use None value ONLY for Weaviate < v1.14.0, by default None

tenant: str, optional

The name of the tenant for which this operation is being performed.

Examples

>>> client.data_object.get_by_id(
...     uuid="d842a0f4-ad8c-40eb-80b4-bfefc7b1b530",
...     class_name='Author', # ONLY with Weaviate >= 1.14.0
... )
{
    "additional": {},
    "class": "Author",
    "creationTimeUnix": 1617112817487,
    "id": "d842a0f4-ad8c-40eb-80b4-bfefc7b1b530",
    "lastUpdateTimeUnix": 1617112817487,
    "properties": {
        "age": 46,
        "name": "H.P. Lovecraft"
    },
    "vectorWeights": null
}

Returns

dict or None

dict in case the object exists. None in case the object does not exist.

Raises

TypeError

If argument is of wrong type.

ValueError

If argument contains an invalid value.

requests.ConnectionError

If the network connection to Weaviate fails.

weaviate.UnexpectedStatusCodeException

If Weaviate reports a none OK status.

replace(data_object: dict | str, class_name: str, uuid: str | UUID, vector: Sequence | None = None, consistency_level: ConsistencyLevel | None = None, tenant: str | None = None) None[source]

Replace an already existing object with the given data object. This method replaces the whole object.

Parameters

data_objectdict or str

Describes the new values. It may be an URL or path to a json or a python dict describing the new values.

class_namestr

Name of the class of the object that should be updated.

uuidstr or uuid.UUID

The UUID of the object that should be changed.

vector: Sequence or None, optional

Embedding for the object. Can be used when:

  • a class does not have a vectorization module.

  • The given vector was generated using the _identical_ vectorization module that is configured for the

class. In this case this vector takes precedence.

Supported types are list, ‘numpy.ndarray`, torch.Tensor and tf.Tensor, by default None.

consistency_levelOptional[ConsistencyLevel], optional

Can be one of ‘ALL’, ‘ONE’, or ‘QUORUM’. Determines how many replicas must acknowledge

tenant: Optional[str], optional

The name of the tenant for which this operation is being performed.

Examples

>>> author_id = client.data_object.create(
...     data_object = {'name': 'H. Lovecraft', 'age': 46},
...     class_name = 'Author'
... )
>>> client.data_object.get(author_id)
{
    "additional": {},
    "class": "Author",
    "creationTimeUnix": 1617112817487,
    "id": "d842a0f4-ad8c-40eb-80b4-bfefc7b1b530",
    "lastUpdateTimeUnix": 1617112817487,
    "properties": {
        "age": 46,
        "name": "H. Lovecraft"
    },
    "vectorWeights": null
}
>>> client.data_object.replace(
...     data_object = {'name': 'H.P. Lovecraft'},
...     class_name = 'Author',
...     uuid = author_id
... )
>>> client.data_object.get(author_id)
{
    "additional": {},
    "class": "Author",
    "id": "d842a0f4-ad8c-40eb-80b4-bfefc7b1b530",
    "lastUpdateTimeUnix": 1617112838668,
    "properties": {
        "name": "H.P. Lovecraft"
    },
    "vectorWeights": null
}

Raises

TypeError

If argument is of wrong type.

ValueError

If argument contains an invalid value.

requests.ConnectionError

If the network connection to Weaviate fails.

weaviate.UnexpectedStatusCodeException

If Weaviate reports a none OK status.

update(data_object: dict | str, class_name: str, uuid: str | UUID, vector: Sequence | None = None, consistency_level: ConsistencyLevel | None = None, tenant: str | None = None) None[source]

Update an already existing object in Weaviate with the given data object. Overwrites only the specified fields, the unspecified ones remain unchanged.

Parameters

data_objectdict or str

The object states the fields that should be updated. Fields not specified in the ‘data_object’ remain unchanged. Fields that are None will not be changed. If type is str it should be either an URL or a file.

class_namestr

The class name of the object.

uuidstr or uuid.UUID

The ID of the object that should be changed.

vector: Sequence or None, optional

Embedding for the object. Can be used when:

  • a class does not have a vectorization module.

  • The given vector was generated using the _identical_ vectorization module that is configured for the

class. In this case this vector takes precedence.

Supported types are list, ‘numpy.ndarray`, torch.Tensor and tf.Tensor, by default None.

consistency_levelOptional[ConsistencyLevel], optional

Can be one of ‘ALL’, ‘ONE’, or ‘QUORUM’. Determines how many replicas must acknowledge

tenant: Optional[str], optional

The name of the tenant for which this operation is being performed.

Examples

>>> author_id = client.data_object.create(
...     data_object = {'name': 'Philip Pullman', 'age': 64},
...     class_name = 'Author'
... )
>>> client.data_object.get(author_id)
{
    "additional": {},
    "class": "Author",
    "creationTimeUnix": 1617111215172,
    "id": "bec2bca7-264f-452a-a5bb-427eb4add068",
    "lastUpdateTimeUnix": 1617111215172,
    "properties": {
        "age": 64,
        "name": "Philip Pullman"
    },
    "vectorWeights": null
}
>>> client.data_object.update(
...     data_object = {'age': 74},
...     class_name = 'Author',
...     uuid = author_id
... )
>>> client.data_object.get(author_id)
{
    "additional": {},
    "class": "Author",
    "creationTimeUnix": 1617111215172,
    "id": "bec2bca7-264f-452a-a5bb-427eb4add068",
    "lastUpdateTimeUnix": 1617111215172,
    "properties": {
        "age": 74,
        "name": "Philip Pullman"
    },
    "vectorWeights": null
}

Raises

TypeError

If argument is of wrong type.

ValueError

If argument contains an invalid value.

requests.ConnectionError

If the network connection to Weaviate fails.

weaviate.UnexpectedStatusCodeException

If Weaviate reports a none successful status.

validate(data_object: dict | str, class_name: str, uuid: str | UUID | None = None, vector: Sequence | None = None) dict[source]

Validate an object against Weaviate.

Parameters

data_objectdict or str

Object to be validated. If type is str it should be either an URL or a file.

class_namestr

Name of the class of the object that should be validated.

uuidstr, uuid.UUID or None, optional

The UUID of the object that should be validated against Weaviate. by default None.

vector: Sequence or None, optional

The embedding of the object that should be validated. Can be used when:

  • a class does not have a vectorization module.

  • The given vector was generated using the _identical_ vectorization module that is configured for the

class. In this case this vector takes precedence.

Supported types are list, ‘numpy.ndarray`, torch.Tensor and tf.Tensor, by default None.

Examples

Assume we have a Author class only ‘name’ property, NO ‘age’.

>>> client1.data_object.validate(
...     data_object = {'name': 'H. Lovecraft'},
...     class_name = 'Author'
... )
{'error': None, 'valid': True}
>>> client1.data_object.validate(
...     data_object = {'name': 'H. Lovecraft', 'age': 46},
...     class_name = 'Author'
... )
{
    "error": [
        {
        "message": "invalid object: no such prop with name 'age' found in class 'Author'
            in the schema. Check your schema files for which properties in this class are
            available"
        }
    ],
    "valid": false
}

Returns

dict

Validation result. E.g. {“valid”: bool, “error”: None or list}

Raises

TypeError

If argument is of wrong type.

ValueError

If argument contains an invalid value.

weaviate.UnexpectedStatusCodeException

If validating the object against Weaviate failed with a different reason.

requests.ConnectionError

If the network connection to Weaviate fails.