weaviate

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

class weaviate.WeaviateClient(connection_params=None, embedded_options=None, auth_client_secret=None, additional_headers=None, additional_config=None, skip_init_checks=False)[source]

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.

backup

Backup object instance connected to the same Weaviate instance as the Client. This namespace contains all the functionality to upload data in batches to Weaviate for all collections and tenants.

Type:

_Backup

batch

BatchClient object instance connected to the same Weaviate instance as the Client. This namespace contains all functionality to backup data.

Type:

_BatchClientWrapper

cluster

Cluster object instance connected to the same Weaviate instance as the Client. This namespace contains all functionality to inspect the connected Weaviate cluster.

Type:

_Cluster

collections

Collections object instance connected to the same Weaviate instance as the Client. 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”, …).

Type:

_Collections

debug

Debug object instance connected to the same Weaviate instance as the Client. This namespace contains functionality used to debug Weaviate clusters. As such, it is deemed experimental and is subject to change. We can make no guarantees about the stability of this namespace nor the potential for future breaking changes. Use at your own risk.

Type:

_Debug

roles

Roles object instance connected to the same Weaviate instance as the Client. This namespace contains all functionality to manage Weaviate’s RBAC functionality.

Type:

_Roles

users

Users object instance connected to the same Weaviate instance as the Client. This namespace contains all functionality to manage Weaviate users.

Type:

_Users

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

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

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

Parameters:

  • connection_params (ConnectionParams | None) – The connection parameters to use for the underlying HTTP requests.

  • embedded_options (EmbeddedOptions | None) – The options to use when provisioning an embedded Weaviate instance.

  • auth_client_secret (_BearerToken | _ClientPassword | _ClientCredentials | _APIKey | None) – 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 | None) – Additional headers to include in the requests. Can be used to set OpenAI/HuggingFace/Cohere etc. keys. Here is an example of how to set API keys within this parameter.

  • additional_config (AdditionalConfig | None) – Additional and advanced configuration options for Weaviate.

  • skip_init_checks (bool) – 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.

close()

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.

Return type:

None | Awaitable[None]

connect()

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:
Return type:

None | Awaitable[None]

get_meta()

Get the meta endpoint description of weaviate.

Returns:

The dict describing the weaviate configuration.

Raises:

UnexpectedStatusCodeError – If Weaviate reports a none OK status.

Return type:

dict | Awaitable[dict]

get_open_id_configuration()

Get the openid-configuration.

Returns:

The configuration or None if not configured.

Raises:

UnexpectedStatusCodeError – If Weaviate reports a none OK status.

Return type:

Dict[str, Any] | None | Awaitable[Dict[str, Any] | None]

graphql_raw_query(gql_query)

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.

Parameters:

gql_query (str) – GraphQL query as a string.

Returns:

A dict with the response from the GraphQL query.

Raises:
Return type:

_RawGQLReturn | Awaitable[_RawGQLReturn]

is_connected()

Check if the client is connected to Weaviate.

Returns:

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

Return type:

bool

is_live()
Return type:

bool | Awaitable[bool]

is_ready()
Return type:

bool | Awaitable[bool]

class weaviate.WeaviateAsyncClient(connection_params=None, embedded_options=None, auth_client_secret=None, additional_headers=None, additional_config=None, skip_init_checks=False)[source]

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.

backup

Backup object instance connected to the same Weaviate instance as the Client. This namespace contains all the functionality to upload data in batches to Weaviate for all collections and tenants.

Type:

_BackupAsync

cluster

Cluster object instance connected to the same Weaviate instance as the Client. This namespace contains all functionality to inspect the connected Weaviate cluster.

Type:

_ClusterAsync

collections

Collections object instance connected to the same Weaviate instance as the Client. 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”, …).

Type:

_CollectionsAsync

debug

Debug object instance connected to the same Weaviate instance as the Client. This namespace contains functionality used to debug Weaviate clusters. As such, it is deemed experimental and is subject to change. We can make no guarantees about the stability of this namespace nor the potential for future breaking changes. Use at your own risk.

Type:

_DebugAsync

roles

Roles object instance connected to the same Weaviate instance as the Client. This namespace contains all functionality to manage Weaviate’s RBAC functionality.

Type:

_RolesAsync

users

Users object instance connected to the same Weaviate instance as the Client. This namespace contains all functionality to manage Weaviate users.

Type:

_UsersAsync

Initialise a WeaviateAsyncClient 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.use_async_with_weaviate_cloud() or weaviate.use_async_with_local() helper functions.

