Weaviate Packages

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

class weaviate.Client(url: str | None = None, auth_client_secret: _BearerToken | _ClientPassword | _ClientCredentials | _APIKey | None = None, timeout_config: Tuple[int | float, int | float] | int | float = (10, 60), proxies: dict | str | None = None, trust_env: bool = False, additional_headers: dict | None = None, startup_period: int | None = None, embedded_options: EmbeddedOptions | None = None, additional_config: Config | None = None)[source]

Bases: _ClientBase[Connection]

The v3 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.

Attributes

backupweaviate.backup.Backup

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

batchweaviate.batch.Batch

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

classificationweaviate.classification.Classification

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

clusterweaviate.cluster.Cluster

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

contextionaryweaviate.contextionary.Contextionary

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

data_objectweaviate.data.DataObject

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

schemaweaviate.schema.Schema

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

queryweaviate.gql.Query

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

Initialize a Client class instance to use when interacting with Weaviate.

Arguments:

urlstr or None, optional

The connection string to the REST API of Weaviate.

auth_client_secret : weaviate.AuthCredentials or None, optional # fmt: off

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: on 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).

proxiesdict, 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_envbool, 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_headersdict 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_periodint or None

deprecated, has no effect

embedded_optionsweaviate.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.

Raises:

TypeError

If arguments are of a wrong data type.

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

Getter/setter for timeout_config.

Parameters

