Skip to main content

Java client

This page describes how to create AI applications with the gRPC API and Java client provided with Aerospike Vector Search (AVS).


  • Java 21

Importing the Java client

  1. To import the client into your application, add the following dependency to your pom.xml:

        <!-- Aerospike client dependencies -->

    The artifacts are available on Maven.

  2. Import corresponding dependencies with the following:

    import com.aerospike.vector.client.*;
    import com.aerospike.vector.client.adminclient.AdminClient;
    import com.aerospike.vector.client.dbclient.Client;
    import com.aerospike.vector.client.dbclient.VectorSearchListener;

The AVS Java client has four main functions:

  • VectorDbAdminClientGrpc - administrative client.
  • VectorDbClientGrpc - database client for inserting vectors, searching, and checking index status.
  • Conversions - utility functions to convert data to the format accepted by AVS and convert retrieved data to JVM types.
  • HostPort - data structure to represent AVS information.

Admin client operations

This section provides example code for admin client operations:

Create an admin client:

AdminClient adminClient = new AdminClient(List.of(new HostPort(PROXIMUS_HOST, PROXIMUS_PORT, false)), "admin-label");

Create an index in AVS:

* indexId : Unique identifier for the index; must not be null.
* vectorBinName : Name of the bin storing vector data; must not be null.
* dimensions : Must be a positive integer, throws IllegalArgumentException otherwise.
* vectorDistanceMetric : distance to be used on this index
* setFilter : Can be null, which means no set filter is applied.
* indexParams : Optional parameters for fine-tuning the index.
* storage : Storage settings; can be null if default storage options are used.
* labels : Must not be empty; required for indexing metadata.
IndexStorage.newBuilder().setNamespace(NAMESPACE).build(), //recheck this

List available indexes in AVS:


Drop a specific index:

adminClient.indexDrop(com.aerospike.vector.client.IndexId indexId);

Retrieve the current status of an index:

adminClient.indexStatus(com.aerospike.vector.client.IndexId indexId);

Development client operations

This section provides example code for development client operations:

Create a client instance:

Client client = new Client(
List.of(new HostPort("localhost", 5000, false)), "client-label", true);

Add a vector in AVS:

* namespace : Aerospike namespace to store the record
* set : Aerospike set to be used for storing record
* key : key of the record
* map : Map< String, Object> contains bins and the corresponding values
* writeType: record write type
client.put(namespace, set, key, Map.of("vector_bin_name", vector, 0));

Retrieve an AVS record using a key:

client.get(namespace, set, key, Projection.DEFAULT);

Check if an inserted vector record is indexed:

client.isIndexed(namespace, set, key, index_namespace, indexName);

You can perform a simple vector search with the following:

* listener : a callback which acts upon intermediate states and can collect searched data
* namespace : Aerospike namespace
* indexname : name of the AVS indexname
* searchvector : a float array which gets converted to aerospike specific format
* limit : specifies number of records to be retunred as search result
* projection : result projection
VectorSearchQuery query = new VectorSearchQuery.Builder(namespace, indexname,
searchvector, limit).withProjection(Projection.getDefault()).build();
client.vectorSearchAsync(query, listener);

The following illustrates a simple listener implementation:

class SimpleListener implements VectorSearchListener {
List<Neighbor>[] results;
int idx;
AtomicLong counter;

public SimpleListener(int idx, List<Neighbor>[] results, AtomicLong counter) {
this.results = results;
this.idx = idx;
this.counter = counter;

List<Neighbor> result = new ArrayList<>();

public void onNext(Neighbor neighbor) {

public void onComplete() {
results[idx] = result;

public void onError(Throwable e) {
LOG.warn("Error in listener {}", e);

Get vector data as a float list

You can get an entry with the following call:

//getRecord() contains all bins returned from the AVS
List<Float> floatList = result.getRecord().getFields(0).getValue().getVectorValue().getFloatData().getValueList();

Support matrix

AVS versionsJava Client version


For a more detailed description of the APIs, see the Javadoc documentation.