Parameters:

  • connection_params (ConnectionParams | None) – The connection parameters to use for the underlying HTTP requests.

  • embedded_options (EmbeddedOptions | None) – The options to use when provisioning an embedded Weaviate instance.

  • auth_client_secret (_BearerToken | _ClientPassword | _ClientCredentials | _APIKey | None) – 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 | None) –

    Additional headers to include in the requests. Can be used to set OpenAI/HuggingFace/Cohere etc. keys. Here is an example of how to set API keys within this parameter.

  • additional_config (AdditionalConfig | None) – Additional and advanced configuration options for Weaviate.

  • skip_init_checks (bool) – 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.

close()

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.

Return type:

None | Awaitable[None]

connect()

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:
Return type:

None | Awaitable[None]

get_meta()

Get the meta endpoint description of weaviate.

Returns:

The dict describing the weaviate configuration.

Raises:

UnexpectedStatusCodeError – If Weaviate reports a none OK status.

Return type:

dict | Awaitable[dict]

get_open_id_configuration()

Get the openid-configuration.

Returns:

The configuration or None if not configured.

Raises:

UnexpectedStatusCodeError – If Weaviate reports a none OK status.

Return type:

Dict[str, Any] | None | Awaitable[Dict[str, Any] | None]

graphql_raw_query(gql_query)

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.

Parameters:

gql_query (str) – GraphQL query as a string.

Returns:

A dict with the response from the GraphQL query.

Raises:
Return type:

_RawGQLReturn | Awaitable[_RawGQLReturn]

is_connected()

Check if the client is connected to Weaviate.

Returns:

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

Return type:

bool

is_live()
Return type:

bool | Awaitable[bool]

is_ready()
Return type:

bool | Awaitable[bool]

