Weaviate Packages

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

weaviate.BatchClient: alias of _BatchClient

class weaviate.Client(**kwargs)[source]

Bases: object

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.

get_meta() → dict[source]

Get the meta endpoint description of weaviate.

Returns:

dict: The dict describing the weaviate configuration.

Raises:

weaviate.UnexpectedStatusCodeError: If Weaviate reports a none OK status.

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

Get the openid-configuration.

Returns

dict: The configuration or None if not configured.

Raises

weaviate.UnexpectedStatusCodeError: If Weaviate reports a none OK status.

is_live() → bool[source]

Ping Weaviate’s live state.

Returns:

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

is_ready() → bool[source]

Ping Weaviate’s ready state

Returns:

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

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.

Bases: _WeaviateClientBase

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.
cluster: A Cluster object instance connected to the same Weaviate instance as the Client.
collections: A _CollectionsAsync object instance connected to the same Weaviate instance as the Client.

Initialise a WeaviateClient/WeaviateClientAsync 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.

To simplify connections to Weaviate Cloud or local instances, use the weaviate.connect_to_weaviate_cloud or weaviate.connect_to_local helper functions.

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 headers to include in the requests.
  
  Can be used to set OpenAI/HuggingFace/Cohere etc. keys.
  
  [Here](https://weaviate.io/developers/weaviate/modules/reader-generator-modules/generative-openai#providing-the-key-to-weaviate) is an
  
  example of how to set API keys within this parameter.
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.

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 await client.collections.create(“MyCollection”, …).

Bases: _WeaviateClientBase

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/WeaviateClientAsync 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.

To simplify connections to Weaviate Cloud or local instances, use the weaviate.connect_to_weaviate_cloud or weaviate.connect_to_local helper functions.

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 headers to include in the requests.
  
  Can be used to set OpenAI/HuggingFace/Cohere etc. keys.
  
  [Here](https://weaviate.io/developers/weaviate/modules/reader-generator-modules/generative-openai#providing-the-key-to-weaviate) is an
  
  example of how to set API keys within this parameter.
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

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

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.

get_meta() → dict

Get the meta endpoint description of weaviate.

Returns:

dict: The dict describing the weaviate configuration.

Raises:

weaviate.UnexpectedStatusCodeError: If Weaviate reports a none OK status.

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

Get the openid-configuration.

Returns

dict: The configuration or None if not configured.

Raises

weaviate.UnexpectedStatusCodeError: If Weaviate reports a none OK status.

graphql_raw_query(gql_query: str) → _RawGQLReturn

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_live() → bool

is_ready() → bool

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 instance 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:

>>> ################## Without Context Manager #############################
>>> 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.26.1', 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:

>>> ################## Without Context Manager #############################
>>> 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.

Connect to a Weaviate Cloud (WCD) instance. This method is deprecated and will be removed in a future release. Use connect_to_weaviate_cloud instead.

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

Connect to a Weaviate Cloud (WCD) 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 WCD 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:

>>> ################## Without Context Manager #############################
>>> import weaviate
>>> client = weaviate.connect_to_weaviate_cloud(
...     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_weaviate_cloud(
...     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.

weaviate.use_async_with_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) → WeaviateAsyncClient[source]

Create an async client object ready to connect to a Weaviate instance with custom connection parameters.

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

This method handles creating the WeaviateAsyncClient instance with relevant options to Weaviate Cloud connections but you must manually call await client.connect(). 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 an async with statement, which will automatically open/close the connection when the context is entered/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:

>>> ################## Without Context Manager #############################
>>> import weaviate
>>> client = weaviate.use_async_with_custom(
...     http_host="localhost",
...     http_port=8080,
...     http_secure=False,
...     grpc_host="localhost",
...     grpc_port=50051,
...     grpc_secure=False,
... )
>>> await client.is_ready()
False # The connection is not ready yet, you must call `await client.connect()` to connect.
... await client.connect()
>>> await client.is_ready()
True
>>> await client.close() # Close the connection when you are done with it.
>>> ################## Async With Context Manager #############################
>>> import weaviate
>>> async with weaviate.use_async_with_custom(
...     http_host="localhost",
...     http_port=8080,
...     http_secure=False,
...     grpc_host="localhost",
...     grpc_port=50051,
...     grpc_secure=False,
... ) as client:
...     await client.is_ready()
True
>>> # The connection is automatically closed when the context is exited.

weaviate.use_async_with_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.26.1', persistence_data_path: str | None = None, binary_path: str | None = None, environment_variables: Dict[str, str] | None = None) → WeaviateAsyncClient[source]

Create an async client object ready to connect to an embedded Weaviate instance.

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

This method handles creating the WeaviateAsyncClient instance with relevant options to Weaviate Cloud connections but you must manually call await client.connect(). 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 an async with statement, which will automatically open/close the connection when the context is entered/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.use_async_with_embedded(
...     port=8080,
...     grpc_port=50051,
... )
>>> await client.is_ready()
False # The connection is not ready yet, you must call `await client.connect()` to connect.
... await client.connect()
>>> await client.is_ready()
True
################## With Context Manager #############################
>>> import weaviate
>>> async with weaviate.use_async_with_embedded(
...     port=8080,
...     grpc_port=50051,
... ) as client:
...     await client.is_ready()
True
>>> # The connection is automatically closed when the context is exited.

weaviate.use_async_with_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) → WeaviateAsyncClient[source]

Create an async client object ready to connect to a local Weaviate instance deployed using Docker compose with standard port configurations.

This method handles creating the WeaviateAsyncClient instance with relevant options to Weaviate Cloud connections but you must manually call await client.connect(). 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 an async with statement, which will automatically open/close the connection when the context is entered/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.WeaviateAsyncClient: The async client ready to connect to the cluster with the required parameters set appropriately.

Examples:

>>> ################## Without Context Manager #############################
>>> import weaviate
>>> client = weaviate.use_async_with_local(
...     host="localhost",
...     port=8080,
...     grpc_port=50051,
... )
>>> await client.is_ready()
False # The connection is not ready yet, you must call `await client.connect()` to connect.
... await client.connect()
>>> await client.is_ready()
True
>>> await client.close() # Close the connection when you are done with it.
>>> ################## With Context Manager #############################
>>> import weaviate
>>> async with weaviate.use_async_with_local(
...     host="localhost",
...     port=8080,
...     grpc_port=50051,
... ) as client:
...     await client.is_ready()
True
>>> # The connection is automatically closed when the context is exited.

weaviate.use_async_with_weaviate_cloud(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) → WeaviateAsyncClient[source]

Create an async client object ready to connect to a Weaviate Cloud (WCD) instance.

This method handles creating the WeaviateAsyncClient instance with relevant options to Weaviate Cloud connections but you must manually call await client.connect(). 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 an async with statement, which will automatically open/close the connection when the context is entered/exited. See the examples below for details.

Arguments:

cluster_url: The WCD 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.WeaviateAsyncClient: The async client ready to connect to the cluster with the required parameters set appropriately.

Examples:

>>> ################## Without Context Manager #############################
>>> import weaviate
>>> client = weaviate.use_async_with_weaviate_cloud(
...     cluster_url="rAnD0mD1g1t5.something.weaviate.cloud",
...     auth_credentials=weaviate.classes.init.Auth.api_key("my-api-key"),
... )
>>> await client.is_ready()
False # The connection is not ready yet, you must call `await client.connect()` to connect.
... await client.connect()
>>> await client.is_ready()
True
>>> await client.close() # Close the connection when you are done with it.
>>> ################## With Context Manager #############################
>>> import weaviate
>>> async with weaviate.use_async_with_weaviate_cloud(
...     cluster_url="rAnD0mD1g1t5.something.weaviate.cloud",
...     auth_credentials=weaviate.classes.init.Auth.api_key("my-api-key"),
... ) as client:
...     await client.is_ready()
True

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(**kwargs)[source]

Bases: object

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.

get_meta() → dict[source]

Get the meta endpoint description of weaviate.

Returns:

dict: The dict describing the weaviate configuration.

Raises:

weaviate.UnexpectedStatusCodeError: If Weaviate reports a none OK status.

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

Get the openid-configuration.

Returns

dict: The configuration or None if not configured.

Raises

weaviate.UnexpectedStatusCodeError: If Weaviate reports a none OK status.

is_live() → bool[source]

Ping Weaviate’s live state.

Returns:

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

is_ready() → bool[source]

Ping Weaviate’s ready state

Returns:

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

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.

Bases: _WeaviateClientBase

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.
cluster: A Cluster object instance connected to the same Weaviate instance as the Client.
collections: A _CollectionsAsync object instance connected to the same Weaviate instance as the Client.

Initialise a WeaviateClient/WeaviateClientAsync 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.

To simplify connections to Weaviate Cloud or local instances, use the weaviate.connect_to_weaviate_cloud or weaviate.connect_to_local helper functions.

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 headers to include in the requests.
  
  Can be used to set OpenAI/HuggingFace/Cohere etc. keys.
  
  [Here](https://weaviate.io/developers/weaviate/modules/reader-generator-modules/generative-openai#providing-the-key-to-weaviate) is an
  
  example of how to set API keys within this parameter.
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.

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 await client.collections.create(“MyCollection”, …).

Bases: _WeaviateClientBase

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/WeaviateClientAsync 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.

To simplify connections to Weaviate Cloud or local instances, use the weaviate.connect_to_weaviate_cloud or weaviate.connect_to_local helper functions.

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 headers to include in the requests.
  
  Can be used to set OpenAI/HuggingFace/Cohere etc. keys.
  
  [Here](https://weaviate.io/developers/weaviate/modules/reader-generator-modules/generative-openai#providing-the-key-to-weaviate) is an
  
  example of how to set API keys within this parameter.
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

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

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.

get_meta() → dict

Get the meta endpoint description of weaviate.

Returns:

dict: The dict describing the weaviate configuration.

Raises:

weaviate.UnexpectedStatusCodeError: If Weaviate reports a none OK status.

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

Get the openid-configuration.

Returns

dict: The configuration or None if not configured.

Raises

weaviate.UnexpectedStatusCodeError: If Weaviate reports a none OK status.

graphql_raw_query(gql_query: str) → _RawGQLReturn

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_live() → bool

is_ready() → bool

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.

__init__ uses __pydantic_self__ instead of the more common self for the first arg 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.

__init__ uses __pydantic_self__ instead of the more common self for the first arg 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.

__init__ uses __pydantic_self__ instead of the more common self for the first arg to allow self as a field name.

field init: int | float = 2

Constraints:

ge = 0

field insert: int | float = 90

Constraints:

ge = 0

field query: int | float = 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.26.1', 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.26.1'

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.

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 = '', grpc_address: Tuple[str, int] = ('not provided', 0))[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.

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

Bases: WeaviateBaseError

Is raised when a request to Weaviate times out.

Weaviate base exception initializer.

Arguments:

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

exception weaviate.exceptions.WeaviateUnsupportedFeatureError(feature: str, current: str, minimum: str)[source]

Bases: WeaviateBaseError

Is raised when a client method tries to use a new feature with an old Weaviate version.

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!

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 Packages

Attributes

Arguments:

Raises:

Parameters

Returns

Subpackages

Submodules

weaviate.auth module

weaviate.classes module

weaviate.client module

Attributes

Arguments:

Raises:

Parameters

Returns

weaviate.config module

weaviate.embedded module

weaviate.error_msgs module

weaviate.exceptions module

weaviate.types module

weaviate.util module

Parameters

Parameters

Returns

Parameters

Returns

Raises

Parameters

Returns

Raises

Parameters

Returns

Parameters

Returns

Parameters

Returns

Raises

Parameters

Returns

Raises

Parameters

Returns

Parameters

Returns

Raises

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

weaviate.warnings module