Simpler streamlined developer experience with AVS Python client 4.0

The Aerospike Vector Search (AVS) Python client 4.0.0 has undergone significant updates, including breaking changes, new features, and the removal of deprecated functionality.

These changes emphasize API simplicity and improved functionality. The addition of the Index object enables cleaner, more focused operations on specific indexes, while the merging of client types reduces complexity. Users are encouraged to migrate to the new patterns to take full advantage of the updated library and avoid disruptions.

Breaking changes

If you are already using an older version of the AVS Python client, these changes may break your application when upgrading to the 4.0.0 versioned client.

Merged admin and standard clients

The admin and standard clients have been merged into a single Client object. This consolidation simplifies the client API but introduces a breaking change for existing users who rely on separate client types. Users must instantiate the unified Client object for all operations, including administrative and data-related tasks.

Removed the deprecated wait_for_index_completion client method

We removed the previously deprecated wait_for_index_completion client method. We encourage you to monitor index status with the Index.status() and Index.get_percent_unmerged() methods instead. They provide more detailed and correct information about index completeness.

For example, to ensure that an index has finished indexing all its vector records, use a function like this:

import time
import aerospike_vector_search as avs
# Wait for the index to finish indexing records
def wait_for_indexing(index: avs.Index):
    verticies = 0
    unmerged_recs = 0
    # Wait for the index to have verticies and no unmerged records
    while verticies == 0 or unmerged_recs > 0:
        status = index.status()
        verticies = status.index_healer_vertices_valid
        unmerged_recs = status.unmerged_record_count
        time.sleep(0.5)

Removed the deprecated field_names parameter

We removed the field_names parameter and replaced it with the incude_fieldsparameter. Use this to specify which record fields to include in the results of a Client.get() or Client.vector_search() call.

Limited search, top_k results to 10 by default

When running a vector search or search by key, the limit parameter now defaults to 10, rather than unbounded.

Changed the types.IndexDefinition.vector_distance_metric type (minor)

The type of the types.IndexDefinition.vector_distance_metric field is now always types.VectorDistanceMetric. In most cases this is not a breaking change, but if you rely on the types.IndexDefinition.vector_distance_metric being an integer, this could break your code. For example, types.IndexDefinition.vector_distance_metric == 1 used to return True if types.IndexDefinition.vector_distance_metric was in integer, but because that field is now always type types.VectorDistanceMetric, comparing it to an integer will always return false.

Functional updates

These changes aren’t breaking and add new functionality to the AVS Python client. You should adopt these features to get the best performance and user experience.

Introduction of the Index object

A new Index object provides targeted operations on specific indexes. The Index object allows:

• Performing operations such as vector_search and vector_search_by_key directly on a specific index, without specifying the index namespace or name.

• Retrieving and updating index configurations.

• Monitoring and managing index status and completeness.

This enhancement improves code clarity by encapsulating index-specific operations into a dedicated object. It also reduces the potential for mistakes when specifying arguments such as index name and namespace by tracking them in the object and eliminating them as method arguments.

NOTE: Creating an Index object has some overhead as it retrieves the index definition from AVS. Index objects should be reused where possible. Avoid creating and destroying them in a tight loop.

import aerospike_vector_search as avs
# Create and connect a client
client = avs.Client(
    seeds=avs.types.HostPort(
        host="127.0.0.1",
        port=5000,
    ),
    # comment out the below line if you are not using a load balancer
    # or are not using a single node AVS cluster.
    is_loadbalancer=True,
)
# Create the index in AVS
client.index_create(
    namespace="test",
    name="test_index",
    vector_field="vector",
    dimensions=3,
)
# Get an Index object targeting the index we just created
index = client.index(
    namespace="test",
    name="test_index",
)
# Now you can perform targeted operations on the index
# Get the index definition
index_info = index.get()
# Perform an HNSW similarity search on the index
search_results = index.vector_search(
    query=[1.0, 2.0, 3.0],
    limit=3,
)
# Delete the index from AVS.
index.drop()
# Close the client
# NOTE: This will also close any Index objects created from this client
# Index objects need the Client that created them to be open to function
# so only close the client when you are done with the Index objects
client.close()

Exclude the vector field by default

When using the Index object, the vector field data is excluded by default in operations like vector_search and vector_search_by_key. This saves on network traffic and CPU time spent unpacking the usually large vector field. Users must explicitly include the vector field in the results using the include_fields parameter if it is needed.

NOTE: When using vector search through the Client object (not the Index object) the vector field is still included by default, and these performance hits are incurred.

Migration guide

Upgrading to the AVS Python client 4.0.0 gets you the latest features and best performance. Make sure to handle the breaking changes in client 4.0.0 by following the steps below.

Key migration steps

1. Switch to Unified Client.

   Replace separate admin and standard Client instances with a single Client instance.

# Old
admin_client = AdminClient(...)
standard_client = StandardClient(...)
# New
client = Client(...)

2. Adopt the new Index object.

Start to use the Index object for index-specific operations. This is preferred to direct client method calls for these operations.

# Old
client.vector_search(index_name="index_name", namespace="namespace", query=[...], ...)
# New
index = client.index(namespace="namespace", name="index_name")
neighbors = index.vector_search(query=[...], limit=5)

3. Update deprecated parameters.

Replace field_names with include_fields.

4. Monitor Index status with index.status().

Replace usage of wait_for_index_completion with checks against index status Index.status() or monitor index completion as a percentage through Index.get_percent_unmerged().

Explore migration examples

For an example of how to migrate to AVS Python client 4.0.0, see the PR introducing it to the AVS examples.