weaviate

Weaviate Python Client Library used to interact with a Weaviate instance.

The interaction with Weaviate instance should be through a Client object. A Client instance has instance attributes to all the object needed to create objects/schema, do classification, upload batches, query data, … Creating separate Schema, DataObject, Batch, Classification, Query, Connect, Reference is STRONGLY DISCOURAGED. The Client class creates the needed instances and connects all of them to the same Weaviate instance for you.

Examples

Creating and exploring a Weaviate instance running on localhost, on port 8080, with Authentication disabled.

>>> import weaviate
>>> client = weaviate.Client('http://localhost:8080')
>>> print_type = lambda obj: print(type(obj))
>>> print_type(client.batch)
<class 'weaviate.batch.crud_batch.Batch'>
>>> print_type(client.schema)
<class 'weaviate.schema.crud_schema.Schema'>
>>> print_type(client.classification)
<class 'weaviate.classification.classify.Classification'>
>>> print_type(client.data_object)
<class 'weaviate.data.crud_data.DataObject'>
>>> print_type(client.query)
<class 'weaviate.gql.query.Query'>

weaviate.__version__

Current weaviate-python library version installed.

Type:: str

class weaviate.AdditionalProperties(uuid: bool = False, vector: bool = False, creationTimeUnix: bool = False, lastUpdateTimeUnix: bool = False, distance: bool = False, certainty: bool = False, score: bool = False, explainScore: bool = False)

Bases: object

certainty: bool = False

creationTimeUnix: bool = False

distance: bool = False

explainScore: bool = False

lastUpdateTimeUnix: bool = False

score: bool = False

uuid: bool = False

vector: bool = False

class weaviate.AuthApiKey(api_key: str)

Bases: object

Using the given API key to authenticate with weaviate.

api_key: str

class weaviate.AuthBearerToken(access_token: str, expires_in: int = 60, refresh_token: str | None = None)

Bases: object

Using a preexisting bearer/access token for authentication.

The expiration time of access tokens is given in seconds.

Only the access token is required. However, when no refresh token is given, the authentication will expire once the lifetime of the access token is up.

access_token: str

expires_in: int = 60

refresh_token: str | None = None

class weaviate.AuthClientCredentials(client_secret: str, scope: str | List[str] | None = None)

Bases: object

Authenticate for the Client Credential flow using client secrets.

Acquire the client secret from your identify provider and set the appropriate scope. The client includes hardcoded scopes for Azure, otherwise it needs to be supplied. Scopes can be given as:

List of strings: [“scope1”, “scope2”]

space separated string: “scope1 scope2”

client_secret: str

scope: str | List[str] | None = None

class weaviate.AuthClientPassword(username: str, password: str, scope: str | ~typing.List[str] | None = <factory>)

Bases: object

Using username and password for authentication with Resource Owner Password flow.

For some providers the scope needs to contain “offline_access” (and “openid” which is automatically added) to return a refresh token. Without a refresh token the authentication will expire once the lifetime of the access token is up. Scopes can be given as:

List of strings: [“scope1”, “scope2”]

space separated string: “scope1 scope2”

password: str

scope: str | List[str] | None

username: str

exception weaviate.AuthenticationFailedException(message: str = '')

Bases: WeaviateBaseError

Authentication Failed Exception.

Weaviate base exception initializer. :param message: An error message specific to the context in which the error occurred. :type message: str, optional

Bases: object

A python native Weaviate Client class that encapsulates Weaviate functionalities in one object. A Client instance creates all the needed objects to interact with Weaviate, and connects all of them to the same Weaviate instance. See below the Attributes of the Client instance. For the per attribute functionality see that attribute’s documentation.

backup

A Backup object instance connected to the same Weaviate instance as the Client.

Type:: weaviate.backup.Backup

batch

A Batch object instance connected to the same Weaviate instance as the Client.

Type:: weaviate.batch.Batch

classification

A Classification object instance connected to the same Weaviate instance as the Client.

Type:: weaviate.classification.Classification

cluster

A Cluster object instance connected to the same Weaviate instance as the Client.

Type:: weaviate.cluster.Cluster

contextionary

