weaviate.connect package

Module communication to a Weaviate instance. Used to connect to Weaviate and run REST requests.

class weaviate.connect.Connection(url: str, auth_client_secret: _BearerToken | _ClientPassword | _ClientCredentials | _APIKey | None, timeout_config: Tuple[int | float, int | float], proxies: dict | str | None, trust_env: bool, additional_headers: Dict[str, Any] | None, startup_period: int | None, connection_config: ConnectionConfig, embedded_db: EmbeddedV3 | None = None, grcp_port: int | None = None)[source]

Bases: _ConnectionBase

Connection class used to communicate to a weaviate instance.

Initialize a Connection class instance.

Parameters

urlstr

URL to a running weaviate instance.

auth_client_secretweaviate.auth.AuthCredentials, optional

Credentials to authenticate with a weaviate instance. The credentials are not saved within the client and authentication is done via authentication tokens.

timeout_configtuple(float, float) or float, optional

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

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.

trust_envbool, optional

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

additional_headersDict[str, Any] or None

Additional headers to include in the requests, used to set OpenAI key. OpenAI key looks like this: {‘X-OpenAI-Api-Key’: ‘KEY’}.

startup_periodint or None

How long the client will wait for weaviate to start before raising a RequestsConnectionError. If None the client will not wait at all.

Raises

ValueError

If no authentication credentials provided but the Weaviate server has an OpenID configured.

close() None[source]

Shutdown connection class gracefully.

delete(path: str, weaviate_object: dict | list | None = None, params: Dict[str, Any] | None = None) Response[source]

Make a DELETE request to the Weaviate server instance.

Parameters

pathstr

Sub-path to the Weaviate resources. Must be a valid Weaviate sub-path. e.g. ‘/meta’ or ‘/objects’, without version.

weaviate_objectdict, optional

Object is used as payload for DELETE request. By default None.

paramsdict, optional

Additional request parameters, by default None

Returns

requests.Response

The response, if request was successful.

Raises

requests.ConnectionError

If the DELETE request could not be made.

get(path: str, params: Dict[str, Any] | None = None, external_url: bool = False) Response[source]

Make a GET request.

Parameters

pathstr

Sub-path to the Weaviate resources. Must be a valid Weaviate sub-path. e.g. ‘/meta’ or ‘/objects’, without version.

paramsdict, optional

Additional request parameters, by default None

external_url: Is an external (non-weaviate) url called

Returns

requests.Response

The response if request was successful.

Raises

requests.ConnectionError

If the GET request could not be made.

get_current_bearer_token() str[source]
get_meta() Dict[str, str][source]

Returns the meta endpoint.

get_proxies() dict[source]
property grpc_stub: WeaviateStub | None
head(path: str, params: Dict[str, Any] | None = None) Response[source]

Make a HEAD request to the server.

Parameters

pathstr

Sub-path to the resources. Must be a valid sub-path. e.g. ‘/meta’ or ‘/objects’, without version.

paramsdict, optional

Additional request parameters, by default None

Returns

requests.Response

The response to the request.

Raises

requests.ConnectionError

If the HEAD request could not be made.

patch(path: str, weaviate_object: dict | list, params: Dict[str, Any] | None = None) Response[source]

Make a PATCH request to the Weaviate server instance.

Parameters

pathstr

Sub-path to the Weaviate resources. Must be a valid Weaviate sub-path. e.g. ‘/meta’ or ‘/objects’, without version.

weaviate_objectdict

Object is used as payload for PATCH request.

paramsdict, optional

Additional request parameters, by default None

Returns

requests.Response

The response, if request was successful.

Raises

requests.ConnectionError

If the PATCH request could not be made.

post(path: str, weaviate_object: dict | list, params: Dict[str, Any] | None = None) Response[source]

Make a POST request to the Weaviate server instance.

Parameters

pathstr

Sub-path to the Weaviate resources. Must be a valid Weaviate sub-path. e.g. ‘/meta’ or ‘/objects’, without version.

weaviate_objectdict

Object is used as payload for POST request.

paramsdict, optional

Additional request parameters, by default None

external_url: Is an external (non-weaviate) url called

Returns

requests.Response

The response, if request was successful.

