Merge branch 'trunk' into fix/server-side-parameter-binding

Author: sgrebnov

.github/workflows/test.yml

@@ -130,7 +130,7 @@ jobs:
           sleep 2
 
       - name: Run Node.js local runtime tests
-        run: npm run test:node -- test/local-runtime.test.ts test/user-agent.test.ts
+        run: npm run test:node -- test/local-runtime.test.ts test/user-agent.test.ts test/grpc-http-fallback.test.ts
 
       - name: Run performance tests
         run: npm run test:perf

README.md

@@ -82,6 +82,32 @@ const table = await client.sql(
 
 The SDK handles all protocol negotiation automatically - you just write standard SQL with parameters.
 
+### Search
+
+`search()` runs vector similarity, keyword, and hybrid search against datasets that have
+an embedding column and a loaded embedding model.
+
+```js
+const results = await client.search('trips near the airport', {
+  datasets: ['taxi_trips'],
+  limit: 5,
+  additional_columns: ['trip_distance'],
+  keywords: ['airport'],
+});
+
+console.log(`${results.results.length} matches in ${results.duration_ms}ms`);
+
+for (const match of results.results) {
+  console.log(match.dataset, match.score, match.primary_key, match.data);
+}
+```
+
+Each match carries the `dataset` it was found in, its similarity `score`, the matched
+column values in `matches`, the dataset's `primary_key`, any `additional_columns` you
+requested in `data`, and `metadata`. The four object fields are always present — they
+default to `{}` when the runtime returns nothing for them, so you can read into them
+without a guard.
+
 ## Upgrading from v2 to v3
 
 Version 3.0 represents a major evolution of the SDK with cross-platform support, new APIs, and enhanced reliability.
@@ -560,6 +586,35 @@ Options:
 - `refresh_sql`: Custom SQL query to use for the refresh
 - `refresh_jitter_max`: Maximum jitter time for refresh scheduling
 
+#### `listActiveQueries()` / `cancelActiveQuery(queryId)` - List and cancel running queries
+
+`listActiveQueries()` reports the synchronous queries this client currently has running — those started by `sql()`, `query()`, `sqlJson()`, FlightSQL, `nsql()` and `search()` — and `cancelActiveQuery()` stops one by id.
+
+The runtime does not hand a query's id back to the client that submitted it, so the two are used together: list to find the query, then cancel it. Both are scoped to the caller, so a client only ever sees and cancels its own queries.
+
+```js
+const queries = await spiceClient.listActiveQueries();
+
+for (const query of queries) {
+  console.log(`${query.query_id} [${query.protocol}] ${query.sql_preview}`);
+  console.log(`  started at ${new Date(query.started_at_ms).toISOString()}`);
+}
+
+// Cancel a long-running query by id.
+if (queries.length > 0) {
+  const result = await spiceClient.cancelActiveQuery(queries[0].query_id);
+  console.log(`${result.query_id} is now ${result.status}`);
+}
+```
+
+Each `ActiveQuery` carries `query_id`, `protocol` (`http`, `flight`, `flightsql`, or `internal`), a truncated `sql_preview`, and `started_at_ms` as milliseconds since the Unix epoch.
+
+`cancelActiveQuery()` throws when the id is not a UUID, when the API key lacks write access, or when no such query is running — including the case where the id belongs to a different caller, which the runtime reports as not found rather than cancelling.
+
+The boundary is the **caller's identity, not the client instance**: the runtime scopes both `listActiveQueries()` and `cancelActiveQuery()` to the authenticated principal. Two clients using the same API key therefore share one set and can cancel each other's queries, and unauthenticated requests all share the runtime's public scope. Do not rely on one `SpiceClient` seeing only its own queries.
+
+Both work on Node and in the browser, since they use the HTTP control plane rather than Flight.
+
 #### `nsql(request)` - Natural language to SQL (NSQL)
 
 The `nsql()` method converts natural language queries into SQL and executes them, returning both the results and the generated SQL.
@@ -637,7 +692,26 @@ The `SpiceClient` automatically handles environments where Apache Arrow Flight g
 2. **Automatic**: If the Flight proto file is missing, it's automatically downloaded from `https://data.spiceai.io/v1/proto/flight` and cached
 3. **Fallback**: If gRPC cannot be initialized, automatically falls back to the HTTP `/v1/sql` endpoint
 
-Both gRPC and HTTP modes support compression (gzip, deflate) to reduce bandwidth usage. This ensures the SDK works efficiently in any environment without configuration changes. See [docs/http-fallback.md](./docs/http-fallback.md) for more details.
+Both gRPC and HTTP modes support compression (gzip, deflate) to reduce bandwidth usage. This ensures the SDK works efficiently in any environment without configuration changes.
+
+### TLS and mTLS (Node.js only)
+
+> **Note:** mTLS (client certificate authentication) is an [Enterprise](https://docs.spice.ai/docs/enterprise) feature of the Spice.ai runtime.
+
+The client accepts PEM certificate file paths for custom server verification and mutual TLS:
+
+```js
+const client = new SpiceClient({
+  flightUrl: 'my-spice-host:50051',
+  httpUrl: 'https://my-spice-host:8090',
+  tlsRootCertFile: './certs/ca.pem', // custom CA for server verification (optional)
+  tlsClientCertFile: './certs/client.pem', // ┐ provide both to enable mTLS
+  tlsClientKeyFile: './certs/client.key', //  ┘
+});
+```
+
+- `tlsClientCertFile` and `tlsClientKeyFile` must be provided together; the client certificate is presented during the TLS handshake on both the gRPC and HTTP transports.
+- The Spice runtime must be configured with `client_auth_mode: request` or `required`. See the [mTLS cookbook recipe](https://github.com/spiceai/cookbook/tree/trunk/mtls) for a complete walkthrough.
 
 ## Advanced
 

src/client-common.ts

@@ -16,6 +16,10 @@ import {
   type QueryParameters,
   type SearchOptions,
   type SearchResponse,
+  type WireSearchResponse,
+  type ActiveQuery,
+  type ActiveQueriesResponse,
+  type CancelActiveQueryResponse,
 } from './interfaces';
 import type { GrpcFlightClient } from './grpc/client.node';
 import {
@@ -24,6 +28,7 @@ import {
   normalizeSchema,
   serializeArrowField,
 } from './arrow-utils';
+import { normalizeSearchResponse } from './search-utils';
 import { Logger } from './logger';
 import { Param } from './param';
 
@@ -685,7 +690,39 @@ export class SpiceClient {
     if (this._grpcClient) {
       const useGrpc = await this._grpcClient.ensureInitialized();
       if (useGrpc) {
-        return this.doGrpcQueryRequest(queryText, parameters, onData, headers);
+        // Track whether any chunk has reached the caller's callback — once it
+        // has, falling back to HTTP would deliver duplicate data
+        let dataSent = false;
+        const trackingOnData = onData
+          ? (table: Table) => {
+              dataSent = true;
+              onData(table);
+            }
+          : undefined;
+
+        try {
+          return await this.doGrpcQueryRequest(
+            queryText,
+            parameters,
+            trackingOnData,
+            headers,
+          );
+        } catch (error) {
+          if (this._flightOnly || dataSent) {
+            throw error;
+          }
+          this._logger.warn(
+            `[spice.js] Arrow Flight query failed, falling back to HTTP: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          );
+          return this.doHttpQueryRequest(
+            queryText,
+            parameters,
+            onData,
+            headers,
+          );
+        }
       }
 
       // If flightOnly mode is enabled and gRPC failed, throw error
@@ -773,23 +810,39 @@ export class SpiceClient {
       ? 'application/vnd.spiceai.sql.v1+json' // data.spiceai.io returns schema with 'data' field
       : 'application/json'; // OSS returns plain JSON array
 
-    // Prepare request body with parameters
     const httpParameters = this.convertParametersForHttp(parameters);
-    const requestBody = JSON.stringify({
-      sql: queryText,
-      parameters: httpParameters,
-    });
 
+    // The JSON envelope ({sql, parameters}) is only understood by the OSS
+    // runtime, and only when Content-Type is exactly application/json.
+    // Spice Cloud parses every request body as raw SQL, so queries without
+    // parameters are sent as plain text — the format every endpoint accepts.
+    let requestBody: string;
+    let contentType: string;
+    if (httpParameters.length === 0) {
+      requestBody = queryText;
+      contentType = 'text/plain';
+    } else if (this._isSpiceCloud) {
+      throw new Error(
+        'Parameterized queries over HTTP are not supported by Spice Cloud. Use Arrow Flight (gRPC) for parameterized queries.',
+      );
+    } else {
+      requestBody = JSON.stringify({
+        sql: queryText,
+        parameters: httpParameters,
+      });
+      contentType = 'application/json';
+    }
+
+    // Custom headers merge first — the computed Content-Type/Accept always
+    // win, because the SDK picks the body format (raw SQL vs JSON envelope)
+    // and parses the response according to these values; a caller override
+    // would desync the headers from the body.
     const requestHeaders: { [key: string]: string } = {
-      'Content-Type': 'application/json',
+      ...headers,
+      'Content-Type': contentType,
       Accept: acceptHeader,
     };
 
-    // Merge custom headers if provided
-    if (headers) {
-      Object.assign(requestHeaders, headers);
-    }
-
     const response = await this.fetchInternal(
       'POST',
       '/v1/sql',
@@ -1397,8 +1450,8 @@ export class SpiceClient {
       );
     }
 
-    const result = await response.json();
-    return result as SearchResponse;
+    const result = (await response.json()) as WireSearchResponse;
+    return normalizeSearchResponse(result);
   }
 
   /**
@@ -1446,6 +1499,99 @@ export class SpiceClient {
     return await response.json();
   }
 
+  /**
+   * Lists the synchronous queries this client currently has running.
+   *
+   * Synchronous queries are the ones started by `sql()`, `query()`, `sqlJson()`,
+   * FlightSQL, `nsql()` and `search()` — not async query jobs, which the runtime
+   * only serves in cluster mode.
+   *
+   * The runtime does not return a query's id to the client that submitted it, so
+   * this is how to find the id that {@link cancelActiveQuery} needs. Results are
+   * scoped to this client, so another caller's in-flight queries are never listed.
+   *
+   * @returns Promise resolving to the active queries
+   */
+  async listActiveQueries(): Promise<ActiveQuery[]> {
+    if (!this._httpUrl) {
+      throw new Error('HTTP URL is required for listing active queries');
+    }
+
+    const response = await this.fetchInternal('GET', '/v1/sql/active');
+
+    if (response.status === 403) {
+      throw new Error(
+        'The configured API key does not allow listing queries. Use a key with write access.',
+      );
+    }
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(
+        `Failed to list active queries: ${response.status} ${response.statusText} - ${errorText}`,
+      );
+    }
+
+    const payload = (await response.json()) as ActiveQueriesResponse | null;
+    return payload?.queries ?? [];
+  }
+
+  /**
+   * Cancels a running synchronous query by id.
+   *
+   * `queryId` comes from {@link listActiveQueries}. Cancellation is scoped to this
+   * client: an id belonging to another caller is reported as not found rather than
+   * cancelled.
+   *
+   * @param queryId - The id of the query to cancel
+   * @returns Promise resolving to the cancellation response
+   */
+  async cancelActiveQuery(
+    queryId: string,
+  ): Promise<CancelActiveQueryResponse> {
+    if (!this._httpUrl) {
+      throw new Error('HTTP URL is required for cancelling a query');
+    }
+
+    if (!queryId) {
+      throw new Error(
+        'queryId is required. Use listActiveQueries() to find one.',
+      );
+    }
+
+    const response = await this.fetchInternal(
+      'POST',
+      `/v1/sql/${encodeURIComponent(queryId)}/cancel`,
+    );
+
+    if (response.status === 400) {
+      throw new Error(
+        `Query id '${queryId}' is not a valid UUID. Use the query_id from listActiveQueries().`,
+      );
+    }
+
+    if (response.status === 403) {
+      throw new Error(
+        'The configured API key does not allow cancelling queries. Use a key with write access.',
+      );
+    }
+
+    if (response.status === 404) {
+      throw new Error(
+        `No active query '${queryId}' found. It may have already finished, or it was submitted by a different client.`,
+      );
+    }
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(
+        `Failed to cancel query '${queryId}': ${response.status} ${response.statusText} - ${errorText}`,
+      );
+    }
+
+    return (await response.json()) as CancelActiveQueryResponse;
+  }
+
   /**
    * Checks if the Spice runtime is ready to accept requests.
    * This endpoint is authenticated and requires an API key.

src/index.browser.ts

@@ -40,5 +40,8 @@ export type {
   SearchResponse,
   SearchMatch,
   QueryHeaders,
+  ActiveQuery,
+  ActiveQueriesResponse,
+  CancelActiveQueryResponse,
   RefreshOverrides, // deprecated, kept for backward compatibility
 } from './interfaces';

src/index.node.ts

@@ -41,5 +41,8 @@ export type {
   SearchResponse,
   SearchMatch,
   QueryHeaders,
+  ActiveQuery,
+  ActiveQueriesResponse,
+  CancelActiveQueryResponse,
   RefreshOverrides, // deprecated, kept for backward compatibility
 } from './interfaces';