A Contextionary object instance connected to the same Weaviate instance as the Client.

Type:: weaviate.contextionary.Contextionary

data_object

A DataObject object instance connected to the same Weaviate instance as the Client.

Type:: weaviate.data.DataObject

schema

A Schema object instance connected to the same Weaviate instance as the Client.

Type:: weaviate.schema.Schema

query

A Query object instance connected to the same Weaviate instance as the Client.

Type:: weaviate.gql.Query

Initialize a Client class instance.

Parameters:

url (str) – The URL to the weaviate instance.
auth_client_secret (weaviate.AuthCredentials or None, optional) –
fmt (#) – Authenticate to weaviate by using one of the given authentication modes: - weaviate.auth.AuthBearerToken to use existing access and (optionally, but recommended) refresh tokens - weaviate.auth.AuthClientPassword to use username and password for oidc Resource Owner Password flow - weaviate.auth.AuthClientCredentials to use a client secret for oidc client credential flow
fmt –
timeout_config (tuple(Real, Real) or Real, optional) – Set the timeout configuration for all requests to the Weaviate server. It can be a real number or, a tuple of two real numbers: (connect timeout, read timeout). If only one real number is passed then both connect and read timeout will be set to that value, by default (2, 20).
proxies (dict, str or None, optional) – Proxies to be used for requests. Are used by both ‘requests’ and ‘aiohttp’. Can be passed as a dict (‘requests’ format: https://docs.python-requests.org/en/stable/user/advanced/#proxies), str (HTTP/HTTPS protocols are going to use this proxy) or None. Default None.
trust_env (bool, optional) – Whether to read proxies from the ENV variables: (HTTP_PROXY or http_proxy, HTTPS_PROXY or https_proxy). Default False. NOTE: ‘proxies’ has priority over ‘trust_env’, i.e. if ‘proxies’ is NOT None, ‘trust_env’ is ignored.
additional_headers (dict or None) –
Additional headers to include in the requests. Can be used to set OpenAI/HuggingFace keys. OpenAI/HuggingFace key looks like this:

{“X-OpenAI-Api-Key”: “<THE-KEY>”}, {“X-HuggingFace-Api-Key”: “<THE-KEY>”}

by default None
startup_period (int or None) – How long the client will wait for Weaviate to start before raising a RequestsConnectionError. If None, the client won’t wait at all. Default timeout is 5s.
embedded_options (weaviate.embedded.EmbeddedOptions or None, optional) – Create an embedded Weaviate cluster inside the client - You can pass weaviate.embedded.EmbeddedOptions() with default values - Take a look at the attributes of weaviate.embedded.EmbeddedOptions to see what is configurable
additional_config (weaviate.Config, optional) – Additional and advanced configuration options for weaviate.

Examples

Without Auth.

>>> client = Client(
...     url = 'http://localhost:8080'
... )
>>> client = Client(
...     url = 'http://localhost:8080',
...     timeout_config = (5, 15)
... )

With Auth.

>>> my_credentials = weaviate.AuthClientPassword(USER_NAME, MY_PASSWORD)
>>> client = Client(
...     url = 'http://localhost:8080',
...     auth_client_secret = my_credentials
... )

Creating a client with an embedded database:

>>> from weaviate import EmbeddedOptions
>>> client = Client(embedded_options=EmbeddedOptions())

Creating a client with additional configurations:

>>> from weaviate import Config
>>> client = Client(additional_config=Config())

Raises:: TypeError – If arguments are of a wrong data type.

get_meta() → dict

Get the meta endpoint description of weaviate.

Returns:: The dict describing the weaviate configuration.
Return type:: dict
Raises:: weaviate.UnexpectedStatusCodeException – If weaviate reports a none OK status.

get_open_id_configuration() → Dict[str, Any] | None

Get the openid-configuration.

Returns:: The configuration or None if not configured.
Return type:: dict
Raises:: weaviate.UnexpectedStatusCodeException – If weaviate reports a none OK status.

is_live() → bool

Ping Weaviate’s live state.

Returns:: True if weaviate is live and should not be killed, False otherwise.
Return type:: bool

is_ready() → bool

Ping Weaviate’s ready state

Returns:: True if Weaviate is ready to accept requests, False otherwise.
Return type:: bool

property timeout_config: Tuple[int | float, int | float]

Getter/setter for timeout_config.

Parameters:

timeout_config (tuple(float, float) or float, optional) –

For Getter only: Set the timeout configuration for all requests to the Weaviate server. It can be a real number or, a tuple of two real numbers:

(connect timeout, read timeout).

If only one real number is passed then both connect and read timeout will be set to that value.

Returns:

For Getter only: Requests Timeout configuration.

Return type:

Tuple[float, float]

class weaviate.Config(grpc_port_experimental: Optional[int] = None, connection_config: weaviate.config.ConnectionConfig = <factory>)

Bases: object

connection_config: ConnectionConfig

grpc_port_experimental: int | None = None

class weaviate.ConnectionConfig(session_pool_connections: int = 20, session_pool_maxsize: int = 20)

Bases: object

session_pool_connections: int = 20

session_pool_maxsize: int = 20

class weaviate.ConsistencyLevel(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

ALL = 'ALL'

ONE = 'ONE'

QUORUM = 'QUORUM'

class weaviate.EmbeddedOptions(persistence_data_path: str = '/home/docs/.local/share/weaviate', binary_path: str = '/home/docs/.cache/weaviate-embedded', version: str = '1.19.3', port: int = 6666, hostname: str = '127.0.0.1', additional_env_vars: Dict[str, str] | None = None)

Bases: object

additional_env_vars: Dict[str, str] | None = None

binary_path: str = '/home/docs/.cache/weaviate-embedded'

hostname: str = '127.0.0.1'

persistence_data_path: str = '/home/docs/.local/share/weaviate'

port: int = 6666

version: str = '1.19.3'

class weaviate.LinkTo(link_on: str, linked_class: str, properties: List[Union[str, ForwardRef('LinkTo')]])

Bases: object

link_on: str

linked_class: str

properties: List[str | LinkTo]

exception weaviate.ObjectAlreadyExistsException(message: str = '')

Bases: WeaviateBaseError

Object Already Exists Exception.

Weaviate base exception initializer. :param message: An error message specific to the context in which the error occurred. :type message: str, optional

exception weaviate.SchemaValidationException(message: str = '')

Bases: WeaviateBaseError

Schema Validation Exception.

Weaviate base exception initializer. :param message: An error message specific to the context in which the error occurred. :type message: str, optional

exception weaviate.UnexpectedStatusCodeException(message: str, response: Response)

Bases: WeaviateBaseError

Is raised in case the status code returned from Weaviate is not handled in the client implementation and suggests an error.

Custom code can act on the attributes: - status_code - json

Parameters:

message (str) – An error message specific to the context, in which the error occurred.
response (requests.Response) – The request response of which the status code was unexpected.

property status_code: int

class weaviate.WeaviateErrorRetryConf(number_retries: int = 3, errors_to_exclude: List[str] | None = None, errors_to_include: List[str] | None = None)

Bases: object

Configures how often objects should be retried when Weavaite returns an error and which errors should be included or excluded. By default, all errors are retried.

Parameters:

number_retries (int) – How often a batch that includes objects with errors should be retried. Must be >=1.
errors_to_exclude (Optional[List[str]]) –
Which errors should NOT be retried. All other errors will be retried. An object will be skipped, when the given string is part of the weaviate error message.

Example: errors_to_exclude =[“string1”, “string2”] will match the error with message “Long error message that contains string1”.
errors_to_include (Optional[List[str]]) –
Which errors should be retried. All other errors will NOT be retried. An object will be included, when the given string is part of the weaviate error message.

Example: errors_to_include =[“string1”, “string2”] will match the error with message “Long error message that contains string1”.

errors_to_exclude: List[str] | None = None

errors_to_include: List[str] | None = None

number_retries: int = 3

exception weaviate.WeaviateStartUpError(message: str = '')

Bases: WeaviateBaseError

Is raised if weaviate does not start up in time.

Weaviate base exception initializer. :param message: An error message specific to the context in which the error occurred. :type message: str, optional

weaviate

Subpackages