Raises

requests.ConnectionError

If the POST request could not be made.

property proxies: dict
put(path: str, weaviate_object: dict | list, params: Dict[str, Any] | None = None) Response[source]

Make a PUT request to the Weaviate server instance.

Parameters

pathstr

Sub-path to the Weaviate resources. Must be a valid Weaviate sub-path. e.g. ‘/meta’ or ‘/objects’, without version.

weaviate_objectdict

Object is used as payload for PUT request.

paramsdict, optional

Additional request parameters, by default None

Returns

requests.Response

The response, if request was successful.

Raises

requests.ConnectionError

If the PUT request could not be made.

property server_version: str

Version of the weaviate instance.

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

Getter/setter for timeout_config.

Parameters

timeout_configtuple(float, float), optional

For Setter only: Set the timeout configuration for all requests to the Weaviate server. It can be a float or, a tuple of two floats:

(connect timeout, read timeout).

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

Returns

Tuple[float, float]

For Getter only: Requests Timeout configuration.

wait_for_weaviate(startup_period: int) None[source]

Waits until weaviate is ready or the time limit given in ‘startup_period’ has passed.

Parameters

startup_periodint

Describes how long the client will wait for weaviate to start in seconds.

Raises

WeaviateStartUpError

If weaviate takes longer than the time limit to respond.

pydantic model weaviate.connect.ConnectionParams[source]

Bases: BaseModel

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: ProtocolParams [Required]
Validated by:
  • _check_port_collision

field http: ProtocolParams [Required]
Validated by:
  • _check_port_collision

classmethod from_params(http_host: str, http_port: int, http_secure: bool, grpc_host: str, grpc_port: int, grpc_secure: bool) ConnectionParams[source]
classmethod from_url(url: str, grpc_port: int, grpc_secure: bool = False) ConnectionParams[source]
model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

class weaviate.connect.ConnectionV4(connection_params: ConnectionParams, auth_client_secret: _BearerToken | _ClientPassword | _ClientCredentials | _APIKey | None, timeout_config: Timeout, proxies: str | Proxies | None, trust_env: bool, additional_headers: Dict[str, Any] | None, connection_config: ConnectionConfig, embedded_db: EmbeddedV4 | None = None)[source]

Bases: _Connection

property agrpc_stub: WeaviateStub | None
connect(skip_init_checks: bool) None[source]
grpc_headers() Tuple[Tuple[str, str], ...] | None[source]
property grpc_stub: WeaviateStub | None
pydantic model weaviate.connect.ProtocolParams[source]

Bases: BaseModel

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 host: str [Required]
Validated by:
  • _check_host

field port: int [Required]
Validated by:
  • _check_port

field secure: bool [Required]
model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

Submodules

weaviate.connect.authentication module

weaviate.connect.connection module

weaviate.connect.helpers module

Helper functions for creating a new WeaviateClient in common scenarios.

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

Connect to a Weaviate instance with custom connection parameters.

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

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

Arguments:
http_host

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

http_port

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

http_secure

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

grpc_host

The host to use for the underlying gRPC API.

grpc_port

The port to use for the underlying gRPC API.

grpc_secure

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

headers

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

additional_config

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

auth_credentials

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

skip_init_checks

Whether to skip the initialization checks when connecting to Weaviate.

Returns
weaviate.WeaviateClient

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

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

Connect to an embedded Weaviate instance.

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

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

Arguments:
hostname

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

port

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

grpc_port

The port to use for the underlying gRPC API.

headers

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

additional_config

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

version

Weaviate version to be used for the embedded instance.

persistence_data_path

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

binary_path

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

environment_variables

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

Returns
weaviate.WeaviateClient

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

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

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

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

Arguments:
host

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

port

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

grpc_port

The port to use for the underlying gRPC API.

headers

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

additional_config

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

skip_init_checks

Whether to skip the initialization checks when connecting to Weaviate.

auth_credentials

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

Returns
weaviate.WeaviateClient

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

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

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

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

Arguments:
cluster_url

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

auth_credentials

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

headers

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

additional_config

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

skip_init_checks

Whether to skip the initialization checks when connecting to Weaviate.

Returns
weaviate.WeaviateClient

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

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