Framework connectors
Two connectors plug CYROCK.AI DB into the JVM AI frameworks: a Spring AI VectorStore and a
LangChain4j EmbeddingStore. An application already built on either one keeps the interfaces it
already targets and changes only its wiring.
Both are written against the Java SDK and nothing else, so there is nothing in them you could not do by hand. What they save you is the mapping.
Both assume the collection or graph already exists. They read and write; they do not create or alter schema. Creating the collection says what it has to look like.
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 whichever connector you need:
<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-spring-ai</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
For LangChain4j the artifact is cyrock-db-langchain4j at the same version. Either one brings
cyrock-db-client-java with it, so you do not declare the SDK separately. Both are also managed by
the SDK BOM, so if you import that - see Java SDK - you can
leave the <version> off.
The id in settings.xml and in <repositories> must match - that is how Maven knows which
credentials to send. Both connectors need Java 21.
Neither connector brings its framework. They are compiled against Spring AI 2.0.0 on Spring Boot 4.1.0 and LangChain4j 1.17.1, and the framework itself stays whatever your build resolves - which is what you want when your application already manages it. Spring AI 2.0 needs Spring Boot 4, so an application still on Boot 3 has to move first.
Creating the collection
Both connectors write into a collection that already exists, and they are strict about it because the engine is: metadata in CYROCK.AI DB is declared, and an undeclared field name is rejected on write rather than stored loosely. Three things have to line up.
-
The vector field’s dimension must match your embedding model - 384 for the in-process embedder, 1536 for a
text-embedding-3-small, and so on. It is fixed once the field exists. -
The content field must be declared. Both connectors keep the document text in a metadata field,
contentby default. It is an ordinarySTRINGfield. -
Every metadata key you pass through the framework must be declared too. A Spring AI
Document’s metadata map and a LangChain4j `TextSegment’s `Metadataboth arrive as CYROCK.AI DB metadata, so a key nobody declared fails the write.
CollectionDefinition definition = CollectionDefinition.builder()
.name("support-articles")
.vectorFields(List.of(VectorFieldDefinition.builder()
.name("vector")
.dimension(384)
.similarityFunction(SimilarityFunction.COSINE)
.build()))
.metadataFields(List.of(
new MetadataFieldDefinition("content", MetadataFieldType.STRING, Cardinality.HIGH, true, 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). Declaring content
with fulltext set is what makes the full-text and hybrid retrieval modes below available on it; a
purely vector setup does not need it. Java SDK has the rest of
the schema surface - or create the collection from the console or in
CyQL. The connectors do not care which.
Spring AI
The vector store
CyrockVectorStore implements org.springframework.ai.vectorstore.VectorStore. Build it from a
connected client and the EmbeddingModel your application already has:
import ai.cyrock.db.client.java.CyrockDbClient;
import ai.cyrock.db.client.java.CyrockDbClientGrpc;
import ai.cyrock.db.springai.CyrockVectorStore;
import org.springframework.ai.vectorstore.VectorStore;
CyrockDbClient client = CyrockDbClientGrpc.builder()
.apiKey(apiKey)
.build();
VectorStore store = CyrockVectorStore.builder()
.client(client)
.embeddingModel(embeddingModel)
.collectionId(collectionId)
.build();
client, embeddingModel and collectionId are required. vectorField and contentField default
to vector and content; set them if your collection names them differently. From there it is the
interface you already know:
store.add(List.of(
Document.builder().id("reset-password")
.text("Reset a password from the account settings page.")
.metadata(Map.of("topic", "accounts")).build(),
Document.builder().id("invoice-schedule")
.text("Invoices are issued on the first of the month.")
.metadata(Map.of("topic", "billing")).build()));
List<Document> hits = store.similaritySearch(SearchRequest.builder()
.query("how do I change my password")
.topK(5)
.similarityThreshold(0.5)
.filterExpression("topic == 'accounts'")
.build());
for (final Document hit : hits)
{
System.out.println(hit.getScore() + " " + hit.getText());
}
add embeds each document with your EmbeddingModel and upserts it, so re-adding the same id
replaces rather than duplicates. similaritySearch embeds the query, runs an
approximate-nearest-neighbour search and drops anything below similarityThreshold. The filter is
applied before ranking, so a narrow filter still returns a full topK.
Deletes come in two shapes:
store.delete(List.of("reset-password"));
store.delete(new FilterExpressionBuilder().eq("topic", "billing").build());
Deleting by id removes the documents you added under those ids. Deleting by filter compiles the
expression to a CyQL DELETE and applies it server-side, so it is one round trip however many
documents match. Deleting something that is not there is not an error.
What the filter converter covers
CyqlFilterExpressionConverter renders a Spring AI Filter.Expression tree into a CyQL filter
string. It covers the comparisons =, !=, <, ⇐, >, >=, set membership IN and NOT IN,
the null checks IS NULL and IS NOT NULL, and AND, OR, NOT with grouping. Dates and times
become CyQL literals at second precision, and an offset or zoned value is rendered as its UTC
instant.
Two things it deliberately refuses. A metadata key that is not a plain identifier is rejected rather
than concatenated into the statement, which is what closes off query injection through a crafted
key. And an expression type CyQL has no equivalent for raises IllegalArgumentException at call
time, rather than producing a filter that quietly means something else.
Spring Boot auto-configuration
Set the collection id and the rest wires itself:
spring.ai.vectorstore.cyrock.collection-id=<the collection id>
spring.ai.vectorstore.cyrock.api-key=<the key from the startup banner>
Property, under spring.ai.vectorstore.cyrock |
Default | Meaning |
|---|---|---|
|
empty |
The collection to read and write. Setting it is what activates the auto-configuration |
|
|
Hostname of the client gateway |
|
|
The client gateway port, which fronts both the data and platform planes |
|
empty |
Exchanged for a short-lived token and attached to every call |
|
|
|
|
|
The vector field written and searched |
|
|
The metadata field holding the document text |
|
empty |
Set it to activate the Graph RAG advisor below |
With collection-id unset the auto-configuration contributes nothing at all, so adding the
dependency to an application that is not ready to use it changes nothing.
It contributes a connected CyrockDbClient unless your application already defines one. Defining
your own @Bean is the way to reach client options these properties do not cover - a call timeout,
custom credentials - and the auto-configuration then uses yours. The VectorStore bean needs an
EmbeddingModel bean to be present; without one there is nothing to embed with and no store is
created.
Grounding a chat client in a graph
A VectorStore can only hand back the nearest passages. CyrockGraphRagAdvisor is a ChatClient
advisor that instead embeds the question, runs a global search over a graph’s community summaries,
and prepends what it finds to the user message. That answers "what are the recurring themes here",
which no nearest-neighbour lookup expresses. See Concepts for what a community
summary is.
ChatClient chatClient = ChatClient.builder(chatModel)
.defaultAdvisors(CyrockGraphRagAdvisor.builder()
.client(client)
.embeddingModel(embeddingModel)
.graphId(graphId)
.topK(5)
.build())
.build();
String answer = chatClient.prompt("What are the recurring themes in these incidents?")
.call()
.content();
It searches every level of the community hierarchy, and if the graph holds no summaries yet it leaves the request untouched rather than failing - so detect communities and store their summaries first, or the advisor is a silent no-op.
Setting spring.ai.vectorstore.cyrock.graph-id contributes the same advisor as a bean. One thing to
know if you do: the advisor takes its vector field from vector-field, the same property the vector
store uses. If your graph names that field differently from your collection, build the advisor
yourself rather than letting the properties configure it.
Health
With Spring Boot Actuator on the classpath the auto-configuration also contributes a health
indicator that reads the configured collection. A reachable server holding it reports UP with the
collection name; anything else reports DOWN with a stable reason, and the underlying failure goes
to the log rather than out of the endpoint. That turns a wrong collection id or a wrong endpoint
into a readiness failure instead of a surprise on the first search.
LangChain4j
The embedding store
CyrockEmbeddingStore implements dev.langchain4j.store.embedding.EmbeddingStore<TextSegment>.
LangChain4j keeps embedding outside the store, so this one takes no EmbeddingModel: you embed, it
stores.
import ai.cyrock.db.langchain4j.CyrockEmbeddingStore;
EmbeddingStore<TextSegment> store = CyrockEmbeddingStore.builder()
.client(client)
.collectionId(collectionId)
.build();
TextSegment segment = TextSegment.from(
"Reset a password from the account settings page.",
Metadata.from("topic", "accounts"));
String id = store.add(embeddingModel.embed(segment).content(), segment);
For ingest, reach for addAll(List<Embedding>, List<TextSegment>): it goes out as one batch upsert
rather than a call per segment.
Search honours maxResults, minScore and the metadata Filter:
import static dev.langchain4j.store.embedding.filter.MetadataFilterBuilder.metadataKey;
EmbeddingSearchResult<TextSegment> result = store.search(EmbeddingSearchRequest.builder()
.queryEmbedding(embeddingModel.embed("how do I change my password").content())
.maxResults(5)
.minScore(0.5)
.filter(metadataKey("topic").isEqualTo("accounts"))
.build());
for (final EmbeddingMatch<TextSegment> match : result.matches())
{
System.out.println(match.score() + " " + match.embedded().text());
}
removeAll(Collection<String>) removes by id, removeAll(Filter) compiles the filter to a CyQL
DELETE and applies it in one round trip, and removeAll() empties the collection. Removing
something absent is not an error.
CyqlFilterMapper renders the LangChain4j filter tree: the comparisons, IsIn and IsNotIn,
ContainsString - which becomes CyQL CONTAINS, a case-insensitive substring match on a string
field and element membership on a list field - and And, Or, Not. As on the Spring AI side, a
metadata key that is not a plain identifier is refused rather than concatenated in.
Retrieving content for AiServices
ContentRetriever is the interface AiServices actually consumes for RAG, so this is usually the
class you want rather than the store. CyrockContentRetriever has three modes, chosen by what you
give the builder:
| Configured with | Mode |
|---|---|
|
Vector. The model embeds the query |
|
Full-text. BM25 on that field, with no embedding backend at all |
both |
Hybrid. Both run, fused with reciprocal-rank fusion |
ContentRetriever retriever = CyrockContentRetriever.builder()
.client(client)
.collectionId(collectionId)
.embeddingModel(embeddingModel)
.textField("content")
.maxResults(5)
.build();
Assistant assistant = AiServices.builder(Assistant.class)
.chatModel(chatModel)
.contentRetriever(retriever)
.build();
String answer = assistant.chat("how do I change my password");
Giving it neither an embeddingModel nor a textField fails at build time - there would be nothing
to search with. The full-text mode is the one worth remembering: it needs no embedding provider and
no network, so a keyword-shaped question can be served by a pipeline with no embedding model
configured. textField has to be a STRING field declared with fulltext.
maxResults defaults to 3, matching LangChain4j’s own retrievers, which is usually too few once
your documents run longer than a paragraph.
Retrieving a graph context window
CyrockGraphContentRetriever is also a ContentRetriever, but it retrieves from a graph: it embeds
the query, seeds a vector search on the graph’s nodes, then expands out along the edges to a
configured depth. What comes back is a context window - the matching nodes together with their
related neighbours - which is graph traversal inside an AiServices pipeline.
ContentRetriever retriever = CyrockGraphContentRetriever.builder()
.client(client)
.graphId(graphId)
.embeddingModel(embeddingModel)
.vectorField("embedding")
.contentField("content")
.maxResults(5)
.depth(2)
.build();
maxResults is how many seed nodes the vector search returns, not how much content comes back:
each seed drags in its neighbourhood, so the amount of text grows with depth. It defaults to 5,
and depth defaults to 1. Start there and raise it deliberately - depth 3 on a well-connected graph
returns a great deal of text to answer one question with.
A node contributes only if it carries the content field. Nodes without it are skipped rather than returned empty.
Document ids
Worth reading once, because there are two id spaces and the difference surprises people.
CYROCK.AI DB numbers documents internally, and a search response carries that internal id rather than the key you supplied.
-
Spring AI always adds under an id. A
Documentcarries one, generated for you if you did not set it, and it becomes the CYROCK.AI DB external key - sodelete(List<String>)takes the ids you added with. A null or blank id is refused rather than quietly replaced. -
LangChain4j adds both ways.
add(embedding),add(embedding, segment)andaddAll(embeddings, segments)let CYROCK.AI DB assign the id and return it.add(id, embedding)andaddAll(ids, embeddings, segments)store your id as the external key instead. -
Search returns the internal id either way. A document added under your own key comes back from a search carrying the internal id, not that key. If you need to correlate a hit with a record of your own, keep the key in the metadata as well and read it off there.
-
Removal accepts either form. A numeric id is tried as an internal id first and falls back to an external key; a non-numeric id is always an external key.
What the connectors do not do
-
No schema creation. Neither creates or alters a collection or a graph, and neither adds a vector field. A missing collection is a 404 on the first call; an undeclared metadata field is a rejected write.
-
Blocking only. Both call the synchronous SDK surface, because the framework interfaces they implement are synchronous. The asynchronous client is there when you want calls in flight, but you drive it yourself.
-
Errors arrive as the SDK’s. A failure surfaces as
CyrockDbClientExceptionwith an HTTP status code rather than as a framework exception type. Java SDK has the subtypes worth branching on. -
One collection or one graph each. An instance is bound to the id it was built with. Point at several by building several.
See also
-
Java SDK - the surface both connectors are built on
-
Concepts - collections, graphs, vector fields and communities
-
CyQL - the filter grammar the converters emit
-
Web console - creating the collection without writing code