# API Reference

Look up the SpiceClient parameters and methods of the Spice Node.js SDK, including sql, nsql, search, and refreshDataset.

## 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:

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

const spiceClient = new SpiceClient();
```

Connect to Spice Cloud:

```javascript
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:

```javascript
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](https://arrow.apache.org/js/current/classes/Arrow.dom.Table.html).

- `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](https://spice.ai/docs/sdks/node.js-sdk/streaming) data.
- `headers` (object, optional): Custom headers to include with the request.

```javascript
// 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] }
);
```

> **Note**
>
> 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)`](https://arrow.apache.org/js/current/classes/Arrow.dom.Table.html#getchild):

```javascript
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.

```javascript
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](https://spice.ai/docs/cloud/api/nsql) for the full contract.

```javascript
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.

```javascript
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**.

```javascript
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.

```javascript
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.

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

#### `search(query, options?)`: Search datasets

Runs a search query against the project's datasets.

```javascript
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.

```javascript
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.

> **Warning**
>
> 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).

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