Embedded Weaviate

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.

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.

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

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

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()

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.

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:

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.

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.

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.

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.

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.

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

Embedded Weaviate is supported on Linux and macOS.

Embedded Weaviate is supported for Python and TypeScript 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.

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

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