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.ai Cloud endpoints for both.

Default connection to local Spice Runtime:

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

const spiceClient = new SpiceClient();

Connect to Spice.ai Cloud Platform:

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. A callback may be passed in this position instead of onData.

• 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] }
);

Rows returned by toArray() are plain objects when the result contains a decimal, timestamp, list, or struct column, and Arrow row proxies otherwise. Use plain property access or JSON.stringify(row) rather than calling row.toJSON(), which is not present on the plain-object form.

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

refreshAcceleration(dataset, options?) — Trigger dataset refresh

Triggers an on-demand refresh for an accelerated dataset.

• 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.refreshAcceleration('my_dataset');

// With options
await spiceClient.refreshAcceleration('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();

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.

Before 3.2.0, query() was a synchronous alias for sql(). The call compiles unchanged but now resolves to a job handle instead of a Table.

setMaxRetries(retries) — Configure connection retries

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

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