Embedded Weaviate

Experimental

Embedded Weaviate is experimental software. APIs and parameters may change.

Embedded Weaviate is a deployment model that runs a Weaviate instance from your application code rather than from a stand-alone Weaviate server installation.

When Embedded Weaviate starts for the first time, it creates a permanent datastore in the location set in your persistence_data_path. When your client exits, the Embedded Weaviate instance also exits, but the data persists.

The next time the client runs, the client starts a new instance of Embedded Weaviate. New Embedded Weaviate instances use the data that is saved in the datastore.

Start an Embedded Weaviate instance

Python

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

import weaviate
import os

client = weaviate.connect_to_embedded(
    version=weaviate_version,  # e.g. version="1.33.0"
    headers={
        "X-OpenAI-Api-Key": os.getenv("OPENAI_API_KEY")  # Replace with your API key
    },
    environment_variables={"LOG_LEVEL": "error"}  # Reduce amount of logs
)

# Add your client code here.

Set the log level to reduce verbosity

Embedded Weaviate can emit a lot of log messages. To reduce the amount of logs, set the LOG_LEVEL environment variable to error or warning, as shown in the example above.

When you exit the client, the Embedded Weaviate instance also exits.

Custom connection configuration

To pass additional configuration details to your embedded instance, use a custom connection:

Python

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

import weaviate
from weaviate.embedded import EmbeddedOptions
import os

client = weaviate.WeaviateClient(
    embedded_options=EmbeddedOptions(
        additional_env_vars={
            "ENABLE_MODULES": "backup-filesystem,text2vec-openai,text2vec-cohere,text2vec-huggingface,ref2vec-centroid,generative-openai,qna-openai",
            "BACKUP_FILESYSTEM_PATH": "/tmp/backups"
        }
    )
    # Add additional options here (see Python client docs for syntax)
)

client.connect()  # Call `connect()` to connect to the server when you use `WeaviateClient`

# Add your client code here.

# Uncomment the next line to exit the Embedded Weaviate server.
# client.close()

Configuration options

To configure Embedded Weaviate, set these variables in your instantiation code or pass them as parameters when you invoke your client. You can also pass them as system environment variables. All parameters are optional.

Parameter	Type	Default	Description
additional_env_vars	string	None.	Pass additional environment variables, such as API keys, to the server.
binary_path	string	varies	Binary download directory. If the binary is not present, the client downloads the binary. If XDG_CACHE_HOME is set, its value is used verbatim as the default. No subdirectory is appended, so XDG_CACHE_HOME=/foo makes the default exactly /foo. If XDG_CACHE_HOME is not set, the default is: ~/.cache/weaviate-embedded/
grpc_port	integer	50060	The Weaviate server gRPC port. The client passes this value to the server as GRPC_PORT.
hostname	string	127.0.0.1	Hostname or IP address
persistence_data_path	string	varies	Data storage directory. If XDG_DATA_HOME is set, its value is used verbatim as the default. No subdirectory is appended, so XDG_DATA_HOME=/foo makes the default exactly /foo. If XDG_DATA_HOME is not set, the default is: ~/.local/share/weaviate
port	integer	8079	The Weaviate server request port.
version	string	A version pinned in the client (see note)	Specify the version with one of the following: -"latest" - The version number as a string: "1.19.6" - The URL of a Weaviate binary (See below)

Set version explicitly

If you do not set version, Embedded Weaviate does not run the latest Weaviate release. The client falls back to a single Weaviate version that is fixed in the client source code when that client release is published. That pin only moves when the client is released again, so it can be several Weaviate minor releases behind the current one, and upgrading your client can also change which Weaviate version your embedded instance runs.

Set version explicitly so you control which server version you get. Use "latest" to resolve the newest Weaviate release at startup, or pin a version number such as "1.19.6" for a reproducible environment. The version in use is printed in the embedded server startup logs.

Do not modify XDG_CACHE_HOME or XDG_DATA_HOME

