Introduction
All good things have to come to an end. In this case, it's time for us to start saying goodbye to the v3 API in our Weaviate Python client.
You probably know that the Weaviate Python client got a glow-up to an extensively re-written (and improved) v4 API around six months ago. This brought more speed through gRPC and improved usability through expanded IDE support and additional type-safety.
Here's an illustrative example of the difference between the two versions. Note how little of the v4 API is based on raw strings, and how much more is based on type-safe objects:
- Python Client v4
- Python Client v3
from weaviate.classes.config import Configure, Property, DataType, VectorDistances, VectorFilterStrategy
client.collections.create(
"Article",
# Additional configuration not shown
vector_index_config=Configure.VectorIndex.hnsw(
quantizer=Configure.VectorIndex.Quantizer.bq(),
ef_construction=300,
distance_metric=VectorDistances.COSINE,
filter_strategy=VectorFilterStrategy.SWEEPING # or ACORN (Available from Weaviate v1.27.0)
),
)
class_obj = {
'class': 'Article',
# Additional configuration not shown
"vectorIndexType": "flat",
"vectorIndexConfig": {
"bq": {
"enabled": True, # Enable BQ compression. Default: False
"rescoreLimit": 200, # The minimum number of candidates to fetch before rescoring. Default: -1 (No limit)
"cache": True, # Enable use of vector cache. Default: False
},
"vectorCacheMaxObjects": 100000, # Cache size if `cache` enabled. Default: 1000000000000
"filterStrategy": "sweeping" # or "acorn" (Available from Weaviate v1.27.0)
}
}
client.schema.create_class(class_obj)
The v4 API is a significant improvement over the v3 API, and we want to encourage all of our users to migrate to the new version.
Having said that, we appreciate that code migration isn't an overnight task. So the v4 client versions had included the older v3 API in order to ease the transition.
But this will be coming to an end in a few months. Here's what you need to know:
Deprecation plan
Starting in December 2024, the v4 client will no longer include the v3 API (i.e. the weaviate.Client class).
The v3 client (latest version 3.26.7) will continue to be available on PyPI for existing projects. But it will not receive any new features or updates, except for any critical security updates.
This will help us to provide the best developer experience for you, continue to add support for the latest features in a timely manner, and clearly separate the two.
What does this mean for me?
New projects or projects with active development
The v4 client API is the only way to take advantage of the latest Weaviate core database versions. So if you want to use the latest features, you will need to migrate to the v4 API.
Our documentation includes a migration guide here, and many code examples include both v3 and v4 syntax. We will be adding more dedicated resources for you to ease the migration experience.
Frozen codebases
If you have an existing codebase and Weaviate core database that you expect to remain static, we recommend pinning the version in your requirements file (e.g. requirements.txt), like so:
weaviate-client>=3.26.7,<4.0.0
Conclusion
We appreciate that code migration can be cumbersome, but we feel strongly that the end experience and feature set will make your time worthwhile.
If you have specific requests for migration documentation or resources, please reach out through our docs GitHub repository.
We're excited to see the amazing AI-native apps that you build with the v4 API. Thanks for reading and happy coding!
Ready to start building?
Check out the Quickstart tutorial, or build amazing apps with a free trial of Weaviate Cloud (WCD).
Don't want to miss another blog post?
Sign up for our bi-weekly newsletter to stay updated!
By submitting, I agree to the Terms of Service and Privacy Policy.