Add query bindings, dataset refresh, and GitHub release publishing flow (#70)

* Add query bindings, dataset refresh, and release publishing flow

* test: Add async query tests with parameter handling and dataset refresh

* docs: Update README and tests to clarify usage of Arrow parameter types

* ci: move ubuntu-22.04 jobs to ubuntu-24.04 (Spice CLI GLIBC 2.38+ floor)

The prebuilt Spice CLI from install.spiceai.org now requires GLIBC
2.38/2.39, but ubuntu-22.04 runners ship GLIBC 2.35, so `spice install`
fails with "version GLIBC_2.38 not found" and the whole ubuntu-22.04
matrix leg goes red trunk-wide.

The failure also cascades: the always() "Stop spice and check logs" step
has working-directory: spice_qs, but a failed install/init never creates
that directory, so the step itself errors with "No such file or
directory" and masks the real cause.

Move the matrix entry to ubuntu-24.04 (GLIBC 2.39) and guard the
stop-step on hashFiles('spice_qs/**') so a failed install/init no longer
cascades into a misleading second failure.

Author: lukekim

.github/ISSUE_TEMPLATE/end_game.md

@@ -28,13 +28,12 @@ assignees: ''
 - [ ] Test the [`spice-rs` sample](https://github.com/spiceai/samples/tree/trunk/client-sdk/spice-rs-sdk-sample) using the latest `trunk` SDK version.
 - [ ] Update [release notes](https://github.com/spiceai/spice-rs/blob/trunk/docs/release_notes)
   - [ ] Ensure all contributors have been acknowledged.
-- [ ] Verify the version in `Cargo.toml` is correct and match the milestone version.
+- [ ] Verify `Cargo.toml` is set to the milestone version and the release tag will match it.
 - [ ] Run [Test CI](https://github.com/spiceai/spice-rs/actions/workflows/build.yml) and ensure it is green on the trunk branch.
 - [ ] QA DRI sign-off
 - [ ] Docs DRI sign-off
-- [ ] Create a new branch `release-v[semver]` for the release from trunk. E.g. `release-v3.0.0`
-- [ ] Release the new version by creating and publishing a latest [GitHub Release](https://github.com/spiceai/spice-rs/releases/new) with the tag from the release branch. E.g. `v3.0.0`.
-- [ ] Ensure the [publish](https://github.com/spiceai/spice-rs/actions/workflows/publish.yml) workflow has triggered, and successfully published the package.
+- [ ] Create or publish the GitHub Release for the target version tag.
+- [ ] If this should be the stable SDK release, mark the GitHub Release as Latest.
+- [ ] Ensure the [publish](https://github.com/spiceai/spice-rs/actions/workflows/publish.yml) workflow completed successfully and published the package.
 - [ ] Run a test pass using the [`spice-rs` sample](https://github.com/spiceai/samples/tree/trunk/client-sdk/spice-rs-sdk-sample) using the latest published version.
-- [ ] Update the version in `Cargo.toml` to the next release version.
 - [ ] The SDK release is added to the next [Spice release notes](https://github.com/spiceai/spiceai/tree/trunk/docs/release_notes)

.github/workflows/publish.yml

@@ -2,35 +2,154 @@ name: crates-publish
 
 on:
   release:
-    types: [published]
+    types: [published, released, edited]
 
   workflow_dispatch:
+    inputs:
+      tag:
+        description: Git tag to publish, for example v3.2.0
+        required: true
+        type: string
+
+  workflow_call:
+    inputs:
+      tag:
+        description: Git tag to publish, for example v3.2.0
+        required: false
+        type: string
 
 jobs:
   publish:
+    concurrency:
+      group: crates-publish-${{ github.event.release.tag_name || inputs.tag || github.ref }}
+      cancel-in-progress: false
     runs-on: ubuntu-latest
     environment: cratesio
     permissions:
+      contents: read
       id-token: write # Required for OIDC token exchange with crates.io
     steps:
       # actions/checkout v4.2.2
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          ref: ${{ github.event.release.tag_name || inputs.tag || github.ref }}
+
+      - name: Determine whether publish should run
+        id: preflight
+        env:
+          EVENT_ACTION: ${{ github.event.action }}
+          EVENT_NAME: ${{ github.event_name }}
+          GITHUB_TOKEN: ${{ github.token }}
+          RELEASE_DRAFT: ${{ github.event.release.draft }}
+          RELEASE_ID: ${{ github.event.release.id }}
+          RELEASE_TAG: ${{ github.event.release.tag_name || inputs.tag }}
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+
+          should_publish=false
+          skip_reason=''
+
+          if [[ "${EVENT_NAME}" == "release" ]]; then
+            if [[ "${RELEASE_DRAFT}" == "true" ]]; then
+              skip_reason='Draft releases do not trigger publishing.'
+            elif [[ "${EVENT_ACTION}" == "published" || "${EVENT_ACTION}" == "released" ]]; then
+              should_publish=true
+            elif [[ "${EVENT_ACTION}" == "edited" ]]; then
+              latest_release_id="$({
+                curl -fsSL \
+                  -H "Accept: application/vnd.github+json" \
+                  -H "Authorization: Bearer ${GITHUB_TOKEN}" \
+                  -H "X-GitHub-Api-Version: 2022-11-28" \
+                  "https://api.github.com/repos/${REPOSITORY}/releases/latest" |
+                  jq -r '.id'
+              } 2>/dev/null || true)"
+
+              if [[ -n "${latest_release_id}" && "${latest_release_id}" == "${RELEASE_ID}" ]]; then
+                should_publish=true
+              else
+                skip_reason='Edited release is not the latest published release.'
+              fi
+            else
+              skip_reason="Release action ${EVENT_ACTION} does not trigger publishing."
+            fi
+          else
+            should_publish=true
+          fi
+
+          crate_name="$(awk -F'"' '
+            $0 == "[package]" { in_package=1; next }
+            /^\[/ && $0 != "[package]" { in_package=0 }
+            in_package && $1 ~ /^[[:space:]]*name = / { print $2; exit }
+          ' Cargo.toml)"
+
+          crate_version="$(awk -F'"' '
+            $0 == "[package]" { in_package=1; next }
+            /^\[/ && $0 != "[package]" { in_package=0 }
+            in_package && $1 ~ /^[[:space:]]*version = / { print $2; exit }
+          ' Cargo.toml)"
+
+          if [[ -z "${crate_name}" || -z "${crate_version}" ]]; then
+            echo "Failed to determine crate metadata from Cargo.toml" >&2
+            exit 1
+          fi
+
+          if [[ -n "${RELEASE_TAG}" ]]; then
+            if [[ ! "${RELEASE_TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
+              echo "Release tag ${RELEASE_TAG} must match vX.Y.Z or vX.Y.Z-suffix" >&2
+              exit 1
+            fi
+
+            tag_version="${RELEASE_TAG#v}"
+            if [[ "${crate_version}" != "${tag_version}" ]]; then
+              echo "Release tag ${RELEASE_TAG} does not match Cargo.toml version ${crate_version}" >&2
+              exit 1
+            fi
+          elif [[ "${EVENT_NAME}" == "workflow_dispatch" ]]; then
+            echo "workflow_dispatch requires a tag input" >&2
+            exit 1
+          fi
+
+          if [[ "${should_publish}" == "true" ]]; then
+            if curl -fsSL "https://crates.io/api/v1/crates/${crate_name}/${crate_version}" >/dev/null; then
+              should_publish=false
+              skip_reason="${crate_name} ${crate_version} is already published to crates.io."
+            fi
+          fi
+
+          if [[ "${should_publish}" == "true" ]]; then
+            decision_message="Publishing ${crate_name} ${crate_version}."
+          else
+            decision_message="${skip_reason}"
+          fi
+
+          echo "should_publish=${should_publish}" >> "${GITHUB_OUTPUT}"
+          echo "crate_name=${crate_name}" >> "${GITHUB_OUTPUT}"
+          echo "crate_version=${crate_version}" >> "${GITHUB_OUTPUT}"
+          echo "decision_message=${decision_message}" >> "${GITHUB_OUTPUT}"
+
+      - name: Publish decision
+        run: echo "${{ steps.preflight.outputs.decision_message }}"
 
       # rust-lang/crates-io-auth-action v1.0.1
       # https://github.com/rust-lang/crates-io-auth-action/releases/tag/v1.0.1
       - uses: rust-lang/crates-io-auth-action@e919bc7605cde86df457cf5b93c5e103838bd879
         id: auth
+        if: ${{ steps.preflight.outputs.should_publish == 'true' }}
 
       - name: Install Rust toolchain
         # actions-rs/toolchain v1.0.7
         uses: actions-rs/toolchain@16499b5e05bf2e26879000db0c1d13f7e13fa3af
+        if: ${{ steps.preflight.outputs.should_publish == 'true' }}
         with:
           profile: minimal
           toolchain: 1.93.1
           override: true
 
       - run: cargo build
+        if: ${{ steps.preflight.outputs.should_publish == 'true' }}
 
       - run: cargo publish
+        if: ${{ steps.preflight.outputs.should_publish == 'true' }}
         env:
           CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }}

Cargo.toml

@@ -5,6 +5,12 @@ edition = "2024"
 rust-version = "1.93.1"
 description = "SDK for Spice.ai, an open-source runtime and platform for building AI-driven software."
 license = "Apache-2.0"
+repository = "https://github.com/spiceai/spice-rs"
+homepage = "https://spice.ai"
+documentation = "https://docs.rs/spiceai"
+readme = "README.md"
+keywords = ["spiceai", "sql", "arrow", "flight", "sdk"]
+categories = ["api-bindings", "database"]
 
 [dependencies]
 arrow = { version = "58", features = ["prettyprint"] }
@@ -39,3 +45,4 @@ winver = "1.0.0"
 
 [dev-dependencies]
 regex = "1.10.6"
+wiremock = "0.6.5"

README.md

@@ -1,71 +1,142 @@
 # Rust Spice SDK
 
-Rust SDK for Spice.ai
+Rust SDK for Spice.ai.
 
 ## Installation
 
-Add Spice SDK
+Add the SDK:
 
 ```bash
 cargo add spiceai
 ```
 
 ## Usage
 
-<!-- NOTE: If you're changing the code examples below, make sure you update `tests/readme_test.rs`. -->
+### Query a local Spice runtime
 
-### Usage with locally running [spice runtime](https://github.com/spiceai/spiceai)
+Follow the [quickstart guide](https://github.com/spiceai/spiceai?tab=readme-ov-file#%EF%B8%8F-quickstart-local-machine) to install and run Spice locally.
 
-Follow the [quickstart guide](https://github.com/spiceai/spiceai?tab=readme-ov-file#%EF%B8%8F-quickstart-local-machine) to install and run spice locally
+```rust,no_run
+use spiceai::{ClientBuilder, StreamExt};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+  let client = ClientBuilder::new().build().await?;
+
+  let mut stream = client
+    .sql(
+      "SELECT trip_distance, total_amount FROM taxi_trips ORDER BY trip_distance DESC LIMIT 10;",
+    )
+    .await?;
+
+  while let Some(batch) = stream.next().await {
+    println!("rows: {}", batch?.num_rows());
+  }
+
+  Ok(())
+}
+```
+
+### Use Arrow types re-exported by the SDK
+
+The SDK re-exports `arrow` as `spiceai::arrow`, which keeps your Arrow types aligned with the SDK's public API.
 
 ```rust,no_run
-use spiceai::ClientBuilder;
+use spiceai::{arrow::array::Float64Array, ClientBuilder, StreamExt};
 
 #[tokio::main]
-async fn main() {
-  let client = ClientBuilder::new()
-    .flight_url("http://localhost:50051")
-    .build()
-    .await
-    .unwrap();
+async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+  let client = ClientBuilder::new().build().await?;
+
+  let mut stream = client
+    .sql("SELECT trip_distance FROM taxi_trips ORDER BY trip_distance DESC LIMIT 1;")
+    .await?;
 
-  let data = client.query("SELECT trip_distance, total_amount FROM taxi_trips ORDER BY trip_distance DESC LIMIT 10;").await;
+  if let Some(batch) = stream.next().await {
+    let batch = batch?;
+    let values = batch
+      .column(0)
+      .as_any()
+      .downcast_ref::<Float64Array>()
+      .expect("trip_distance should be Float64");
+
+    println!("longest trip: {}", values.value(0));
+  }
+
+  Ok(())
 }
 ```
 
-### New client with <https://spice.ai> cloud
+### Parameterized queries
 
-```rust
+For common scalar bindings, use `QueryParameters`. For any Arrow data type, wrap a one-element Arrow array with `QueryParameter::array(...)`. For advanced Arrow parameter batches, use `Client::sql_with_params`.
+
+```rust,no_run
+use spiceai::{ClientBuilder, QueryParameters, StreamExt};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+  let client = ClientBuilder::new().build().await?;
+
+  let mut stream = client
+    .sql_with_bindings(
+      "SELECT VendorID, fare_amount FROM taxi_trips WHERE VendorID = $1 AND fare_amount > $2 LIMIT 5;",
+      QueryParameters::new().push(1_i32).push(1.0_f64),
+    )
+    .await?;
+
+  while let Some(batch) = stream.next().await {
+    println!("rows: {}", batch?.num_rows());
+  }
+
+  Ok(())
+}
+```
+
+### Connect to Spice.ai Cloud
+
+```rust,no_run
 use spiceai::ClientBuilder;
 
 #[tokio::main]
-async fn main() {
+async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
   let client = ClientBuilder::new()
     .api_key("API_KEY")
     .use_spiceai_cloud()
     .build()
-    .await
-    .unwrap();
+    .await?;
+
+  let _ = client;
+  Ok(())
 }
 ```
 
-### Arrow Query
+### Async query jobs and dataset refresh
 
-SQL Query
+Async query management and dataset refresh use the Spice HTTP API, so configure `http_url()` in addition to the Flight endpoint when needed.
 
-```rust
-use spiceai::ClientBuilder;
+```rust,no_run
+use spiceai::{ClientBuilder, DatasetRefreshMode, DatasetRefreshRequest};
 
 #[tokio::main]
-async fn main() {
+async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
   let client = ClientBuilder::new()
-    .api_key("API_KEY")
-    .use_spiceai_cloud()
+    .http_url("http://localhost:8090")
     .build()
-    .await
-    .unwrap();
+    .await?;
+
+  let job = client.query("SELECT * FROM large_table").await?;
+  println!("query status: {}", job.status().await?);
+
+  let response = client
+    .refresh_dataset_with_options(
+      "taxi_trips",
+      DatasetRefreshRequest::new().with_refresh_mode(DatasetRefreshMode::Full),
+    )
+    .await?;
 
-  let data = client.query("SELECT * FROM taxi_trips LIMIT 10;").await;
+  println!("{}", response.message);
+  Ok(())
 }
 ```