The XDG_DATA_HOME and XDG_CACHE_HOME environment variables are widely used system variables. If you modify them, you may break other applications.

Default modules

The following modules are enabled by default:

• generative-openai
• qna-openai
• ref2vec-centroid
• text2vec-cohere
• text2vec-huggingface
• text2vec-openai

To enable additional modules, add them to your instantiation code.

For example, to add the backup-s3 module, instantiate your client like this:

Python

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

import weaviate
from weaviate.embedded import EmbeddedOptions
import os

client = weaviate.WeaviateClient(
    embedded_options=EmbeddedOptions(
        additional_env_vars={
            "ENABLE_MODULES": "backup-filesystem,text2vec-openai,text2vec-cohere,text2vec-huggingface,ref2vec-centroid,generative-openai,qna-openai",
            "BACKUP_FILESYSTEM_PATH": "/tmp/backups"
        }
    )
    # Add additional options here. For syntax, see the Python client documentation.
)

# Run your client code in a context manager or call client.close()
# before exiting the client to avoid connection errors.
client.connect()  # Call `connect()` to connect to the server when you use `WeaviateClient`

# Add your client code here.

Binary sources

Weaviate Database releases include executable Linux binaries. When you instantiate an Embedded Weaviate client, the client checks for local copies of the binary packages. If the client finds the binary files, it runs them to create a temporary Weaviate instance. If not, the client downloads the binaries and saves them in your binary_path directory.

The Embedded Weaviate instance goes away when your client exits. However, the client does not delete the binary files. The next time your client runs, it checks for the binaries and uses the saved binaries if they exist.

File list

For a list of the files that are included in a release, see the Assets section of the Release Notes page for that release on GitHub.

File URL

To get the URL for a particular binary archive file, follow these steps:

1. Find the Weaviate Database release you want on the Release Notes page.
2. Click to the release notes for that version. The Assets section includes linux-amd64 and linux-arm64 binaries in tar.gz format.
3. Copy the link to the full URL of the tar.gz file for your platform.

For example, the URL for the Weaviate 1.19.6 AMD64 binary is:

https://github.com/weaviate/weaviate/releases/download/v1.19.6/weaviate-v1.19.6-linux-amd64.tar.gz.

Functional overview

Weaviate Database usually runs as a stand-alone server that clients connect to in order to access data. An Embedded Weaviate instance is a process that runs in conjunction with a client script or application. Embedded Weaviate instances can access a persistent datastore, but the instances exit when the client exits.

When your client runs, it checks for a stored Weaviate binary. If it finds one, the client uses that binary to create an Embedded Weaviate instance. If not, the client downloads the binary.

The instance also checks for an existing data store. Clients reuse the same data store, updates persist between client invocations.

When you exit the client script or application, the Embedded Weaviate instance also exits:

• Scripts: The Embedded Weaviate instance exits when the script exits.
• Applications: The Embedded Weaviate instance exits when the application exits.
• Jupyter Notebooks: The Embedded Weaviate instance exits when the Jupyter notebook is no longer active.

Embedded server output

The embedded server pipes STDOUT and STDERR to the client. To redirect STDERR in a command terminal, run your script like this:

python3 your_embedded_client_script.py 2>/dev/null

Supported Environments

Embedded Weaviate is supported on Linux and macOS.

Client languages

Embedded Weaviate is supported for Python and TypeScript clients.

Python clients

Embedded Weaviate is built into the Python client, so there is no separate package to install. The Python client requires Weaviate v1.23.7 or later.

TypeScript clients

The embedded TypeScript client is no longer a part of the standard TypeScript client.

The embedded client has additional dependencies that are not included in the standard client. However, the embedded client extends the original TypeScript client so after you instantiate an Embedded Weaviate instance, the embedded TypeScript client works the same way as the standard client.

To install the embedded TypeScript client, run this command:

npm install weaviate-ts-embedded

The TypeScript clients are in these GitHub repositories:

• Embedded TypeScript client
• Standard TypeScript client

Questions and feedback

Have a question or feedback? Here's how to reach us.

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.