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, recall and globalSearch, 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 LOGIN in 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 a LOGIN event 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 maxAttempts attempts, five at most and by default. Before retry n it waits a random time between zero and initialBackoff * backoffMultiplier^(n-1), capped at maxBackoff: 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 callTimeout with 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

executeCollectionStatement(collectionId, …​)

One collection

executeStatement(graphId, …​)

One graph

executeProjectStatement(projectId, …​)

Project-wide DDL - CREATE COLLECTION, SHOW COLLECTIONS

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.

Which to use

Both APIs are the same operations against the same server, and mixing them on one client is fine. Reach for the asynchronous one when calls overlap; the blocking one reads better when they do not.

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

NotFoundException

404

The collection, graph, document or node does not exist

ForbiddenException

403

Authenticated, but not permitted to do this

UnauthorizedException

401

Not authenticated, or the API key was refused

UnavailableException

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

DeadlineExceededException

504

The call did not finish within its deadline

DurabilityNotConfirmedException

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