synapcores-java — Java SDK + Spring Boot starter for SynapCores AIDB

Official Java SDK for SynapCores — the AI-native database that runs SQL, vectors, RAG, and the in-database agentic runtime from a single engine.

Two artifacts:

Artifact	What it is	For
com.synapcores:synapcores-sdk	Framework-agnostic Java SDK	Any JVM project — vanilla Java, Kotlin, Quarkus, Micronaut, etc.
com.synapcores:synapcores-spring-boot-starter	Spring Boot 3.x auto-config	Spring Boot 3 apps — facade, properties, health indicator

Requirements

• JDK 17+
• Maven 3.6+ or Gradle 7+
• A running SynapCores engine — free Community Edition: docker run -d -p 28080:8080 ghcr.io/synapcores/community:latest

Install

Maven

<dependency>
    <groupId>com.synapcores</groupId>
    <artifactId>synapcores-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

<!-- Spring Boot users: -->
<dependency>
    <groupId>com.synapcores</groupId>
    <artifactId>synapcores-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

implementation("com.synapcores:synapcores-sdk:1.0.0")
implementation("com.synapcores:synapcores-spring-boot-starter:1.0.0")  // Spring Boot users

Quickstart — vanilla Java

import com.synapcores.sdk.SynapCores;
import com.synapcores.sdk.result.QueryResult;

import java.util.Map;

public class Quickstart {
    public static void main(String[] args) {
        SynapCores sc = SynapCores.builder()
            .host("localhost").port(8080)
            .apiKey(System.getenv("AIDB_API_KEY"))   // aidb_… or ak_…
            .build();

        QueryResult r = sc.sql("SELECT name FROM users WHERE id = :id",
            Map.of("id", 42));
        for (Map<String, Object> row : r) {
            System.out.println(row.get("name"));
        }
    }
}

Quickstart — Spring Boot

Add this to application.yml:

synapcores:
  host: localhost
  port: 8080
  api-key: ${AIDB_API_KEY}
  # OR (for the JWT login flow):
  # username: admin
  # password: ${AIDB_PASSWORD}
  timeout: 30s

Then inject the bean anywhere:

@Service
public class CustomerService {
    private final SynapCores sc;

    public CustomerService(SynapCores sc) {   // auto-injected
        this.sc = sc;
    }

    public List<Customer> recentSignups() {
        return sc.sql("SELECT * FROM customers WHERE created_at > :cutoff",
                Map.of("cutoff", Instant.now().minus(7, ChronoUnit.DAYS)))
            .rows().stream()
            .map(Customer::from)
            .toList();
    }
}

What's in the box

Method	Sync	Async	What it does
sql(sql, params)	✓	sqlAsync	Run SQL via /v1/query/execute. :name placeholders inlined client-side.
embed(text)	✓	—	SELECT EMBED(...) — returns double[].
ragSearch(query, opts)	✓	—	Top-K similar rows from a table with a VECTOR column.
agentRun(persona, task, opts)	✓	—	Fire AGENT_RUN() — the in-DB agentic runtime.
importRecipe(url)	✓	—	Import a recipe by URL.
execRecipe(id, params)	✓	—	Execute an imported recipe.
knnSearch(table, vec, k, opts)	✓	—	KNN against a VECTOR column with a literal query vector.
login(user, pass)	✓	—	Exchange credentials for a JWT (only needed without apiKey).

Async variants for the other read methods land in v1.1 if there's signal — sqlAsync is shipped now to validate the CompletableFuture pattern.

Errors

Every error is a SynapCoresException subclass — runtime, no checked-exception soup:

try {
    QueryResult r = sc.sql(badSql, params);
} catch (QueryException qe) {
    log.warn("engine rejected at {} (status {}): {}",
        qe.endpoint(), qe.statusCode(), qe.getMessage());
} catch (AuthException ae) {
    // refresh token, retry…
} catch (NetworkException ne) {
    // backoff…
}

Hierarchy: SynapCoresException ← AuthException / QueryException / NetworkException / EnvelopeException.

Parameter binding — how it actually works

The engine's /v1/query/execute route does not parse :name, ?, or $1 placeholders server-side. The SDK substitutes :name placeholders client-side with proper SQL escaping (single-quote doubling, backslash escape, NULL/TRUE/FALSE literals, [1,2,3] vector literals for float[] / double[] / int[] / long[] / Collection<Number>).

What goes over the wire is fully inlined SQL — the request body never contains a params field. This means:

• Map<String, Object> is the supported params shape.
• Untrusted user input is safe when passed through params — the SDK escapes it. Never string-concatenate user input into the SQL.
• A :name in the SQL with no matching key throws QueryException — fail-fast.

// SAFE — single quotes in the value get doubled correctly
sc.sql("SELECT * FROM users WHERE name = :n", Map.of("n", "O'Brien"));

// SAFE — vector becomes [0.1,0.2,0.3]
sc.sql("INSERT INTO docs (id, embedding) VALUES (:id, :v)",
    Map.of("id", 1, "v", new float[]{0.1f, 0.2f, 0.3f}));

Spring Boot — health indicator + metrics

The starter ships an optional Actuator health indicator. It registers automatically when Actuator is on the classpath; no extra config required. Toggle it via:

management:
  health:
    synapcores:
      enabled: true

When healthy, /actuator/health/synapcores returns:

{"status":"UP", "details": {"scalar": "1"}}

Micrometer integration is on the roadmap for v1.1.

Configuration reference

All synapcores.* properties bind to SynapCoresProperties:

Property	Default	Notes
synapcores.host	localhost
synapcores.port	8080
synapcores.use-https	false	Set true in prod
synapcores.api-key	—	aidb_… or ak_… Bearer key (recommended)
synapcores.token	—	Pre-obtained JWT (skip login)
synapcores.username	—	For the login() flow
synapcores.password	—	For the login() flow
synapcores.timeout	30s	Per-request timeout
synapcores.database	—	Sets X-Database header
synapcores.tenant	—	Sets X-Tenant header
synapcores.auto-login	true	Auto-call login() on bean creation if username+password are set and no apiKey/token

Engine compatibility

Tested live against SynapCores AIDB v1.7.0.2.1-ce (image ghcr.io/synapcores/community:latest). The SDK targets the stable /v1/* REST surface — minor engine releases should not break it.

Building from source

git clone https://github.com/SynapCores/synapcores-java.git
cd synapcores-java

mvn -B test                       # unit tests (default — fast)
mvn -B test -Dexcluded.groups= -Dgroups=integration \
    -DSYNAPCORES_HOST=127.0.0.1   # live integration tests

License

MIT — see LICENSE.