weaviate.connect_to_custom(http_host, http_port, http_secure, grpc_host, grpc_port, grpc_secure, headers=None, additional_config=None, auth_credentials=None, skip_init_checks=False)[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.

Parameters:

  • http_host (str) – The host to use for the underlying REST and GraphQL API calls.

  • http_port (int) – The port to use for the underlying REST and GraphQL API calls.

  • http_secure (bool) – Whether to use https for the underlying REST and GraphQL API calls.

  • grpc_host (str) – The host to use for the underlying gRPC API.

  • grpc_port (int) – The port to use for the underlying gRPC API.

  • grpc_secure (bool) – Whether to use a secure channel for the underlying gRPC API.

  • headers (Dict[str, str] | None) – Additional headers to include in the requests, e.g. API keys for Cloud vectorization.

  • additional_config (AdditionalConfig | None) – This includes many additional, rarely used config options. use wvc.init.AdditionalConfig() to configure.

  • auth_credentials (_BearerToken | _ClientPassword | _ClientCredentials | _APIKey | None) – 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 (bool) – Whether to skip the initialization checks when connecting to Weaviate.

Returns:

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

Return type:

WeaviateClient

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='127.0.0.1', port=8079, grpc_port=50050, headers=None, additional_config=None, version='1.26.6', persistence_data_path=None, binary_path=None, environment_variables=None)[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 for more details.

Parameters:

  • hostname (str) – The hostname to use for the underlying REST & GraphQL API calls.

  • port (int) – The port to use for the underlying REST and GraphQL API calls.

  • grpc_port (int) – The port to use for the underlying gRPC API.

  • headers (Dict[str, str] | None) – Additional headers to include in the requests, e.g. API keys for Cloud vectorization.

  • additional_config (AdditionalConfig | None) – This includes many additional, rarely used config options. use wvc.init.AdditionalConfig() to configure.

  • version (str) – Weaviate version to be used for the embedded instance.

  • persistence_data_path (str | None) – 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 (str | None) – 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 (Dict[str, str] | None) – Additional environment variables to be passed to the embedded instance for configuration.

Returns:

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

Return type:

WeaviateClient

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='localhost', port=8080, grpc_port=50051, headers=None, additional_config=None, skip_init_checks=False, auth_credentials=None)[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.

Parameters:

  • host (str) – The host to use for the underlying REST and GraphQL API calls.

  • port (int) – The port to use for the underlying REST and GraphQL API calls.

  • grpc_port (int) – The port to use for the underlying gRPC API.

  • headers (Dict[str, str] | None) – Additional headers to include in the requests, e.g. API keys for Cloud vectorization.

  • additional_config (AdditionalConfig | None) – This includes many additional, rarely used config options. use wvc.init.AdditionalConfig() to configure.

  • skip_init_checks (bool) – Whether to skip the initialization checks when connecting to Weaviate.

  • auth_credentials (_BearerToken | _ClientPassword | _ClientCredentials | _APIKey | None) – 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().

Return type:

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.
weaviate.connect_to_wcs(cluster_url, auth_credentials, headers=None, additional_config=None, skip_init_checks=False)[source]

Deprecated since version 4.6.2.

This method is deprecated and will be removed in a future release. Use connect_to_weaviate_cloud() instead.

Parameters:
Return type:

WeaviateClient

weaviate.connect_to_weaviate_cloud(cluster_url, auth_credentials, headers=None, additional_config=None, skip_init_checks=False)[source]

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.

Parameters:

  • cluster_url (str) – The WCD cluster URL or hostname to connect to. Usually in the form: rAnD0mD1g1t5.something.weaviate.cloud

  • auth_credentials (_BearerToken | _ClientPassword | _ClientCredentials | _APIKey | None) – 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 (Dict[str, str] | None) – Additional headers to include in the requests, e.g. API keys for third-party Cloud vectorization.

  • additional_config (AdditionalConfig | None) – This includes many additional, rarely used config options. use wvc.init.AdditionalConfig() to configure.

  • skip_init_checks (bool) – Whether to skip the initialization checks when connecting to Weaviate.

Returns:

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

Return type:

WeaviateClient

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, http_port, http_secure, grpc_host, grpc_port, grpc_secure, headers=None, additional_config=None, auth_credentials=None, skip_init_checks=False)[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.

Parameters:

  • http_host (str) – The host to use for the underlying REST and GraphQL API calls.

  • http_port (int) – The port to use for the underlying REST and GraphQL API calls.

  • http_secure (bool) – Whether to use https for the underlying REST and GraphQL API calls.

  • grpc_host (str) – The host to use for the underlying gRPC API.

  • grpc_port (int) – The port to use for the underlying gRPC API.

  • grpc_secure (bool) – Whether to use a secure channel for the underlying gRPC API.

  • headers (Dict[str, str] | None) – Additional headers to include in the requests, e.g. API keys for Cloud vectorization.

  • additional_config (AdditionalConfig | None) – This includes many additional, rarely used config options. use wvc.init.AdditionalConfig() to configure.

  • auth_credentials (_BearerToken | _ClientPassword | _ClientCredentials | _APIKey | None) – 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 (bool) – Whether to skip the initialization checks when connecting to Weaviate.

Returns:

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

Return type:

WeaviateAsyncClient

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='127.0.0.1', port=8079, grpc_port=50050, headers=None, additional_config=None, version='1.26.6', persistence_data_path=None, binary_path=None, environment_variables=None)[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 for more details.

Parameters:

  • hostname (str) – The hostname to use for the underlying REST & GraphQL API calls.

  • port (int) – The port to use for the underlying REST and GraphQL API calls.

  • grpc_port (int) – The port to use for the underlying gRPC API.

  • headers (Dict[str, str] | None) – Additional headers to include in the requests, e.g. API keys for Cloud vectorization.

  • additional_config (AdditionalConfig | None) – This includes many additional, rarely used config options. use wvc.init.AdditionalConfig() to configure.

  • version (str) – Weaviate version to be used for the embedded instance.

  • persistence_data_path (str | None) – 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 (str | None) – 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 (Dict[str, str] | None) – Additional environment variables to be passed to the embedded instance for configuration.

Returns:

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

Return type:

WeaviateAsyncClient

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='localhost', port=8080, grpc_port=50051, headers=None, additional_config=None, skip_init_checks=False, auth_credentials=None)[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.

Parameters:

  • host (str) – The host to use for the underlying REST and GraphQL API calls.

  • port (int) – The port to use for the underlying REST and GraphQL API calls.

  • grpc_port (int) – The port to use for the underlying gRPC API.

  • headers (Dict[str, str] | None) – Additional headers to include in the requests, e.g. API keys for Cloud vectorization.

  • additional_config (AdditionalConfig | None) – This includes many additional, rarely used config options. use wvc.init.AdditionalConfig() to configure.

  • skip_init_checks (bool) – Whether to skip the initialization checks when connecting to Weaviate.

  • auth_credentials (_BearerToken | _ClientPassword | _ClientCredentials | _APIKey | None) – 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:

The async client ready to connect to the cluster with the required parameters set appropriately.

Return type:

WeaviateAsyncClient

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, auth_credentials, headers=None, additional_config=None, skip_init_checks=False)[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.

Parameters:

  • cluster_url (str) – The WCD cluster URL or hostname to connect to. Usually in the form: rAnD0mD1g1t5.something.weaviate.cloud

  • auth_credentials (_BearerToken | _ClientPassword | _ClientCredentials | _APIKey | None) – 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 (Dict[str, str] | None) – Additional headers to include in the requests, e.g. API keys for third-party Cloud vectorization.

  • additional_config (AdditionalConfig | None) – This includes many additional, rarely used config options. use wvc.init.AdditionalConfig() to configure.

  • skip_init_checks (bool) – Whether to skip the initialization checks when connecting to Weaviate.

Returns:

The async client ready to connect to the cluster with the required parameters set appropriately.

Return type:

WeaviateAsyncClient

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

weaviate.auth

Authentication class definitions.

class weaviate.auth._ClientCredentials(client_secret, scope=None)[source]

Authenticate for the Client Credential flow using client secrets.

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

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

  • space separated string: “scope1 scope2”

Parameters:

  • client_secret (str)

  • scope (str | List[str] | None)

client_secret: str
scope: str | List[str] | None = None
class weaviate.auth._ClientPassword(username, password, scope=None)[source]

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

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

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

  • space separated string: “scope1 scope2”

Parameters:

  • username (str)

  • password (str)

  • scope (str | List[str] | None)

username: str
password: str
scope: str | List[str] | None = None
class weaviate.auth._BearerToken(access_token, expires_in=60, refresh_token=None)[source]

Using a preexisting bearer/access token for authentication.

The expiration time of access tokens is given in seconds.

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

Parameters:

  • access_token (str)

  • expires_in (int)

  • refresh_token (str | None)

access_token: str
expires_in: int = 60
refresh_token: str | None = None
class weaviate.auth._APIKey(api_key)[source]

Using the given API key to authenticate with weaviate.

Parameters:

api_key (str)

api_key: str
class weaviate.auth.Auth[source]
static api_key(api_key)[source]
Parameters:

api_key (str)

Return type:

_APIKey

static client_credentials(client_secret, scope=None)[source]
Parameters:

  • client_secret (str)

  • scope (str | List[str] | None)

Return type:

_ClientCredentials

static client_password(username, password, scope=None)[source]
Parameters:

  • username (str)

  • password (str)

  • scope (str | List[str] | None)

Return type:

_ClientPassword

static bearer_token(access_token, expires_in=60, refresh_token=None)[source]
Parameters:

  • access_token (str)

  • expires_in (int)

  • refresh_token (str | None)

Return type:

_BearerToken

weaviate.auth.AuthApiKey

Deprecated since version 4.0.0: Use api_key() instead.

weaviate.auth.AuthBearerToken

Deprecated since version 4.0.0: Use bearer_token() instead.

weaviate.auth.AuthClientCredentials

Deprecated since version 4.0.0: Use client_credentials() instead.

weaviate.auth.AuthClientPassword

Deprecated since version 4.0.0: Use client_password() instead.

weaviate.config

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]
Parameters:

  • session_pool_connections (int)

  • session_pool_maxsize (int)

  • session_pool_max_retries (int)

  • session_pool_timeout (int)

