release: prepare v0.8.0

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 `<latest>`). `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.

pom.xml

@@ -4,7 +4,7 @@
     <groupId>ai.spice</groupId>
     <artifactId>spiceai</artifactId>
     <packaging>jar</packaging>
-    <version>0.7.0</version>
+    <version>0.8.0</version>
     <name>Java Spice SDK</name>
     <url>https://github.com/spiceai/spice-java/</url>
     <description>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.</description>
@@ -45,7 +45,19 @@
         <argLine></argLine>
         <!-- The last published release, which the japicmp API-compatibility
              gate compares against. Bump when releasing; the publish workflow
-             fails if this still equals the version being released. -->
+             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 <latest>). 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. -->
         <japicmp.oldVersion>0.6.0</japicmp.oldVersion>
     </properties>
     <dependencyManagement>

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";
     }
 }