Java client

Overview

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

Prerequisites

• Java 17 (Java client 0.4.0 and later)
• Java 21 (Java client 0.3.0 and earlier)

Java client components

The AVS Java client contains the following components:

Clients

• AdminClient: Administrative client for index management and user management.
• Client: AVS client used for inserting vectors, performing search operations, and checking index statuses.

Utility classes

• Conversions: Utility functions that convert data into the format accepted by AVS and transform retrieved data into JVM (Java Virtual Machine) types.
• HostPort: A data structure that represents AVS server information including hostname and port.
• ConnectionConfig: A data structure that outlines details related to connection settings such as endpoints, credentials, and timeouts.
• ClientTlsConfig: A data structure designed to encapsulate TLS (Transport Layer Security) configuration settings for secure communication.
• Projection: Query projection for specifying which parts of the documents to retrieve during search operations.
• StaticRoles: Represents a set of predefined user roles within the system, facilitating role-based access control.
• VectorSearchQuery: A data structure that represents parameters and criteria for performing vector search queries.

Importing the Java client

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

   <!-- Aerospike client dependencies -->
   <dependency>
   <groupId>com.aerospike</groupId>
   <artifactId>avs-client-java</artifactId>
   <version>0.4.0</version>
   </dependency>

   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;

Admin client operations

This section provides example code for admin client operations.

Create an admin client:

// create a user with admin privileges
com.aerospike.vector.client.auth.PasswordCredentials cred = new com.aerospike.vector.client.auth.PasswordCredentials("admin", "admin");

// connection config
ConnectionConfig adminConfig  =  new  ConnectionConfig.Builder()
    .withHosts(TlsConfigProvider.HOSTS)
    .withListenerName("listener")
    .withLoadBalancer(true)
    .withCredentials(cred)
    .withConnectTimeout(10000)
    .withTls(tlsConfig) // if mtls/tls connection required
    .build();
AdminClient adminClient = new AdminClient(adminConfig);

Create an AVS index:

adminClient.indexCreate(indexId, "vector", 128, VectorDistanceMetric.DOT_PRODUCT,null,HnswParams.newBuilder().build(),
IndexStorage.newBuilder().setNamespace(DEFAULT_NAMESPACE).build(), 
Map.of(), 60_000, 1_000);
);

List available indexes in AVS:

adminClient.indexList();

Drop a specific index:

adminClient.indexDrop(indexId);

Retrieve the current status of an index:

adminClient.indexStatus(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);

Vector search

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 index name
 * searchvector: a float array which gets converted to aerospike specific format
 * limit: specifies number of records to be returned 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<>();

    @Override
    public void onNext(Neighbor neighbor) {
        result.add(neighbor);
    }

    @Override
    public void onComplete() {
        results[idx] = result;
        counter.incrementAndGet();
    }

    @Override
    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 AVS
List<Float> floatList = result.getRecord().getFields(0).getValue().getVectorValue().getFloatData().getValueList();

Support matrix

AVS version	Java Client version	Required Java version
0.9.0	0.4.0	17
0.9.0	0.3.0	21
0.4.0	0.2.0	21

Javadocs

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