From cd0e24cfa025fba48b6ffe2280bcd4f1fd9709eb Mon Sep 17 00:00:00 2001 From: Viktor Yershov Date: Wed, 19 Aug 2026 14:07:27 -0700 Subject: [PATCH 1/7] release: prepare v0.8.0 Bumps pom.xml/Version.java to 0.8.0 and adds release notes covering the four additive feature PRs (#53-#56): search, Nsql/NsqlGenerateSql, active-query management, and async queries. japicmp.oldVersion stays at 0.6.0 rather than bumping to 0.7.0: v0.7.0 was tagged and GitHub-released but its Maven Central publish never completed, so it isn't a resolvable dependency. See the pom.xml comment for detail. --- docs/release_notes/v0.8.0.md | 85 +++++++++++++++++++++++++++++ pom.xml | 16 +++++- src/main/java/ai/spice/Version.java | 2 +- 3 files changed, 100 insertions(+), 3 deletions(-) create mode 100644 docs/release_notes/v0.8.0.md diff --git a/docs/release_notes/v0.8.0.md b/docs/release_notes/v0.8.0.md new file mode 100644 index 0000000..25a2adc --- /dev/null +++ b/docs/release_notes/v0.8.0.md @@ -0,0 +1,85 @@ +# Spice Java SDK v0.8.0 + +## Highlights + +v0.8.0 is a **feature-parity release**, closing the four gaps between this SDK and its siblings (gospice, spice-rs, spicepy, spice.js): search, natural-language-to-SQL, active-query management, and asynchronous queries. All four are purely additive — no existing public API changes shape or behavior, and no dependency changes. + +Unlike gospice and spice-rs, which made their async-query addition a breaking change (repurposing `Query`/`QueryWithParams` to submit asynchronously), this SDK adds it as new, separate methods — `queryAsync`/`queryAsyncWithParams` — so `query()`/`queryWithParams()` keep their existing synchronous, streaming behavior unchanged. This SDK enforces binary/source API compatibility via a `japicmp` CI gate; a rename would have broken it deliberately, and there was no forcing reason (like Go's module-path major-version rule) to accept that cost here. + +## 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. + +```java +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 `query()`/`queryWithParams()` for Arrow-typed results instead of `nsql()`'s decoded JSON rows. + +```java +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?")); +``` + +### 📋 Active Query Management + +`listActiveQueries()` lists 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 discover the ID cancellation needs. + +```java +for (ActiveQuery query : client.listActiveQueries()) { + System.out.printf("%s %s %s%n", query.getQueryId(), query.getProtocol(), query.getSqlPreview()); +} + +client.cancelActiveQuery(queryId); +``` + +Both calls are scoped to the authenticated API key or client certificate, not to the `SpiceClient` instance, and reach only the one runtime process behind the client's HTTP endpoint. Runtime releases up to and including v2.1.5 don't scope either endpoint by credential at all. + +### ⏳ Async Queries + +`queryAsync(sql)` / `queryAsyncWithParams(sql, params...)` submit a query for asynchronous execution and return an `AsyncQuery` handle, requiring the runtime to be running in distributed/scheduler mode. Use the existing `query()`/`queryWithParams()` for the normal synchronous, streaming path. + +```java +AsyncQuery job = client.queryAsync("SELECT * FROM large_table"); +ArrowReader results = job.results(); // waits for completion, then streams results + +// Or poll manually: +QueryStatus status = job.status(); +job.waitForCompletion(Duration.ofMinutes(5)); +job.cancel(); +``` + +## Testing + +- New unit test suites (`SearchTest`, `NsqlTest`, `ActiveQueriesTest`, `AsyncQueryTest`) covering request/response shape, validation, error handling, and — for async queries — multi-chunk result pagination and the empty-result edge case, all against local mock servers with no live runtime required. +- `TestFlightSqlServer` gained `DoAction` support for the four async-query actions, additive to its existing Flight SQL mocking. + +## Compatibility + +- Public API unchanged: all four features are new methods; nothing existing was renamed, removed, or retyped. +- No new dependencies. + +## Release status + +This release is not yet cut. It depends on four open PRs merging first: + +- [#53](https://github.com/spiceai/spice-java/pull/53) — `listActiveQueries()`/`cancelActiveQuery()` +- [#54](https://github.com/spiceai/spice-java/pull/54) — `search()` +- [#55](https://github.com/spiceai/spice-java/pull/55) — `nsql()`/`nsqlGenerateSql()` +- [#56](https://github.com/spiceai/spice-java/pull/56) — `queryAsync()`/`queryAsyncWithParams()` + +It's also worth resolving before or alongside this release: **v0.7.0 was tagged and GitHub-released but was never actually published to Maven Central** — the Sonatype deployment was staged and validated but never taken out of "pending manual publish" (`maven-metadata.xml` on Maven Central still lists `0.6.0` as ``). `pom.xml`'s `japicmp.oldVersion` is deliberately left at `0.6.0` rather than bumped to `0.7.0` for this reason — see the comment in `pom.xml` for detail. diff --git a/pom.xml b/pom.xml index 3439d79..4e9b3c7 100644 --- a/pom.xml +++ b/pom.xml @@ -4,7 +4,7 @@ ai.spice spiceai jar - 0.7.0 + 0.8.0 Java Spice SDK https://github.com/spiceai/spice-java/ Spice provides a unified SQL query interface and portable runtime to locally materialize, accelerate, and query datasets from any database, data warehouse, or data lake. @@ -45,7 +45,19 @@ + fails if this still equals the version being released. + + Deliberately still 0.6.0, not 0.7.0: v0.7.0 was tagged and + GitHub-released, but its Maven Central publish never completed + (the Sonatype deployment was staged and validated but never + taken out of "pending manual publish"; see maven-metadata.xml + at repo1.maven.org, which still lists 0.6.0 as ). japicmp + resolves this version as a real Maven dependency, so pointing it + at an unpublished 0.7.0 would break dependency resolution for + every PR, not just report a compatibility diff. Bump this to + 0.7.0 once it's actually published, or skip it entirely and move + straight to 0.8.0 as the successor to 0.6.0 if 0.7.0 is + abandoned. --> 0.6.0 diff --git a/src/main/java/ai/spice/Version.java b/src/main/java/ai/spice/Version.java index 2964cda..51fd5c9 100644 --- a/src/main/java/ai/spice/Version.java +++ b/src/main/java/ai/spice/Version.java @@ -30,6 +30,6 @@ public class Version { public static final String SPICE_JAVA_VERSION; static { - SPICE_JAVA_VERSION = "0.7.0"; + SPICE_JAVA_VERSION = "0.8.0"; } } From d75be359869f57e0b4f83cd1980118ad5fb4a465 Mon Sep 17 00:00:00 2001 From: Viktor Yershov Date: Wed, 19 Aug 2026 15:21:05 -0700 Subject: [PATCH 2/7] docs: reflect that #54 (search) and #55 (nsql) have merged --- docs/release_notes/v0.8.0.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/release_notes/v0.8.0.md b/docs/release_notes/v0.8.0.md index 25a2adc..bb5e165 100644 --- a/docs/release_notes/v0.8.0.md +++ b/docs/release_notes/v0.8.0.md @@ -75,11 +75,9 @@ job.cancel(); ## Release status -This release is not yet cut. It depends on four open PRs merging first: +`search()` ([#54](https://github.com/spiceai/spice-java/pull/54)) and `nsql()`/`nsqlGenerateSql()` ([#55](https://github.com/spiceai/spice-java/pull/55)) have merged to trunk. This release still depends on two open PRs: - [#53](https://github.com/spiceai/spice-java/pull/53) — `listActiveQueries()`/`cancelActiveQuery()` -- [#54](https://github.com/spiceai/spice-java/pull/54) — `search()` -- [#55](https://github.com/spiceai/spice-java/pull/55) — `nsql()`/`nsqlGenerateSql()` - [#56](https://github.com/spiceai/spice-java/pull/56) — `queryAsync()`/`queryAsyncWithParams()` It's also worth resolving before or alongside this release: **v0.7.0 was tagged and GitHub-released but was never actually published to Maven Central** — the Sonatype deployment was staged and validated but never taken out of "pending manual publish" (`maven-metadata.xml` on Maven Central still lists `0.6.0` as ``). `pom.xml`'s `japicmp.oldVersion` is deliberately left at `0.6.0` rather than bumped to `0.7.0` for this reason — see the comment in `pom.xml` for detail. From e1720d0886c113430b108485e8c0a2a50e05be6e Mon Sep 17 00:00:00 2001 From: Viktor Yershov Date: Wed, 19 Aug 2026 15:37:36 -0700 Subject: [PATCH 3/7] docs: scope v0.8.0 to search + nsql only #53 (active queries) and #56 (async queries) will not merge for this release; remove them from the release notes' What's New and reflect that in Release status instead of listing them as still-pending dependencies. --- docs/release_notes/v0.8.0.md | 43 ++++++++---------------------------- 1 file changed, 9 insertions(+), 34 deletions(-) diff --git a/docs/release_notes/v0.8.0.md b/docs/release_notes/v0.8.0.md index bb5e165..af5334e 100644 --- a/docs/release_notes/v0.8.0.md +++ b/docs/release_notes/v0.8.0.md @@ -2,9 +2,9 @@ ## Highlights -v0.8.0 is a **feature-parity release**, closing the four gaps between this SDK and its siblings (gospice, spice-rs, spicepy, spice.js): search, natural-language-to-SQL, active-query management, and asynchronous queries. All four are purely additive — no existing public API changes shape or behavior, and no dependency changes. +v0.8.0 is a **feature-parity release**, closing two of the four gaps between this SDK and its siblings (gospice, spice-rs, spicepy, spice.js): search and natural-language-to-SQL. Both are purely additive — no existing public API changes shape or behavior, and no dependency changes. -Unlike gospice and spice-rs, which made their async-query addition a breaking change (repurposing `Query`/`QueryWithParams` to submit asynchronously), this SDK adds it as new, separate methods — `queryAsync`/`queryAsyncWithParams` — so `query()`/`queryWithParams()` keep their existing synchronous, streaming behavior unchanged. This SDK enforces binary/source API compatibility via a `japicmp` CI gate; a rename would have broken it deliberately, and there was no forcing reason (like Go's module-path major-version rule) to accept that cost here. +Active-query management and asynchronous queries were also implemented for this cycle ([#53](https://github.com/spiceai/spice-java/pull/53), [#56](https://github.com/spiceai/spice-java/pull/56)) but are **not included in v0.8.0** — those PRs will not be merged for this release. See "Release status" below. ## What's New @@ -35,49 +35,24 @@ System.out.println(response.getData()); String sql = client.nsqlGenerateSql(new NsqlRequest("how many trips were over 10 miles?")); ``` -### 📋 Active Query Management - -`listActiveQueries()` lists 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 discover the ID cancellation needs. - -```java -for (ActiveQuery query : client.listActiveQueries()) { - System.out.printf("%s %s %s%n", query.getQueryId(), query.getProtocol(), query.getSqlPreview()); -} - -client.cancelActiveQuery(queryId); -``` - -Both calls are scoped to the authenticated API key or client certificate, not to the `SpiceClient` instance, and reach only the one runtime process behind the client's HTTP endpoint. Runtime releases up to and including v2.1.5 don't scope either endpoint by credential at all. - -### ⏳ Async Queries - -`queryAsync(sql)` / `queryAsyncWithParams(sql, params...)` submit a query for asynchronous execution and return an `AsyncQuery` handle, requiring the runtime to be running in distributed/scheduler mode. Use the existing `query()`/`queryWithParams()` for the normal synchronous, streaming path. - -```java -AsyncQuery job = client.queryAsync("SELECT * FROM large_table"); -ArrowReader results = job.results(); // waits for completion, then streams results - -// Or poll manually: -QueryStatus status = job.status(); -job.waitForCompletion(Duration.ofMinutes(5)); -job.cancel(); -``` - ## Testing -- New unit test suites (`SearchTest`, `NsqlTest`, `ActiveQueriesTest`, `AsyncQueryTest`) covering request/response shape, validation, error handling, and — for async queries — multi-chunk result pagination and the empty-result edge case, all against local mock servers with no live runtime required. -- `TestFlightSqlServer` gained `DoAction` support for the four async-query actions, additive to its existing Flight SQL mocking. +- New unit test suites (`SearchTest`, `NsqlTest`) covering request/response shape, validation, and error handling, all against local mock servers with no live runtime required. ## Compatibility -- Public API unchanged: all four features are new methods; nothing existing was renamed, removed, or retyped. +- Public API unchanged: both features are new methods; nothing existing was renamed, removed, or retyped. - No new dependencies. ## Release status -`search()` ([#54](https://github.com/spiceai/spice-java/pull/54)) and `nsql()`/`nsqlGenerateSql()` ([#55](https://github.com/spiceai/spice-java/pull/55)) have merged to trunk. This release still depends on two open PRs: +`search()` ([#54](https://github.com/spiceai/spice-java/pull/54)) and `nsql()`/`nsqlGenerateSql()` ([#55](https://github.com/spiceai/spice-java/pull/55)) have merged to trunk and are the entirety of what v0.8.0 ships. + +**Not included in this release:** - [#53](https://github.com/spiceai/spice-java/pull/53) — `listActiveQueries()`/`cancelActiveQuery()` - [#56](https://github.com/spiceai/spice-java/pull/56) — `queryAsync()`/`queryAsyncWithParams()` +Both are implemented and reviewed but will not be merged for v0.8.0. + It's also worth resolving before or alongside this release: **v0.7.0 was tagged and GitHub-released but was never actually published to Maven Central** — the Sonatype deployment was staged and validated but never taken out of "pending manual publish" (`maven-metadata.xml` on Maven Central still lists `0.6.0` as ``). `pom.xml`'s `japicmp.oldVersion` is deliberately left at `0.6.0` rather than bumped to `0.7.0` for this reason — see the comment in `pom.xml` for detail. From ea3e16686eaaa050c65cedae2d50d72685b67010 Mon Sep 17 00:00:00 2001 From: Viktor Yershov Date: Wed, 19 Aug 2026 15:40:47 -0700 Subject: [PATCH 4/7] Update release notes for v0.8.0 Removed release status section and notes on features not included in v0.8.0. --- docs/release_notes/v0.8.0.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/docs/release_notes/v0.8.0.md b/docs/release_notes/v0.8.0.md index af5334e..b816fe0 100644 --- a/docs/release_notes/v0.8.0.md +++ b/docs/release_notes/v0.8.0.md @@ -44,15 +44,3 @@ String sql = client.nsqlGenerateSql(new NsqlRequest("how many trips were over 10 - Public API unchanged: both features are new methods; nothing existing was renamed, removed, or retyped. - No new dependencies. -## Release status - -`search()` ([#54](https://github.com/spiceai/spice-java/pull/54)) and `nsql()`/`nsqlGenerateSql()` ([#55](https://github.com/spiceai/spice-java/pull/55)) have merged to trunk and are the entirety of what v0.8.0 ships. - -**Not included in this release:** - -- [#53](https://github.com/spiceai/spice-java/pull/53) — `listActiveQueries()`/`cancelActiveQuery()` -- [#56](https://github.com/spiceai/spice-java/pull/56) — `queryAsync()`/`queryAsyncWithParams()` - -Both are implemented and reviewed but will not be merged for v0.8.0. - -It's also worth resolving before or alongside this release: **v0.7.0 was tagged and GitHub-released but was never actually published to Maven Central** — the Sonatype deployment was staged and validated but never taken out of "pending manual publish" (`maven-metadata.xml` on Maven Central still lists `0.6.0` as ``). `pom.xml`'s `japicmp.oldVersion` is deliberately left at `0.6.0` rather than bumped to `0.7.0` for this reason — see the comment in `pom.xml` for detail. From 2ff04f82de85c7228451dc254db4489efd9d74e1 Mon Sep 17 00:00:00 2001 From: Viktor Yershov Date: Wed, 19 Aug 2026 17:30:17 -0700 Subject: [PATCH 5/7] Update release notes for v0.8.0 Removed testing section from release notes for v0.8.0. --- docs/release_notes/v0.8.0.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/release_notes/v0.8.0.md b/docs/release_notes/v0.8.0.md index b816fe0..9dfdcbf 100644 --- a/docs/release_notes/v0.8.0.md +++ b/docs/release_notes/v0.8.0.md @@ -35,10 +35,6 @@ System.out.println(response.getData()); String sql = client.nsqlGenerateSql(new NsqlRequest("how many trips were over 10 miles?")); ``` -## Testing - -- New unit test suites (`SearchTest`, `NsqlTest`) covering request/response shape, validation, and error handling, all against local mock servers with no live runtime required. - ## Compatibility - Public API unchanged: both features are new methods; nothing existing was renamed, removed, or retyped. From e7afcc0d5d82b8cd1ddcf8ff636692143fd15f03 Mon Sep 17 00:00:00 2001 From: Viktor Yershov Date: Wed, 19 Aug 2026 18:03:21 -0700 Subject: [PATCH 6/7] Update release notes for v0.8.0 Removed highlights section from release notes for v0.8.0. --- docs/release_notes/v0.8.0.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/release_notes/v0.8.0.md b/docs/release_notes/v0.8.0.md index 9dfdcbf..bc4a59f 100644 --- a/docs/release_notes/v0.8.0.md +++ b/docs/release_notes/v0.8.0.md @@ -1,11 +1,5 @@ # Spice Java SDK v0.8.0 -## Highlights - -v0.8.0 is a **feature-parity release**, closing two of the four gaps between this SDK and its siblings (gospice, spice-rs, spicepy, spice.js): search and natural-language-to-SQL. Both are purely additive — no existing public API changes shape or behavior, and no dependency changes. - -Active-query management and asynchronous queries were also implemented for this cycle ([#53](https://github.com/spiceai/spice-java/pull/53), [#56](https://github.com/spiceai/spice-java/pull/56)) but are **not included in v0.8.0** — those PRs will not be merged for this release. See "Release status" below. - ## What's New ### 🔎 Search From cf4f3871d734fafe8a359df2f0c449ea8ebcba84 Mon Sep 17 00:00:00 2001 From: Viktor Yershov Date: Wed, 19 Aug 2026 18:12:39 -0700 Subject: [PATCH 7/7] Change japicmp.oldVersion from 0.6.0 to 0.7.0 Updated the old version for japicmp to 0.7.0. --- pom.xml | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-) diff --git a/pom.xml b/pom.xml index 4e9b3c7..88d2bee 100644 --- a/pom.xml +++ b/pom.xml @@ -45,20 +45,8 @@ - 0.6.0 + fails if this still equals the version being released. --> + 0.7.0