API Reference

SpiceClient(params)

The top-level object that connects to Spice.ai.

• params.apiKey (string, optional): API key to authenticate with the endpoint.
• params.httpUrl (string, optional): URL of the HTTP endpoint, including the scheme (default: http://127.0.0.1:8090).
• params.flightUrl (string, optional): Host and port of the Flight endpoint, without a scheme (default: 127.0.0.1:50051, using local Spice Runtime).
• params.flightTlsEnabled (boolean, optional): Use TLS for Flight. Defaults to false for a localhost address and true otherwise.
• params.userAgent (string, optional): Prepended to the reported user agent.
• params.customHeaders (object, optional): Additional headers to send with each request.
• params.flightOnly (boolean, optional): Use only the Flight transport (default: false).
• params.httpOnly (boolean, optional): Use only the HTTP transport (default: false). Setting both flightOnly and httpOnly throws.
• params.logging (boolean, optional): Enable or disable logging output (default: true).

Supplying only an apiKey (with neither URL set) selects the Spice Cloud endpoints for both.

From 3.3.0, you can set only one of httpUrl or flightUrl to a Spice Cloud or local runtime address. The client then uses the matching address for the other one. For example, flightUrl: 'flight.spiceai.io:443' alone sends HTTP calls to https://data.spiceai.io. An empty or whitespace-only httpUrl or flightUrl throws. To use the default, omit the option.

Default connection to local Spice Runtime:

import { SpiceClient } from "@spiceai/spice";

const spiceClient = new SpiceClient();

Connect to Spice Cloud:

import { SpiceClient } from "@spiceai/spice";

const spiceClient = new SpiceClient({
    apiKey: 'API_KEY',
    httpUrl: 'https://data.spiceai.io',
    flightUrl: 'flight.spiceai.io:443'
});

Or using shorthand:

import { SpiceClient } from "@spiceai/spice";

const spiceClient = new SpiceClient('API_KEY');

SpiceClient Methods

sql(query, options?, onData?, headers?): Execute SQL queries

The recommended method for executing SQL queries. Returns an Apache Arrow Table.

• query (string, required): The SQL query to execute.
• options (object, optional): Query options including parameters for parameterized queries and signal. A callback may be passed in this position instead of onData.
  • signal (AbortSignal, optional): Cancels the query when it aborts. The client closes the request, and the runtime stops the query. The call rejects with the signal's reason, and the client does not retry it. sqlJson() accepts the same option.
• onData (callback, optional): Callback for handling streaming data.
• headers (object, optional): Custom headers to include with the request.

// Standard query
const table = await spiceClient.sql("SELECT * FROM tpch.lineitem LIMIT 10");
table.toArray().forEach((row) => {
  console.log(JSON.stringify(row));
});

// Parameterized query
const table = await spiceClient.sql(
  'SELECT * FROM taxi_trips WHERE passenger_count = $1 AND trip_distance > $2 LIMIT 10',
  { parameters: [2, 5.0] }
);

Get all elements for a column by calling getChild(name: string):

const table = await spiceClient.sql(
  'SELECT sum(l_extendedprice) as sum_extendedprice FROM tpch.lineitem'
);
let sumExtendedPrice = table.getChild("sum_extendedprice");
console.log(sumExtendedPrice?.toJSON());

sqlJson(query, headers?): Execute SQL queries with JSON results

Returns results in JSON format with schema information.

• query (string, required): The SQL query to execute.
• headers (object, optional): Custom headers to include with the request.

const result = await spiceClient.sqlJson('SELECT name, age FROM users LIMIT 5');

console.log(`Returned ${result.row_count} rows`);
console.log('Schema:', result.schema);
console.log('Data:', result.data);
console.log(`Query took ${result.execution_time_ms}ms`);

The response includes:

• row_count: Number of rows returned
• schema: Schema information with field names and types
• data: Array of row objects
• execution_time_ms: Query execution time in milliseconds

nsql(query, options?): Natural language to SQL

Converts natural language queries into SQL and executes them.

• query (string, required): The natural language query.
• options (object, optional):
  • datasets (array, optional): Dataset names to sample from when building the model context. It is a sampling hint only. It does not restrict which tables the query can target.
  • model (string, optional): Model to use for SQL generation. When omitted, the single compatible model configured in the project is used; if none or more than one is configured, the request fails.
  • sample_data_enabled (boolean, optional): Include sample data in context (default: false).

See the Text-to-SQL API for the full contract.

const result = await spiceClient.nsql('Show me the top 5 customers by total sales');

console.log('Generated SQL:', result.sql);
console.log('Results:', result.data);
console.log(`Returned ${result.row_count} rows`);

refreshDataset(dataset, options?): Trigger dataset refresh

Triggers an on-demand refresh for an accelerated dataset. refreshDataset() is new in 3.3.0. refreshAcceleration() is a deprecated alias that sends the same request.

• dataset (string, required): Name of the dataset to refresh.
• options (object, optional):
  • refresh_mode (string): 'full', 'append', 'changes', or 'disabled'.
  • refresh_sql (string): Custom SQL query for the refresh.
  • refresh_jitter_max (string): Maximum jitter time for refresh scheduling.

await spiceClient.refreshDataset('my_dataset');

// With options
await spiceClient.refreshDataset('my_dataset', {
  refresh_mode: 'full',
  refresh_sql: 'SELECT * FROM source WHERE updated_at > NOW() - INTERVAL 1 DAY',
});

isSpiceHealthy(): Check runtime health

Checks if the Spice runtime is healthy. This endpoint is unauthenticated.

const isHealthy = await spiceClient.isSpiceHealthy();

isSpiceReady(): Check runtime readiness

Checks if the Spice runtime is ready to accept queries. This endpoint is authenticated if an API key is configured.

const isReady = await spiceClient.isSpiceReady();

runtimeStatus(): Get the status of each runtime connection

Returns one { name, endpoint, status } entry for each runtime connection (http, flight, metrics and opentelemetry) from GET /v1/status. Use it to find which endpoint is not ready. It throws when the response is not a valid status list.

const connections = await spiceClient.runtimeStatus();
console.table(connections);

search(query, options?): Search datasets

Runs a search query against the project's datasets.

const results = await spiceClient.search('quarterly revenue trends');

query(sql, options?): Submit an asynchronous query

Submits a query for asynchronous execution and resolves to an AsyncQuery handle rather than a Table. Requires the runtime to be running in distributed (scheduler) mode. Use sql() for the synchronous, streaming path.

• sql (string, required): The SQL query to submit.
• options (object, optional): Query options, including parameters for parameterized queries.

const job = await spiceClient.query('SELECT * FROM taxi_trips');
const table = await job.results(); // waits for completion, then fetches results

The handle exposes status(), waitForCompletion(options?), results(), and cancel(). queryWithParams(sql, parameters) is equivalent to query() with options.parameters set, and listQueries() lists submitted jobs.

setMaxRetries(retries): Configure connection retries

Configures the maximum number of connection retry attempts (default: 3).

spiceClient.setMaxRetries(5); // Setting to 0 disables retries