session_pool_connections: int = 20
session_pool_maxsize: int = 100
session_pool_max_retries: int = 3
session_pool_timeout: int = 5
class weaviate.config.Config(grpc_port_experimental: Optional[int] = None, grpc_secure_experimental: bool = False, connection_config: weaviate.config.ConnectionConfig = <factory>)[source]
Parameters:

  • grpc_port_experimental (int | None)

  • grpc_secure_experimental (bool)

  • connection_config (ConnectionConfig)

grpc_port_experimental: int | None = None
grpc_secure_experimental: bool = False
connection_config: ConnectionConfig
pydantic model weaviate.config.Timeout[source]

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

pydantic model weaviate.config.Proxies[source]

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.AdditionalConfig[source]

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

weaviate.embedded

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]
Parameters:

  • persistence_data_path (str)

  • binary_path (str)

  • version (str)

  • port (int)

  • hostname (str)

  • additional_env_vars (Dict[str, str] | None)

  • grpc_port (int)

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
weaviate.embedded.get_random_port()[source]
Return type:

int

class weaviate.embedded.EmbeddedV3(options)[source]
Parameters:

options (EmbeddedOptions)

is_listening()[source]
Return type:

bool

start()[source]
Return type:

None

weaviate.embedded.EmbeddedDB

alias of EmbeddedV3

class weaviate.embedded.EmbeddedV4(options)[source]
Parameters:

options (EmbeddedOptions)

is_listening()[source]
Return type:

bool

start()[source]
Return type:

None