Java SDK
A gRPC client for the JVM. It handles the token exchange, connection management and retries, so your code deals in collections and documents rather than in headers.
Adding the dependency
The packages are on GitHub Packages, which needs a GitHub account and a token with the
read:packages scope. Add the credentials to your Maven settings.xml:
<servers>
<server>
<id>cyrock-packages</id>
<username>your-github-username</username>
<password>your-personal-access-token</password>
</server>
</servers>
Then the repository and the dependency in your project:
<repositories>
<repository>
<id>cyrock-packages</id>
<name>CYROCK.AI Packages</name>
<url>https://maven.pkg.github.com/cyrock-ai/releases</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>ai.cyrock.db</groupId>
<artifactId>cyrock-db-client-java</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
The id in settings.xml and in <repositories> must match - that is how Maven knows which
credentials to send. The SDK needs Java 21, and pulls in gRPC but no Spring and no storage engine.
Protobuf compatibility
The SDK’s generated gRPC classes are compiled against Protobuf 4.31.1 and bring
com.google.protobuf:protobuf-java along with them. Protobuf’s rule here runs one way only: the
protobuf-java on your classpath may be newer than the version the classes were generated against,
never older. Generating against 4.31.1 rather than the newest release is deliberate - it leaves room
for applications whose own dependency management holds Protobuf at an older 4.x version than the SDK
would otherwise bring.
A version your build manages wins over the one the SDK asks for. Spring Boot 4.1 and later manage Protobuf through a property, so that is where to move it if you need to. Anything from 4.31.1 upwards works; 4.35.1 below is the version the SDK resolves on its own, and the one it is tested against:
<properties>
<protobuf-java.version>4.35.1</protobuf-java.version>
</properties>
Below 4.31.1, the first generated class your code touches throws ProtobufRuntimeVersionException -
see Troubleshooting. Protobuf 3.x is a different major version and is not
supported.
To take the SDK together with the gRPC and Protobuf versions it was tested against, import the BOM instead of pinning anything yourself:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>ai.cyrock.db</groupId>
<artifactId>cyrock-db-bom</artifactId>
<version>1.0.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>ai.cyrock.db</groupId>
<artifactId>cyrock-db-client-java</artifactId>
</dependency>
</dependencies>
Maven takes the first managed version it finds, so an import only wins over the imports below it: if your framework’s BOM is imported first, its Protobuf and gRPC versions stay in force and this one changes nothing.
Connecting
import ai.cyrock.db.client.java.CyrockDbClient;
import ai.cyrock.db.client.java.CyrockDbClientGrpc;
try (CyrockDbClient client = CyrockDbClientGrpc.builder()
.apiKey("<the key from the startup banner>")
.build())
{
// ...
}
close() declares IOException, so the enclosing method needs to throw or catch it.
No host and no port. The defaults are localhost:7290, which is exactly where the container’s
client gateway listens, so a local evaluation needs neither. Point it elsewhere when you need to:
CyrockDbClientGrpc.builder()
.host("cyrock-db.internal")
.port(7290)
.apiKey(apiKey)
.build();
Port 7290 is the client gateway, which fronts both the data and the platform plane. The client
needs both - the key exchange lives on the platform side - so this is the port to use rather than the
individual server ports.
The client is thread-safe and holds a connection pool. Create one per application, not one per request, and close it on shutdown (or let try-with-resources do it).
Retrying while the server comes back
A server that is restarting, being moved, or waking up after it was scaled to zero answers
UNAVAILABLE until it is back, and by default that reaches you as an UnavailableException. Give the
client a RetryPolicy and it retries those calls itself:
import ai.cyrock.db.client.java.RetryPolicy;
CyrockDbClientGrpc.builder()
.apiKey(apiKey)
.callTimeout(Duration.ofSeconds(30))
.retryPolicy(RetryPolicy.builder().build())
.build();
-
What is retried. Only calls that failed with
UNAVAILABLE, and by default only reads: the operations the protocol marks as free of side effects, plus the token exchange,recallandglobalSearch, which touch state but are safe to repeat. A write that failed may still have been applied, its answer lost on the way back, so retrying it can apply it twice;.retryWrites(true)opts into that where your writes tolerate it, such as upserts by key. CyQL statements count as writes, since one operation carries both. Change streams reconnect on their own and are not affected. -
One more
LOGINin the audit log, now and then. When the server completes a token exchange but its answer is lost, the retry exchanges again, and the audit log shows aLOGINevent for each exchange the server completed. The token from the lost answer never reaches the client and simply expires. A manual retry after a failed exchange leaves the same trace. -
How long it waits. Up to
maxAttemptsattempts, five at most and by default. Before retry n it waits a random time between zero andinitialBackoff * backoffMultiplier^(n-1), capped atmaxBackoff: by default up to half a second, doubling, capped at ten seconds, so at most 7.5 seconds of waiting in all. The randomness keeps clients that lost the same server from all coming back at once. -
Set a
callTimeoutwith it. The timeout covers a call with all its retries, so it is what bounds how long a caller waits for a server that is not coming back.
The policy applies to the asynchronous client too, which shares the connection.
Creating a collection
Fields come in two lists: vector fields and metadata fields. The vector list may be empty: a
collection without a vector field is a document store with metadata filtering, and only similarity
search is unavailable on it. Full-text search is available on top of that for each STRING field
declared with fulltext - the fourth constructor argument below, false in both of these fields.
CollectionDefinition definition = CollectionDefinition.builder()
.name("articles")
.vectorFields(List.of(VectorFieldDefinition.builder()
.name("vector")
.dimension(384)
.similarityFunction(SimilarityFunction.COSINE)
.build()))
.metadataFields(List.of(
new MetadataFieldDefinition("title", MetadataFieldType.STRING, Cardinality.HIGH, false, false),
new MetadataFieldDefinition("topic", MetadataFieldType.STRING, Cardinality.LOW, false, false)))
.build();
String collectionId = client.createCollection(projectId, definition).id();
MetadataFieldDefinition takes (name, type, cardinality, fulltext, unique). Cardinality picks the
indexing strategy - HIGH for values that are nearly unique per record, LOW for a small set of
repeated values. Set fulltext to index the field for BM25 SEARCH.
Documents
client.upsertDocument(
collectionId,
"how-to-reset-a-password", // your own external key
Map.of("vector", VectorInput.of(embedding)), // vector fields
Map.of("title", "Resetting a password", // metadata fields
"topic", "accounts"));
Document found = client.getDocument(collectionId, "how-to-reset-a-password");
client.removeDocument(collectionId, "how-to-reset-a-password");
The key is yours to choose, and upsert inserts or replaces, so re-running an import does not create duplicates.
VectorInput.of(float[]) passes an embedding you computed. VectorInput.of(String) passes text and
has the server embed it, which needs an embedding provider configured - see
Configuration.
Searching
List<Match> matches = client.search(collectionId,
SearchRequest.builder("vector", queryVector, 10)
.filter("topic = $topic")
.filterParameter("topic", userTopic)
.build());
The builder takes the vector field, the query vector and the maximum number of results. The filter is
applied before ranking, so all ten results survive it. Bind every caller-supplied value as a $name
with filterParameter rather than concatenating it into the filter string: a concatenated value can
break out of its quotes and rewrite the predicate, a bound one is always a literal. multiSearch searches several vector fields at
once and hybridSearch fuses BM25 with vector similarity.
Running CyQL
Often the shortest path, especially for traversal. Three methods, differing only in what the statement is scoped to - picking the wrong one is the easiest mistake to make here:
| Method | Scope |
|---|---|
|
One collection |
|
One graph |
|
Project-wide DDL - |
StatementResult result = client.executeCollectionStatement(
collectionId,
"MATCH (d) WHERE d.topic = $topic RETURN d.title",
QueryParameters.builder().param("topic", "accounts").build());
for (Map<String, Object> row : result.rows())
{
System.out.println(row.get("d.title"));
}
StatementResult carries columns(), rows() and, for writes, a summary(). Pass values through
QueryParameters rather than concatenating them into the statement; .vector(name, float[]) binds a
vector for a SIMILAR TO $v clause.
Calling asynchronously
Every method above blocks: the calling thread waits for the round trip. That is what you want for a script, and what you do not want when several calls could be in flight at once - fifty searches would need fifty threads, each doing nothing but waiting.
client.async() returns the same operations returning CompletableFuture:
import ai.cyrock.db.client.java.CyrockDbAsyncClient;
CyrockDbAsyncClient async = client.async();
CompletableFuture<List<Match>> matches = async.search(collectionId,
SearchRequest.builder("vector", queryVector, 10).build());
It shares the synchronous client’s connection, its key exchange and its lifecycle. There is nothing extra to build and nothing extra to close - closing the synchronous client closes both.
Fanning out
The point of it. These fifty searches share one connection and no threads wait:
List<CompletableFuture<List<Match>>> pending = queries.stream()
.map(query -> async.search(collectionId,
SearchRequest.builder("vector", query, 10).build()))
.toList();
CompletableFuture
.allOf(pending.toArray(new CompletableFuture[0]))
.join();
List<List<Match>> results = pending.stream().map(CompletableFuture::join).toList();
Ordering: chain what depends, fan out what does not
Two futures started together have no order. Fired alongside its own write, a read may not see it. When the second call depends on the first, chain them:
CompletableFuture<Document> written = async
.upsert(collectionId, -1L, Map.of("vector", VectorInput.of(vector)), metadata)
.thenCompose(id -> async.getById(collectionId, id));
This is the one habit to carry over from the blocking API, where statement order gave you the ordering for free.
Concurrent writes to the same collection are applied in the order they arrive, which is not necessarily the order you submitted them in. Fanning writes out is fine when they are independent; when one must follow another, chain it.
Failures
A future completes exceptionally rather than throwing. CompletableFuture wraps the cause, so unwrap
one level before matching on it:
async.getDocument(collectionId, externalKey)
.exceptionally(error ->
{
Throwable cause = error instanceof CompletionException && error.getCause() != null
? error.getCause()
: error;
System.err.println(cause.getMessage());
return null;
});
join() and get() wrap it the same way. What is inside is the CyrockDbClientException the
synchronous client would have thrown for the same failure - the same subtype and the same status code,
since both surfaces share one mapping - so a catch block moving across only needs the unwrap. Once
unwrapped, the subtypes apply unchanged, RetryableException included, which matters most
here: a caller holding many calls in flight is exactly the one who wants to retry the two failures
resending can fix.
Threading
A continuation attached without an executor runs on a gRPC transport thread. Keep those short, and give anything that blocks - or touches a UI - an executor of its own:
async.search(collectionId, request)
.thenAcceptAsync(this::render, myExecutor);
Cancelling a returned future cancels the call, so a caller who stops caring stops costing the server work.
Transactions
client.executeDocumentTransaction(collectionId, List.of(
CollectionOperation.upsert(...),
CollectionOperation.remove(...)));
Every operation applies or none does. Graphs have the same thing as executeTransaction(graphId,
List<GraphOperation>).
A transaction is one call: the whole operation list goes to the server at once and commits as one unit. There is no open-then-commit session spanning several calls, and a transaction covers one collection or one graph.
A node and its edges in one transaction
A new node’s id is assigned only when the transaction runs, so an edge to it cannot name it by id. Each
endpoint of an AddEdge is therefore either an existing node, EdgeEndpoint.node(id), or the node an
earlier operation of the batch creates, EdgeEndpoint.operation(index), where index is that AddNode
or UpsertNode’s position in the list. `new AddEdge(sourceId, targetId, …) is short for two
EdgeEndpoint.node endpoints.
final TransactionResult result = client.executeTransaction(graphId, List.of(
new AddNode(List.of("Person"), null, Map.of("name", "Ada")), // 0
new AddNode(List.of("Person"), null, Map.of("name", "Bob")), // 1
new AddEdge(EdgeEndpoint.operation(0), EdgeEndpoint.operation(1), "KNOWS", 0.9f, null),
new AddEdge(EdgeEndpoint.operation(0), EdgeEndpoint.node(companyId), "WORKS_AT", 1.0f, null)));
final long adaId = result.results().get(0).generatedId().orElseThrow();
All four apply or none do: if the company node does not exist, Ada and Bob are rolled back with the
edges. An index must point back at an earlier AddNode or UpsertNode; one that points forward, at
itself or at any other operation fails the transaction as invalid.
The same works as a single CyQL statement, which is often shorter:
INSERT (a:Person {name: 'Ada'})-[:KNOWS]→(b:Person {name: 'Bob'}) through executeStatement.
Edges to nodes known by key
When your nodes carry an external key of your own (upsertNode or UpsertNode.byKey), an endpoint can name
the node by that key instead of its id: EdgeEndpoint.key("person:42"). The server resolves the key when the
edge’s operation runs, so you skip reading the ids first, and the key also finds a node an earlier
UpsertNode of the same batch created:
client.executeTransaction(graphId, List.of(
UpsertNode.byKey("post:7", List.of("Post"), null, Map.of("title", "Hello")), // 0
new AddEdge(EdgeEndpoint.operation(0), EdgeEndpoint.key("person:42"), "HAS_CREATOR", 1.0f, null),
new AddEdge(EdgeEndpoint.key("forum:3"), EdgeEndpoint.key("post:7"), "CONTAINER_OF", 1.0f, null)));
A key no node holds fails the whole transaction as not found, naming the key. On a branch, which cannot upsert by key yet, a key finds only the keyed nodes the branch sees from its parent.
Errors
Everything the client throws is a CyrockDbClientException, an unchecked exception carrying the
server’s message and a status code. The code is always an HTTP status, never the gRPC status number
the transport uses underneath - a server that is not serving requests reads as 503, not as the 14 the
wire calls it. Do not read a retry rule off the number, though: some 4xx report the server’s condition
rather than a bad request - 429 while it sheds load, 409 on a conflict - so branch on the subtypes
instead:
try
{
client.getDocument(collectionId, externalKey);
}
catch (final CyrockDbClientException.NotFoundException e)
{
// The document is not there - for this caller that is an answer, not a failure.
}
catch (final CyrockDbClientException.RetryableException e)
{
// The server was unreachable, or it did not answer in time: resending can work.
retryWithBackoff();
}
catch (final CyrockDbClientException e)
{
System.err.println(e.getStatusCode() + " " + e.getMessage());
throw e;
}
The failures worth branching on have a subtype, so the decision does not have to be arithmetic on a status code:
| Subtype | Status | Thrown when |
|---|---|---|
|
404 |
The collection, graph, document or node does not exist |
|
403 |
Authenticated, but not permitted to do this |
|
401 |
Not authenticated, or the API key was refused |
|
503 |
The server could not be reached, or was reached but is not serving this request right now - a restart, a deployment, a dropped connection |
|
504 |
The call did not finish within its deadline |
|
409 |
The write committed and is visible, but the durability flush did not confirm |
UnavailableException and DeadlineExceededException extend RetryableException, which is the type to
catch when resending is the answer - or let the client resend for you, see Retrying while the server
comes back; with a retry policy, an UnavailableException from a
read means its retries ran out. A retryable failure says nothing about whether the request was applied -
a deadline can expire on a write the server goes on to commit - so a non-idempotent operation needs the
same care here as anywhere else.
DurabilityNotConfirmedException is the one worth handling deliberately, and the obvious reaction is
wrong. Do not retry it: the commit stands, so sending the request again applies it twice. The write is
already readable. What is unconfirmed is only whether it would survive a power loss, so the useful
responses are to verify it, to alert, or to reconsider the durability mode - not to repeat it. It is
deliberately not a RetryableException for that reason.
Anything without a subtype arrives as a plain CyrockDbClientException with its projected status - 400
for an invalid argument or a failed precondition, 409 for a conflict, 429 when the server is shedding
load, 500 for an internal failure, 501 for something this server does not implement.
Token expiry is not something to handle: the client re-exchanges automatically.
Graphs
The graph API mirrors the document one, with edges and traversal added:
String graphId = client.createGraph(projectId, graphDefinition).id();
long matrix = client.addNode(graphId,
List.of("Movie"), // labels
Map.of("embedding", VectorInput.of(vector)),
Map.of("title", "The Matrix"));
client.addEdge(graphId, AddEdgeRequest.builder()
.type("ACTED_IN").source(keanu).target(matrix).build());
List<Node> neighbours = client.neighbors(graphId, NeighborsRequest.builder()
.nodeId(matrix).edgeType("ACTED_IN").build());
Reads that return edges (neighborsGraph, contextWindowGraph, reasoningChainGraph, recallGraph,
inducedSubgraph) leave the edges' metadata out unless asked: each edge then has its id, type, endpoints and
weight, an empty metadata map and a createdAt of 0, and the server loads no edge to answer it. Set
includeEdgeMetadata(true) on the request, or pass it to inducedSubgraph, when you read edge properties:
NeighborsWindow window = client.neighborsGraph(graphId, NeighborsRequest.builder()
.nodeId(matrix).direction(Direction.INCOMING).includeEdgeMetadata(true).build());
To read many nodes you know by your own keys, getNodesByKeys(graphId, keys) resolves the whole set in one
call rather than one getNode(graphId, key) per key. A key no node holds is left out, and each node carries
its externalKey(), so you can map the result back:
Map<String, Long> ids = client.getNodesByKeys(graphId, List.of("person:1", "person:2")).stream()
.collect(Collectors.toMap(Node::externalKey, Node::id));
Nodes carry a list of labels, not one. Beyond a single hop, CyQL is clearer than assembling calls - see
CyQL. The client also covers traversal, context windows, graph branching, the Graph RAG
community operations and agentic memory; the full method list is on CyrockDbClient.
A complete example
This compiles and runs against the evaluation container as-is:
import ai.cyrock.db.client.java.CyrockDbClient;
import ai.cyrock.db.client.java.CyrockDbClientException;
import ai.cyrock.db.client.java.CyrockDbClientGrpc;
import ai.cyrock.db.data.Cardinality;
import ai.cyrock.db.data.CollectionDefinition;
import ai.cyrock.db.data.Match;
import ai.cyrock.db.data.MetadataFieldDefinition;
import ai.cyrock.db.data.MetadataFieldType;
import ai.cyrock.db.data.QueryParameters;
import ai.cyrock.db.data.SearchRequest;
import ai.cyrock.db.data.SimilarityFunction;
import ai.cyrock.db.data.StatementResult;
import ai.cyrock.db.data.VectorFieldDefinition;
import ai.cyrock.db.data.VectorInput;
import java.io.IOException;
import java.util.List;
import java.util.Map;
public final class Example
{
private static final int DIMENSION = 384;
public static void main(final String[] args) throws IOException
{
final String apiKey = System.getenv("CYROCK_DB_API_KEY");
final String projectId = System.getenv("CYROCK_DB_PROJECT_ID");
try (final CyrockDbClient client = CyrockDbClientGrpc.builder()
.apiKey(apiKey)
.build())
{
final CollectionDefinition definition = CollectionDefinition.builder()
.name("sdk-example")
.vectorFields(List.of(VectorFieldDefinition.builder()
.name("vector")
.dimension(DIMENSION)
.similarityFunction(SimilarityFunction.COSINE)
.build()))
.metadataFields(List.of(
new MetadataFieldDefinition("title", MetadataFieldType.STRING, Cardinality.HIGH, false, false),
new MetadataFieldDefinition("topic", MetadataFieldType.STRING, Cardinality.LOW, false, false)))
.build();
final String collectionId = client.createCollection(projectId, definition).id();
final float[] embedding = new float[DIMENSION];
embedding[0] = 1.0f;
client.upsertDocument(
collectionId,
"how-to-reset-a-password",
Map.of("vector", VectorInput.of(embedding)),
Map.of("title", "Resetting a password", "topic", "accounts"));
final List<Match> matches = client.search(collectionId,
SearchRequest.builder("vector", embedding, 5)
.filter("topic = \"accounts\"")
.build());
System.out.println("matches: " + matches.size());
final StatementResult result = client.executeCollectionStatement(
collectionId,
"MATCH (d) WHERE d.topic = $topic RETURN d.title",
QueryParameters.builder().param("topic", "accounts").build());
System.out.println("rows: " + result.rows());
}
catch (final CyrockDbClientException e)
{
System.err.println("failed: " + e.getMessage());
}
}
}
Set CYROCK_DB_API_KEY and CYROCK_DB_PROJECT_ID from the startup banner and run it. Nothing else is
needed - no port, no token handling, no configuration file.
See also
-
Getting started - standing up a server
-
Python SDK - the same API for Python
-
REST API - the language-agnostic surface
-
CyQL - the query language