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