weaviate.client

Client class definition.

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

Bases: _ClientBase[Connection]

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

Attributes

backupweaviate.backup.Backup

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

batchweaviate.batch.Batch

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

classificationweaviate.classification.Classification

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

clusterweaviate.cluster.Cluster

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

contextionaryweaviate.contextionary.Contextionary

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

data_objectweaviate.data.DataObject

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

schemaweaviate.schema.Schema

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

queryweaviate.gql.Query

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

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

Arguments:

urlstr or None, optional

The connection string to the REST API of Weaviate.

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

Authenticate to weaviate by using one of the given authentication modes: - weaviate.auth.AuthBearerToken to use existing access and (optionally, but recommended) refresh tokens - weaviate.auth.AuthClientPassword to use username and password for oidc Resource Owner Password flow - weaviate.auth.AuthClientCredentials to use a client secret for oidc client credential flow

# fmt: on timeout_config : tuple(Real, Real) or Real, optional

Set the timeout configuration for all requests to the Weaviate server. It can be a real number or, a tuple of two real numbers: (connect timeout, read timeout). If only one real number is passed then both connect and read timeout will be set to that value, by default (2, 20).

proxiesdict, str or None, optional

Proxies to be used for requests. Are used by both ‘requests’ and ‘aiohttp’. Can be passed as a dict (‘requests’ format: https://docs.python-requests.org/en/stable/user/advanced/#proxies), str (HTTP/HTTPS protocols are going to use this proxy) or None. Default None.

trust_envbool, optional

Whether to read proxies from the ENV variables: (HTTP_PROXY or http_proxy, HTTPS_PROXY or https_proxy). Default False. NOTE: ‘proxies’ has priority over ‘trust_env’, i.e. if ‘proxies’ is NOT None, ‘trust_env’ is ignored.

additional_headersdict or None

Additional headers to include in the requests. Can be used to set OpenAI/HuggingFace keys. OpenAI/HuggingFace key looks like this:

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

by default None

startup_periodint or None

deprecated, has no effect

embedded_optionsweaviate.embedded.EmbeddedOptions or None, optional

Create an embedded Weaviate cluster inside the client - You can pass weaviate.embedded.EmbeddedOptions() with default values - Take a look at the attributes of weaviate.embedded.EmbeddedOptions to see what is configurable

additional_config: weaviate.Config, optional

Additional and advanced configuration options for weaviate.

Raises:

TypeError

If arguments are of a wrong data type.

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

Getter/setter for timeout_config.

Parameters

timeout_configtuple(float, float) or float, optional

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

(connect timeout, read timeout).

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

Returns

Tuple[float, float]

For Getter only: Requests Timeout configuration.

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

Bases: _ClientBase[ConnectionV4]

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

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

A Client instance creates all the needed objects to interact with Weaviate, and connects all of them to the same Weaviate instance. See below the Attributes of the Client instance. For the per attribute functionality see that attribute’s documentation.

Attributes:

backup

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

batch

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

classification

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

cluster

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

collections

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

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

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

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

Arguments:

• connection_params: weaviate.connect.ConnectionParams or None, optional

  • The connection parameters to use for the underlying HTTP requests.

• embedded_options: weaviate.EmbeddedOptions or None, optional

  • The options to use when provisioning an embedded Weaviate instance.

• auth_client_secret: weaviate.AuthCredentials or None, optional

  • Authenticate to weaviate by using one of the given authentication modes:

    • weaviate.auth.AuthBearerToken to use existing access and (optionally, but recommended) refresh tokens

    • weaviate.auth.AuthClientPassword to use username and password for oidc Resource Owner Password flow

    • weaviate.auth.AuthClientCredentials to use a client secret for oidc client credential flow

• additional_headers: dict or None, optional

  • Additional 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.

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

Check if the client is connected to Weaviate.

Returns:

bool

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

is_live() → bool

Ping Weaviate’s live state.

Returns:

bool

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