Skip to main content

Migrate from v3 to v4

Python client version

The current Python client version is v4.5.7

The v4 Weaviate Python client API is very different from the v3 API. This guide will help you understand the major changes and how to migrate your code at a high level.

Installation​

To go from v3 to v4, you must

  1. Upgrade the client library:

    pip install -U weaviate-client  # For beta versions: `pip install --pre -U "weaviate-client==4.*"`

  2. Upgrade Weaviate to a compatible version

    • Weaviate 1.23.7 is required for v4.4.1. Generally, we recommend you use the latest versions of Weaviate and the client.

  3. Make sure a port for gRPC is open to Weaviate.

    • The default port is 50051.
    docker-compose.yml example

    If you are running Weaviate with Docker, you can map the default port (50051) by adding the following to your docker-compose.yml file:

        ports:
        - 8080:8080
        - 50051:50051

Instantiation​

The v4 client is instantiated through the WeaviateClient object, which is the main entry point for all API operations.

You can directly instantiate the client, but in most cases you can use helper functions starting with _connect_to, such as connect_to_local, connect_to_wcs.

import weaviate
import os

client = weaviate.connect_to_wcs(
    cluster_url=os.getenv("WCS_DEMO_URL"),  # Replace with your WCS URL
    auth_credentials=weaviate.auth.AuthApiKey(os.getenv("WCS_DEMO_RO_KEY")),  # Replace with your WCS key
    headers={'X-OpenAI-Api-key': os.getenv("OPENAI_APIKEY")}  # Replace with your OpenAI API key
)

To configure connection timeout values, see Timeout values.

Major changes​

The v4 client API is very different from the v3 API. Major user-facing changes in the v4 client include:

  • Extensive use of helper classes
  • Interaction with collections
  • Removal of builder patterns

Helper classes​

The v4 client introduces an extensive set of helper classes to interact with Weaviate. These classes are used to provide strong typing, and to make the client more user-friendly such as through IDE autocompletion.

Take a look at the examples below.

import weaviate
import weaviate.classes.config as wvcc

client = weaviate.connect_to_local()

try:
    # Note that you can use `client.collections.create_from_dict()` to create a collection from a v3-client-style JSON object
    collection = client.collections.create(
        name="TestArticle",
        vectorizer_config=wvcc.Configure.Vectorizer.text2vec_cohere(),
        generative_config=wvcc.Configure.Generative.cohere(),
        properties=[
            wvcc.Property(
                name="title",
                data_type=wvcc.DataType.TEXT
            )
        ]
    )

finally:
    client.close()

In both of these examples, you can see how the helper classes and methods abstract away the need for manual JSONs or strings.

Interaction with collections​

Interacting with the client object for CRUD and search operations have been replaced with the use of collection objects.

This conveniently removes the need to specify the collection for each operation, and reduces potential for errors.

jeopardy = client.collections.get("JeopardyQuestion")

data_object = jeopardy.query.fetch_object_by_id("00ff6900-e64f-5d94-90db-c8cfa3fc851b")

print(data_object.properties)

Note here that the collection object can be re-used throughout the codebase.

Collection creation from JSON​

You can still create a collection from a JSON definition. This may be a useful way to migrate your existing data, for example. You could fetch an existing definition and then use it to create a new collection.

import weaviate

client = weaviate.connect_to_local()

try:
    collection_definition = {
        "class": "TestArticle",
        "properties": [
            {
                "name": "title",
                "dataType": ["text"],
            },
            {
                "name": "body",
                "dataType": ["text"],
            },
        ],
    }

    client.collections.create_from_dict(collection_definition)

finally:
    client.close()

Removal of builder patterns​

The builder patterns for constructing queries have been removed, as they could be confusing and potentially lead to invalid queries.

In v4, queries are constructed using specific methods and its parameters.

from weaviate.classes.query import MetadataQuery

jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.near_text(
    query="animals in movies",
    limit=2,
    return_metadata=MetadataQuery(distance=True)
)

for o in response.objects:
    print(o.properties)
    print(o.metadata.distance)

This makes it easier to understand and use. Additionally, some parameters typed (e.g. MetadataQuery) which makes it easier to use and reduces errors.

How to migrate your code​

The migration will likely involve significant changes to your codebase. Review the Python client library documentation to get started, including instantiation details and various submodules.

Then, take a look at the how-to guides for Managing data and Queries.

In particular, check out the pages for:

Questions and feedback​

If you have any questions or feedback, let us know in our user forum.