timeout_configtuple(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

Tuple[float, float]

For Getter only: Requests Timeout configuration.

class weaviate.WeaviateClient(connection_params: ConnectionParams | None = None, embedded_options: EmbeddedOptions | None = None, auth_client_secret: _BearerToken | _ClientPassword | _ClientCredentials | _APIKey | None = None, additional_headers: dict | None = None, additional_config: AdditionalConfig | None = None, skip_init_checks: bool = False)[source]

Bases: _ClientBase[ConnectionV4]

The v4 Python-native Weaviate Client class that encapsulates Weaviate functionalities in one object.

WARNING: This client is only compatible with Weaviate v1.23.6 and higher!

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.

Attributes:
backup

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

batch

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

classification

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

cluster

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

collections

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

Initialise a WeaviateClient class instance to use when interacting with Weaviate.

Use this specific initializer when you want to create a custom Client specific to your Weaviate setup.

If you want to get going quickly connecting to WCS or a local instance then use the weaviate.connect_to_wcs or weaviate.connect_to_local helper functions instead.

Arguments:
  • connection_params: weaviate.connect.ConnectionParams or None, optional
    • The connection parameters to use for the underlying HTTP requests.

  • embedded_options: weaviate.EmbeddedOptions or None, optional
    • The options to use when provisioning an embedded Weaviate instance.

  • auth_client_secret: weaviate.AuthCredentials or None, optional
    • 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

  • additional_headers: dict or None, optional
  • additional_config: weaviate.AdditionalConfig or None, optional
    • Additional and advanced configuration options for Weaviate.

  • skip_init_checks: bool, optional
    • If set to True then the client will not perform any checks including ensuring that weaviate has started. This is useful for air-gapped environments and high-performance setups.

backup

This namespace contains all functionality to backup data.

batch

This namespace contains all the functionality to upload data in batches to Weaviate for all collections and tenants.

close() None[source]

In order to clean up any resources used by the client, call this method when you are done with it.

If you do not do this, memory leaks may occur due to stale connections. This method also closes the embedded database if one was started.

cluster

This namespace contains all functionality to inspect the connected Weaviate cluster.

collections

This namespace contains all the functionality to manage Weaviate data collections. It is your main entry point for all collection-related functionality.

Use it to retrieve collection objects using client.collections.get(“MyCollection”) or to create new collections using client.collections.create(“MyCollection”, …).

connect() None[source]

Connect to the Weaviate instance performing all the necessary checks.

If you have specified skip_init_checks in the constructor then this method will not perform any runtime checks to ensure that Weaviate is running and ready to accept requests. This is useful for air-gapped environments and high-performance setups.

This method is idempotent and will only perform the checks once. Any subsequent calls do nothing while client.is_connected() == True.

Raises:
weaviate.WeaviateConnectionError

If the network connection to weaviate fails.

weaviate.UnexpectedStatusCodeException

If weaviate reports a none OK status.

graphql_raw_query(gql_query: str) _RawGQLReturn[source]

Allows to send graphQL string queries, this should only be used for weaviate-features that are not yet supported.

Be cautious of injection risks when generating query strings.

Arguments:
gql_query

GraphQL query as a string.

Returns:

A dict with the response from the GraphQL query.

Raises
TypeError

If ‘gql_query’ is not of type str.

weaviate.WeaviateConnectionError

If the network connection to weaviate fails.

weaviate.UnexpectedStatusCodeError

If weaviate reports a none OK status.

is_connected() bool[source]

Check if the client is connected to Weaviate.

Returns:
bool

True if the client is connected to Weaviate with an open connection pool, False otherwise.

is_live() bool[source]

Ping Weaviate’s live state.

Returns:
bool

True if weaviate is live and should not be killed, False otherwise.

weaviate.connect_to_custom(http_host: str, http_port: int, http_secure: bool, grpc_host: str, grpc_port: int, grpc_secure: bool, headers: Dict[str, str] | None = None, additional_config: AdditionalConfig | None = None, auth_credentials: _BearerToken | _ClientPassword | _ClientCredentials | _APIKey | None = None, skip_init_checks: bool = False) WeaviateClient[source]

Connect to a Weaviate instance with custom connection parameters.

If this is not sufficient for your customization needs then instantiate a weaviate.WeaviateClient directly.

This method handles automatically connecting to Weaviate but not automatically closing the connection. Once you are done with the client you should call client.close() to close the connection and free up resources. Alternatively, you can use the client as a context manager in a with statement, which will automatically close the connection when the context is exited. See the examples below for details.

Arguments:
http_host

The host to use for the underlying REST and GraphQL API calls.

http_port

The port to use for the underlying REST and GraphQL API calls.

http_secure

Whether to use https for the underlying REST and GraphQL API calls.

grpc_host

The host to use for the underlying gRPC API.

grpc_port

The port to use for the underlying gRPC API.

grpc_secure

Whether to use a secure channel for the underlying gRPC API.

headers

Additional headers to include in the requests, e.g. API keys for Cloud vectorization.

additional_config

This includes many additional, rarely used config options. use wvc.init.AdditionalConfig() to configure.

auth_credentials

The credentials to use for authentication with your Weaviate instance. This can be an API key, in which case use weaviate.classes.init.Auth.api_key(), a bearer token, in which case use weaviate.classes.init.Auth.bearer_token(), a client secret, in which case use weaviate.classes.init.Auth.client_credentials() or a username and password, in which case use weaviate.classes.init.Auth.client_password().

skip_init_checks

Whether to skip the initialization checks when connecting to Weaviate.

Returns
weaviate.WeaviateClient

The client connected to the instance with the required parameters set appropriately.

Examples:
>>> import weaviate
>>> client = weaviate.connect_to_custom(
...     http_host="localhost",
...     http_port=8080,
...     http_secure=False,
...     grpc_host="localhost",
...     grpc_port=50051,
...     grpc_secure=False,
... )
>>> client.is_ready()
True
>>> client.close() # Close the connection when you are done with it.
################## With Context Manager #############################
>>> import weaviate
>>> with weaviate.connect_to_custom(
...     http_host="localhost",
...     http_port=8080,
...     http_secure=False,
...     grpc_host="localhost",
...     grpc_port=50051,
...     grpc_secure=False,
... ) as client:
...     client.is_ready()
True
>>> # The connection is automatically closed when the context is exited.
weaviate.connect_to_embedded(hostname: str = '127.0.0.1', port: int = 8079, grpc_port: int = 50050, headers: Dict[str, str] | None = None, additional_config: AdditionalConfig | None = None, version: str = '1.23.7', persistence_data_path: str | None = None, binary_path: str | None = None, environment_variables: Dict[str, str] | None = None) WeaviateClient[source]

Connect to an embedded Weaviate instance.

This method handles automatically connecting to Weaviate but not automatically closing the connection. Once you are done with the client you should call client.close() to close the connection and free up resources. Alternatively, you can use the client as a context manager in a with statement, which will automatically close the connection when the context is exited. See the examples below for details.

See [the docs](https://weaviate.io/developers/weaviate/installation/embedded#embedded-options) for more details.

Arguments:
hostname

The hostname to use for the underlying REST & GraphQL API calls.

port

The port to use for the underlying REST and GraphQL API calls.

grpc_port

The port to use for the underlying gRPC API.

headers

Additional headers to include in the requests, e.g. API keys for Cloud vectorization.

additional_config

This includes many additional, rarely used config options. use wvc.init.AdditionalConfig() to configure.

version

Weaviate version to be used for the embedded instance.

persistence_data_path

Directory where the files making up the database are stored. When the XDG_DATA_HOME env variable is set, the default value is: XDG_DATA_HOME/weaviate/ Otherwise it is: ~/.local/share/weaviate

binary_path

Directory where to download the binary. If deleted, the client will download the binary again. When the XDG_CACHE_HOME env variable is set, the default value is: XDG_CACHE_HOME/weaviate-embedded/ Otherwise it is: ~/.cache/weaviate-embedded

environment_variables

Additional environment variables to be passed to the embedded instance for configuration.

Returns
weaviate.WeaviateClient

The client connected to the embedded instance with the required parameters set appropriately.

Examples:
>>> import weaviate
>>> client = weaviate.connect_to_embedded(
...     port=8080,
...     grpc_port=50051,
... )
>>> client.is_ready()
True
>>> client.close() # Close the connection when you are done with it.
################## With Context Manager #############################
>>> import weaviate
>>> with weaviate.connect_to_embedded(
...     port=8080,
...     grpc_port=50051,
... ) as client:
...     client.is_ready()
True
>>> # The connection is automatically closed when the context is exited.
weaviate.connect_to_local(host: str = 'localhost', port: int = 8080, grpc_port: int = 50051, headers: Dict[str, str] | None = None, additional_config: AdditionalConfig | None = None, skip_init_checks: bool = False, auth_credentials: _BearerToken | _ClientPassword | _ClientCredentials | _APIKey | None = None) WeaviateClient[source]

Connect to a local Weaviate instance deployed using Docker compose with standard port configurations.

This method handles automatically connecting to Weaviate but not automatically closing the connection. Once you are done with the client you should call client.close() to close the connection and free up resources. Alternatively, you can use the client as a context manager in a with statement, which will automatically close the connection when the context is exited. See the examples below for details.

Arguments:
host

The host to use for the underlying REST and GraphQL API calls.

port

The port to use for the underlying REST and GraphQL API calls.

grpc_port

The port to use for the underlying gRPC API.

headers

Additional headers to include in the requests, e.g. API keys for Cloud vectorization.

additional_config

This includes many additional, rarely used config options. use wvc.init.AdditionalConfig() to configure.

skip_init_checks

Whether to skip the initialization checks when connecting to Weaviate.

auth_credentials

The credentials to use for authentication with your Weaviate instance. This can be an API key, in which case use weaviate.classes.init.Auth.api_key(), a bearer token, in which case use weaviate.classes.init.Auth.bearer_token(), a client secret, in which case use weaviate.classes.init.Auth.client_credentials() or a username and password, in which case use weaviate.classes.init.Auth.client_password().

Returns
weaviate.WeaviateClient

The client connected to the local instance with default parameters set as:

Examples:
>>> import weaviate
>>> client = weaviate.connect_to_local(
...     host="localhost",
...     port=8080,
...     grpc_port=50051,
... )
>>> client.is_ready()
True
>>> client.close() # Close the connection when you are done with it.
################## With Context Manager #############################
>>> import weaviate
>>> with weaviate.connect_to_local(
...     host="localhost",
...     port=8080,
...     grpc_port=50051,
... ) as client:
...     client.is_ready()
True
>>> # The connection is automatically closed when the context is exited.
weaviate.connect_to_wcs(cluster_url: str, auth_credentials: _BearerToken | _ClientPassword | _ClientCredentials | _APIKey | None, headers: Dict[str, str] | None = None, additional_config: AdditionalConfig | None = None, skip_init_checks: bool = False) WeaviateClient[source]

Connect to your own Weaviate Cloud Service (WCS) instance.

This method handles automatically connecting to Weaviate but not automatically closing the connection. Once you are done with the client you should call client.close() to close the connection and free up resources. Alternatively, you can use the client as a context manager in a with statement, which will automatically close the connection when the context is exited. See the examples below for details.

Arguments:
cluster_url

The WCS cluster URL or hostname to connect to. Usually in the form rAnD0mD1g1t5.something.weaviate.cloud

auth_credentials

The credentials to use for authentication with your Weaviate instance. This can be an API key, in which case use weaviate.classes.init.Auth.api_key(), a bearer token, in which case use weaviate.classes.init.Auth.bearer_token(), a client secret, in which case use weaviate.classes.init.Auth.client_credentials() or a username and password, in which case use weaviate.classes.init.Auth.client_password().

headers

Additional headers to include in the requests, e.g. API keys for third-party Cloud vectorization.

additional_config

This includes many additional, rarely used config options. use wvc.init.AdditionalConfig() to configure.

skip_init_checks

Whether to skip the initialization checks when connecting to Weaviate.

Returns
weaviate.WeaviateClient

The client connected to the cluster with the required parameters set appropriately.

Examples:
>>> import weaviate
>>> client = weaviate.connect_to_wcs(
...     cluster_url="rAnD0mD1g1t5.something.weaviate.cloud",
...     auth_credentials=weaviate.classes.init.Auth.api_key("my-api-key"),
... )
>>> client.is_ready()
True
>>> client.close() # Close the connection when you are done with it.
################## With Context Manager #############################
>>> import weaviate
>>> with weaviate.connect_to_wcs(
...     cluster_url="rAnD0mD1g1t5.something.weaviate.cloud",
...     auth_credentials=weaviate.classes.init.Auth.api_key("my-api-key"),
... ) as client:
...     client.is_ready()
True
>>> # The connection is automatically closed when the context is exited.

Subpackages

Submodules

weaviate.auth module

Authentication class definitions.

class weaviate.auth.Auth[source]

Bases: object

static api_key(api_key: str) _APIKey[source]
static bearer_token(access_token: str, expires_in: int = 60, refresh_token: str | None = None) _BearerToken[source]
static client_credentials(client_secret: str, scope: str | List[str] | None = None) _ClientCredentials[source]
static client_password(username: str, password: str, scope: str | List[str] | None = None) _ClientPassword[source]
weaviate.auth.AuthApiKey

@deprecated; use wvc.Auth.api_key() instead.

weaviate.auth.AuthBearerToken

@deprecated; use wvc.Auth.api_key() instead.

weaviate.auth.AuthClientCredentials

@deprecated; use wvc.Auth.api_key() instead.

weaviate.auth.AuthClientPassword

@deprecated; use wvc.Auth.api_key() instead.

weaviate.classes module

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

Bases: str, Enum

The consistency levels when writing to Weaviate with replication enabled.

Attributes:

ALL: Wait for confirmation of write success from all, N, replicas. ONE: Wait for confirmation of write success from only one replica. QUORUM: Wait for confirmation of write success from a quorum: N/2+1, of replicas.

ALL = 'ALL'
ONE = 'ONE'
QUORUM = 'QUORUM'

weaviate.client module

Client class definition.

class weaviate.client.Client(url: str | None = None, auth_client_secret: _BearerToken | _ClientPassword | _ClientCredentials | _APIKey | None = None, timeout_config: Tuple[int | float, int | float] | int | float = (10, 60), proxies: dict | str | None = None, trust_env: bool = False, additional_headers: dict | None = None, startup_period: int | None = None, embedded_options: EmbeddedOptions | None = None, additional_config: Config | None = None)[source]

Bases: _ClientBase[Connection]

The v3 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.

Attributes

backupweaviate.backup.Backup

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

batchweaviate.batch.Batch

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

classificationweaviate.classification.Classification

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

clusterweaviate.cluster.Cluster

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

contextionaryweaviate.contextionary.Contextionary

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

data_objectweaviate.data.DataObject

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

schemaweaviate.schema.Schema

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

queryweaviate.gql.Query

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

Initialize a Client class instance to use when interacting with Weaviate.

Arguments:

urlstr or None, optional

The connection string to the REST API of Weaviate.

auth_client_secret : weaviate.AuthCredentials or None, optional # fmt: off

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: on 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).

proxiesdict, 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_envbool, 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_headersdict 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_periodint or None

deprecated, has no effect

embedded_optionsweaviate.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.

Raises:

TypeError

If arguments are of a wrong data type.

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

Getter/setter for timeout_config.

Parameters

timeout_configtuple(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

Tuple[float, float]

For Getter only: Requests Timeout configuration.

class weaviate.client.WeaviateClient(connection_params: ConnectionParams | None = None, embedded_options: EmbeddedOptions | None = None, auth_client_secret: _BearerToken | _ClientPassword | _ClientCredentials | _APIKey | None = None, additional_headers: dict | None = None, additional_config: AdditionalConfig | None = None, skip_init_checks: bool = False)[source]

Bases: _ClientBase[ConnectionV4]

The v4 Python-native Weaviate Client class that encapsulates Weaviate functionalities in one object.

WARNING: This client is only compatible with Weaviate v1.23.6 and higher!

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.

Attributes:
backup

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

batch

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

classification

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

cluster

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

collections

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

Initialise a WeaviateClient class instance to use when interacting with Weaviate.

Use this specific initializer when you want to create a custom Client specific to your Weaviate setup.

If you want to get going quickly connecting to WCS or a local instance then use the weaviate.connect_to_wcs or weaviate.connect_to_local helper functions instead.

Arguments:
  • connection_params: weaviate.connect.ConnectionParams or None, optional
    • The connection parameters to use for the underlying HTTP requests.

  • embedded_options: weaviate.EmbeddedOptions or None, optional
    • The options to use when provisioning an embedded Weaviate instance.

  • auth_client_secret: weaviate.AuthCredentials or None, optional
    • 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

  • additional_headers: dict or None, optional
  • additional_config: weaviate.AdditionalConfig or None, optional
    • Additional and advanced configuration options for Weaviate.

  • skip_init_checks: bool, optional
    • If set to True then the client will not perform any checks including ensuring that weaviate has started. This is useful for air-gapped environments and high-performance setups.

backup

This namespace contains all functionality to backup data.

batch

This namespace contains all the functionality to upload data in batches to Weaviate for all collections and tenants.

close() None[source]

In order to clean up any resources used by the client, call this method when you are done with it.

If you do not do this, memory leaks may occur due to stale connections. This method also closes the embedded database if one was started.

cluster

This namespace contains all functionality to inspect the connected Weaviate cluster.

collections

This namespace contains all the functionality to manage Weaviate data collections. It is your main entry point for all collection-related functionality.

Use it to retrieve collection objects using client.collections.get(“MyCollection”) or to create new collections using client.collections.create(“MyCollection”, …).

connect() None[source]

Connect to the Weaviate instance performing all the necessary checks.

If you have specified skip_init_checks in the constructor then this method will not perform any runtime checks to ensure that Weaviate is running and ready to accept requests. This is useful for air-gapped environments and high-performance setups.

This method is idempotent and will only perform the checks once. Any subsequent calls do nothing while client.is_connected() == True.

Raises:
weaviate.WeaviateConnectionError

If the network connection to weaviate fails.

weaviate.UnexpectedStatusCodeException

If weaviate reports a none OK status.

graphql_raw_query(gql_query: str) _RawGQLReturn[source]

Allows to send graphQL string queries, this should only be used for weaviate-features that are not yet supported.

Be cautious of injection risks when generating query strings.

Arguments:
gql_query

GraphQL query as a string.

Returns:

A dict with the response from the GraphQL query.

Raises
TypeError

If ‘gql_query’ is not of type str.

weaviate.WeaviateConnectionError

If the network connection to weaviate fails.

weaviate.UnexpectedStatusCodeError

If weaviate reports a none OK status.

is_connected() bool[source]

Check if the client is connected to Weaviate.

Returns:
bool

True if the client is connected to Weaviate with an open connection pool, False otherwise.

is_live() bool[source]

Ping Weaviate’s live state.

Returns:
bool

True if weaviate is live and should not be killed, False otherwise.

weaviate.config module

pydantic model weaviate.config.AdditionalConfig[source]

Bases: BaseModel

Use this class to specify the connection and proxy settings for your client when connecting to Weaviate.

When specifying the timeout, you can either provide a tuple with the query and insert timeouts, or a Timeout object. The Timeout object gives you additional option to configure the init timeout, which controls how long the client initialisation checks will wait for before throwing. This is useful when you have a slow network connection.

When specifying the proxies, be aware that supplying a URL (str) will populate all of the http, https, and grpc proxies. In order for this to be possible, you must have a proxy that is capable of handling simultaneous HTTP/1.1 and HTTP/2 traffic.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

field connection: ConnectionConfig [Optional]
field proxies: str | Proxies | None = None
field timeout_: Tuple[int, int] | Timeout [Optional] (alias 'timeout')
field trust_env: bool = False
property timeout: Timeout
class weaviate.config.Config(grpc_port_experimental: Optional[int] = None, grpc_secure_experimental: bool = False, connection_config: weaviate.config.ConnectionConfig = <factory>)[source]

Bases: object

connection_config: ConnectionConfig
grpc_port_experimental: int | None = None
grpc_secure_experimental: bool = False
class weaviate.config.ConnectionConfig(session_pool_connections: int = 20, session_pool_maxsize: int = 100, session_pool_max_retries: int = 3)[source]

Bases: object

session_pool_connections: int = 20
session_pool_max_retries: int = 3
session_pool_maxsize: int = 100
pydantic model weaviate.config.Proxies[source]

Bases: BaseModel

Proxy configurations for sending requests to Weaviate through a proxy.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

field grpc: str | None = None
field http: str | None = None
field https: str | None = None
pydantic model weaviate.config.Timeout[source]

Bases: BaseModel

Timeouts for the different operations in the client.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

field init: int = 1
Constraints:
  • ge = 0

field insert: int = 90
Constraints:
  • ge = 0

field query: int = 30
Constraints:
  • ge = 0

weaviate.embedded module

weaviate.embedded.EmbeddedDB

alias of EmbeddedV3

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

Bases: object

additional_env_vars: Dict[str, str] | None = None
binary_path: str = '/home/docs/.cache/weaviate-embedded'
grpc_port: int = 50060
hostname: str = '127.0.0.1'
persistence_data_path: str = '/home/docs/.local/share/weaviate'
port: int = 8079
version: str = '1.23.7'
class weaviate.embedded.EmbeddedV3(options: EmbeddedOptions)[source]

Bases: _EmbeddedBase

is_listening() bool[source]
start() None[source]
class weaviate.embedded.EmbeddedV4(options: EmbeddedOptions)[source]

Bases: _EmbeddedBase

is_listening() bool[source]
start() None[source]
weaviate.embedded.get_random_port() int[source]

weaviate.error_msgs module

Error and Warning messages that are reused throughout the code.

weaviate.exceptions module

Weaviate Exceptions.

exception weaviate.exceptions.AdditionalPropertiesError(additional_dict: str, additional_dataclass: str)[source]

Bases: WeaviateBaseError

Additional properties were provided multiple times.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

weaviate.exceptions.AdditionalPropertiesException

alias of AdditionalPropertiesError

exception weaviate.exceptions.AuthenticationFailedError(message: str = '')[source]

Bases: WeaviateBaseError

Authentication Failed Exception.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

weaviate.exceptions.AuthenticationFailedException

alias of AuthenticationFailedError

exception weaviate.exceptions.BackupFailedError(message: str = '')[source]

Bases: WeaviateBaseError

Backup Failed Exception.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

weaviate.exceptions.BackupFailedException

alias of BackupFailedError

exception weaviate.exceptions.EmptyResponseError(message: str = '')[source]

Bases: WeaviateBaseError

Occurs when an HTTP request unexpectedly returns an empty response

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

weaviate.exceptions.EmptyResponseException

alias of EmptyResponseError

exception weaviate.exceptions.InvalidDataModelError(type_: str)[source]

Bases: WeaviateBaseError

Is raised when the user provides a generic that is not supported

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

weaviate.exceptions.InvalidDataModelException

alias of InvalidDataModelError

exception weaviate.exceptions.MissingScopeError(message: str = '')[source]

Bases: WeaviateBaseError

Scope was not provided with client credential flow.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

weaviate.exceptions.MissingScopeException

alias of MissingScopeError

exception weaviate.exceptions.ObjectAlreadyExistsError(message: str = '')[source]

Bases: WeaviateBaseError

Object Already Exists Exception.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

weaviate.exceptions.ObjectAlreadyExistsException

alias of ObjectAlreadyExistsError

exception weaviate.exceptions.ResponseCannotBeDecodedError(location: str, response: Response | Response)[source]

Bases: WeaviateBaseError

Raised when a weaviate response cannot be decoded to json

Arguments:
location:

From which code path the exception was raised.

response:

The request response of which the status code was unexpected.

property status_code: int
weaviate.exceptions.ResponseCannotBeDecodedException

alias of ResponseCannotBeDecodedError

exception weaviate.exceptions.SchemaValidationError(message: str = '')[source]

Bases: WeaviateBaseError

Schema Validation Exception.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

weaviate.exceptions.SchemaValidationException

alias of SchemaValidationError

exception weaviate.exceptions.UnexpectedStatusCodeError(message: str, response: Response | Response)[source]

Bases: WeaviateBaseError

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

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

Arguments:
message:

An error message specific to the context, in which the error occurred.

response:

The request response of which the status code was unexpected.

property status_code: int
weaviate.exceptions.UnexpectedStatusCodeException

alias of UnexpectedStatusCodeError

exception weaviate.exceptions.WeaviateAddInvalidPropertyError(message: str)[source]

Bases: WeaviateBaseError

Is raised when adding an invalid new property.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

exception weaviate.exceptions.WeaviateBaseError(message: str = '')[source]

Bases: Exception

Weaviate base exception that all Weaviate exceptions should inherit from.

This error can be used to catch any Weaviate exceptions.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

exception weaviate.exceptions.WeaviateBatchError(message: str)[source]

Bases: WeaviateQueryError

Is raised if a gRPC batch query to Weaviate fails in any way.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

exception weaviate.exceptions.WeaviateBatchValidationError(message: str)[source]

Bases: WeaviateBaseError

Is raised when a batch validation error occurs.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

exception weaviate.exceptions.WeaviateClosedClientError[source]

Bases: WeaviateBaseError

Is raised when a client is closed and a method is called on it.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

exception weaviate.exceptions.WeaviateConnectionError(message: str = '')[source]

Bases: WeaviateBaseError

Is raised when the connection to Weaviate fails.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

exception weaviate.exceptions.WeaviateDeleteManyError(message: str)[source]

Bases: WeaviateQueryError

Is raised if a gRPC delete many request to Weaviate fails in any way.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

exception weaviate.exceptions.WeaviateEmbeddedInvalidVersionError(url: str)[source]

Bases: WeaviateBaseError

Invalid version provided to Weaviate embedded.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

weaviate.exceptions.WeaviateEmbeddedInvalidVersionException

alias of WeaviateEmbeddedInvalidVersionError

exception weaviate.exceptions.WeaviateGRPCUnavailableError(weaviate_version: str = '')[source]

Bases: WeaviateBaseError

Is raised when a gRPC-backed query is made with no gRPC connection present.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

weaviate.exceptions.WeaviateGrpcUnavailable

alias of WeaviateGRPCUnavailableError

exception weaviate.exceptions.WeaviateInsertInvalidPropertyError(data: dict)[source]

Bases: WeaviateBaseError

Is raised when inserting an invalid property.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

exception weaviate.exceptions.WeaviateInsertManyAllFailedError(message: str = '')[source]

Bases: WeaviateBaseError

Is raised when all objects fail to be inserted.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

exception weaviate.exceptions.WeaviateInvalidInputError(message: str)[source]

Bases: WeaviateBaseError

Is raised if the input to a function is invalid.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

weaviate.exceptions.WeaviateInvalidInputException

alias of WeaviateInvalidInputError

exception weaviate.exceptions.WeaviateQueryError(message: str, protocol_type: str)[source]

Bases: WeaviateBaseError

Is raised if a query (either gRPC or GraphQL) to Weaviate fails in any way.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

weaviate.exceptions.WeaviateQueryException

alias of WeaviateQueryError

exception weaviate.exceptions.WeaviateStartUpError(message: str = '')[source]

Bases: WeaviateBaseError

Is raised if weaviate is not available on the given url+port.

Weaviate base exception initializer.

Arguments:
message:

An error message specific to the context in which the error occurred.

weaviate.types module

weaviate.util module

Helper functions!

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

Bases: Enum

class weaviate.util.MetaEnum(cls, bases, classdict, *, boundary=None, _simple=False, **kwds)[source]

Bases: EnumType

weaviate.util.check_batch_result(results: List[Dict[str, Any]] | None) None[source]

Check batch results for errors.

Parameters

resultsdict

The Weaviate batch creation return value.

weaviate.util.file_decoder_b64(encoded_file: str) bytes[source]

Decode file from a Weaviate format image.

Parameters

encoded_filestr

The encoded file.

Returns

bytes

Decoded file as a binary string. Use this in your file handling code to convert it into a specific file type of choice. E.g., PIL for images.

weaviate.util.file_encoder_b64(file_or_file_path: str | Path | BufferedReader) str[source]

Encode a file in a Weaviate understandable format from an io.BufferedReader binary read file or by providing the file path as either a string of a pathlib.Path object

If you pass an io.BufferedReader object, it is your responsibility to close it after encoding.

Parameters

file_or_file_pathstr, pathlib.Path io.BufferedReader

The binary read file or the path to the file.

Returns

str

Encoded file.

Raises

ValueError

If the argument is str and does not point to an existing file.

TypeError

If the argument is of a wrong data type.

weaviate.util.generate_local_beacon(to_uuid: str | UUID, class_name: str | None = None) dict[source]

Generates a beacon with the given uuid and class name (only for Weaviate >= 1.14.0).

Parameters

to_uuidstr or uuid.UUID

The UUID for which to create a local beacon.

class_nameOptional[str], optional

The class name of the to_uuid object. Used with Weaviate >= 1.14.0. For Weaviate < 1.14.0 use None value.

Returns

dict

The local beacon.

Raises

TypeError

If ‘to_uuid’ is not of type str.

ValueError

If the ‘to_uuid’ is not valid.

weaviate.util.generate_uuid5(identifier: Any, namespace: Any = '') str[source]

Generate an UUIDv5, may be used to consistently generate the same UUID for a specific identifier and namespace.

Parameters

identifierAny

The identifier/object that should be used as basis for the UUID.

namespaceAny, optional

Allows to namespace the identifier, by default “”

Returns

str

The UUID as a string.

weaviate.util.get_domain_from_weaviate_url(url: str) str[source]

Get the domain from a weaviate URL.

Parameters

urlstr

The weaviate URL. Of this form: ‘weaviate://localhost/objects/28f3f61b-b524-45e0-9bbe-2c1550bf73d2’

Returns

str

The domain.

weaviate.util.get_valid_uuid(uuid: str | UUID) str[source]

Validate and extract the UUID.

Parameters

uuidstr or uuid.UUID

The UUID to be validated and extracted. Should be in the form of an UUID or in form of an URL (weaviate ‘beacon’ or ‘href’). E.g. ‘http://localhost:8080/v1/objects/fc7eb129-f138-457f-b727-1b29db191a67’ or ‘weaviate://localhost/28f3f61b-b524-45e0-9bbe-2c1550bf73d2’ or ‘fc7eb129-f138-457f-b727-1b29db191a67’

Returns

str

The extracted UUID.

Raises

TypeError

If ‘uuid’ is not of type str.

ValueError

If ‘uuid’ is not valid or cannot be extracted.

weaviate.util.get_vector(vector: Sequence) List[float][source]

Get weaviate compatible format of the embedding vector.

Parameters

vector: Sequence

The embedding of an object. Used only for class objects that do not have a vectorization module. Supported types are list, numpy.ndarray, torch.Tensor, tf.Tensor, pd.Series and pl.Series.

Returns

list

The embedding as a list.

Raises

TypeError

If ‘vector’ is not of a supported type.

weaviate.util.image_decoder_b64(encoded_image: str) bytes[source]

Decode image from a Weaviate format image.

Parameters

encoded_imagestr

The encoded image.

Returns

bytes

Decoded image as a binary string.

weaviate.util.image_encoder_b64(image_or_image_path: str | BufferedReader) str[source]

Encode a image in a Weaviate understandable format from a binary read file or by providing the image path.

Parameters

image_or_image_pathstr, io.BufferedReader

The binary read file or the path to the file.

Returns

str

Encoded image.

Raises

ValueError

If the argument is str and does not point to an existing file.

TypeError

If the argument is of a wrong data type.

weaviate.util.is_object_url(url: str) bool[source]

Validates an url like ‘http://localhost:8080/v1/objects/1c9cd584-88fe-5010-83d0-017cb3fcb446’ or ‘/v1/objects/1c9cd584-88fe-5010-83d0-017cb3fcb446’ references a object. It only validates the path format and UUID, not the host or the protocol.

Parameters

urlstr

The URL to be validated.

Returns

bool

True if the ‘url’ is a valid path to an object. False otherwise.

weaviate.util.is_weaviate_client_too_old(current_version_str: str, latest_version_str: str) bool[source]

Check if the user should be gently nudged to upgrade their Weaviate client version.

Parameters

current_version_strstr

The version of the Weaviate client that is being used (e.g. “v1.18.2” or “1.18.0”)

latest_version_strstr

The latest version of the Weaviate client to compare against (e.g. “v1.18.2” or “1.18.0”)

Returns

bool : True if the user should be nudged to upgrade. False if the user is using a valid version or if the version could not be parsed.

weaviate.util.is_weaviate_domain(url: str) bool[source]
weaviate.util.is_weaviate_object_url(url: str) bool[source]

Checks if the input follows a normal Weaviate ‘beacon’ like this: ‘weaviate://localhost/ClassName/28f3f61b-b524-45e0-9bbe-2c1550bf73d2’

Parameters

urlstr

The URL to be validated.

Returns

bool

True if the ‘url’ is a Weaviate object URL. False otherwise.

weaviate.util.is_weaviate_too_old(current_version_str: str) bool[source]

Check if the user should be gently nudged to upgrade their Weaviate server version.

Parameters

current_version_strstr

The version of the Weaviate server that the client is connected to. (e.g. “v1.18.2” or “1.18.0”)

Returns

bool : True if the user should be nudged to upgrade.

weaviate.util.parse_version_string(ver_str: str) tuple[source]

Parse a version string into a float.

Parameters

ver_strstr

The version string to parse. (e.g. “v1.18.2” or “1.18.0”)

Returns

tuple :

The parsed version as a tuple with len(2). (e.g. (1, 18)) Note: Ignores the patch version.

weaviate.util.strip_newlines(s: str) str[source]

weaviate.warnings module