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โ
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.
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.