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

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”, …).

roles: This namespace contains all functionality to manage Weaviate’s RBAC functionality.

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.6', 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.6', 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

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”, …).

roles: This namespace contains all functionality to manage Weaviate’s RBAC functionality.

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.

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, session_pool_timeout: int = 5)[source]

Bases: object

session_pool_connections: int = 20

session_pool_max_retries: int = 3

session_pool_maxsize: int = 100

session_pool_timeout: int = 5

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 | 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.6', 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.6'

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.exceptions module

Weaviate Exceptions.

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

Weaviate Packages

Subpackages

Submodules

weaviate.auth module

weaviate.classes module

weaviate.client module

weaviate.config module

weaviate.embedded module

weaviate.exceptions module

weaviate.types module

weaviate.util module

Parameters

Parameters

Returns

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