Spice Java SDK v0.8.0

What's New

🔎 Search

search() finds documents similar to a piece of text via the runtime's /v1/search endpoint (vector, keyword, and hybrid search), for datasets with an embedding column and a loaded embedding model.

SearchResponse response = client.search(
    new SearchRequest("delayed flights to Seattle")
        .withDatasets(List.of("flight_reviews"))
        .withLimit(5));

for (SearchMatch match : response.getResults()) {
    System.out.println(match.getDataset() + ": " + match.getScore());
}

🗣️ Natural Language to SQL (Nsql)

nsql() translates a natural-language query into SQL via the runtime's configured LLM and runs it, returning the rows alongside the generated SQL. nsqlGenerateSql() generates the SQL without running it — inspect or edit it, or run it through sql()/sqlWithParams() for Arrow-typed results instead of nsql()'s decoded JSON rows.

NsqlResponse response = client.nsql(new NsqlRequest("how many trips were over 10 miles?"));
System.out.println(response.getSql());
System.out.println(response.getData());

String sql = client.nsqlGenerateSql(new NsqlRequest("how many trips were over 10 miles?"));

⏳ Async Queries

query()/queryWithParams() submit a query for asynchronous execution and return an AsyncQuery handle instead of streaming results directly. This requires the Spice runtime to be running in distributed/scheduler mode; for the normal synchronous, streaming path use sql()/sqlWithParams().

AsyncQuery asyncQuery = client.query("SELECT * FROM taxi_trips LIMIT 10;");

try (ArrowReader reader = asyncQuery.results()) { // blocks until the query completes
    while (reader.loadNextBatch()) {
        System.out.println(reader.getVectorSchemaRoot().contentToTSVString());
    }
}

The AsyncQuery handle also exposes status() for a single poll, waitForCompletion(Duration) to bound how long a wait can take, and cancel() to request cancellation.

📋 Active Query Management

listActiveQueries() reports the synchronous queries currently running on the runtime, and cancelActiveQuery(queryId) cancels one. The runtime doesn't hand a query's ID back to the client that submitted it, so listing is the only way to find the ID that cancelling needs.

List<ActiveQuery> queries = client.listActiveQueries();
for (ActiveQuery query : queries) {
    System.out.printf("%s %s %s%n",
        query.getQueryId(), query.getProtocol(), query.getSqlPreview());
}

if (!queries.isEmpty()) {
    client.cancelActiveQuery(queries.get(0).getQueryId());
}

Breaking Changes

query() and queryWithParams() now submit SQL for asynchronous execution and return an AsyncQuery handle, instead of streaming results directly. The previous synchronous, streaming behavior is now sql()/sqlWithParams():

// Before (v0.7.0 and earlier)
FlightStream stream = client.query("SELECT * FROM taxi_trips");

// After (v0.8.0)
FlightStream stream = client.sql("SELECT * FROM taxi_trips");

Async queries additionally require the runtime to be running in distributed/scheduler mode; calling query()/queryWithParams() against a single-node runtime now returns an error explaining that, rather than the query results.

Everything else in this release is additive: search(), nsql()/nsqlGenerateSql(), and listActiveQueries()/cancelActiveQuery() are all new methods; nothing else existing was renamed, removed, or retyped.

Compatibility

• No new dependencies.