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 (default: http://localhost:8090).

• params.flightUrl (string, optional): URL of the Flight endpoint (default: localhost:50051, using local Spice Runtime).

• params.logging (boolean, optional): Enable or disable logging output (default: true).

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?) — 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.

• onData (callback, optional): Callback for handling streaming data.

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

// 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 limit the query scope.

  • model (string, optional): Model to use for SQL generation (default: "nql").

  • sample_data_enabled (boolean, optional): Include sample data in context (default: true).

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();

query(sql, onData?) — Legacy query method

The legacy query method. Still supported, but sql() is recommended for new code.

const table = await spiceClient.query("SELECT * FROM tpch.lineitem LIMIT 10");

setMaxRetries(retries) — Configure connection retries

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

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