spice.js

Spice.ai client library for Node.JS

See full documentation at docs.spice.ai.

Installation

npm install @spiceai/spice or yarn add @spiceai/spice

Usage

High-Performance Apache Arrow Flight Query with https://spice.ai cloud

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

const main = async () => {
  const spiceClient = new SpiceClient({
    api_key: 'API_KEY', // spice.ai api key,
    http_url: 'https://data.spiceai.io',
    flight_url: 'flight.spiceai.io:443'
  });
  const table = await spiceClient.query(
    'SELECT number, "timestamp", gas_used FROM eth.recent_blocks LIMIT 10'
  );
  console.table(table.toArray());
};

main();

Querying data is done through a SpiceClient object that initializes the connection with Spice endpoint. SpiceClient has the following arguments:

• apiKey (string, required): API key to authenticate with the endpoint.
• url (string, optional): URL of the endpoint to use (default: flight.spiceai.io:443)

Read more about the Spice.ai Apache Arrow Flight API at docs.spice.ai.

Async Query

import { SpiceClient } from '@spiceai/spice';
const main = async () => {
  const spiceClient = new SpiceClient('API_KEY');
  const queryResp = await spiceClient.queryAsync(
    'recent_blocks',
    'SELECT number, "timestamp", gas_used FROM eth.recent_blocks LIMIT 10',
    'https://o4skc7qyx7mrl8x7wdtgmc.hooks.webhookrelay.com'
  ).catch((reason) => {
    console.error('Query failed.', reason)    
  });

  if !queryResp {
    return;
  }

  // Webhook trigger with body
  const queryResults = await spiceClient.getQueryResultsFromNotification(
    body
  );

  console.log(queryResults);
};

main();

Read more about the Spice.ai Async HTTP API at docs.spice.ai.

Usage with locally running spice runtime

Follow the quiqstart guide to install and run spice locally

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

const main = async () => {
  // uses connection to local runtime by default
  const spiceClient = new SpiceClient();

  // or use custom connection params:
  // const spiceClient = new SpiceClient({
  //   http_url: 'http://my_spice_http_host',
  //   flight_url: 'my_spice_flight_host',
  // });

  const table = await spiceClient.query(
    'SELECT trip_distance, total_amount FROM taxi_trips ORDER BY trip_distance DESC LIMIT 10;'
  );
  console.table(table.toArray());
};

main();

Connection retry

From version 1.0.1 the SpiceClient implements connection retry mechanism (3 attempts by default). The number of attempts can be configured via setMaxRetries:

const spiceClient = new SpiceClient('API_KEY');
spiceClient.setMaxRetries(5); // Setting to 0 will disable retries

Retries are performed for connection and system internal errors. It is the SDK user's responsibility to properly handle other errors, for example RESOURCE_EXHAUSTED (HTTP 429).

Documentation

Check out our API documentation to learn more about how to use the Node.js SDK.

Running tests locally

To run the tests (yarn test):

1. Create WebhookRelay account (Free)
2. Create Access Token => save key and secret as RELAY_KEY and RELAY_SECRET
3. Create New Empty Bucket called spice.js => save Default public endpoint value as RELAY_URL

Pass RELAY_KEY, RELAY_SECRET, RELAY_URL as parameters when running the tests, for example via .env config file.

API_KEY=<Your API_KEY>
RELAY_KEY=<Your RELAY_KEY from Step 2 above>
RELAY_SECRET=<Your RELAY_SECRET from Step 2 above>
RELAY_URL=<Your RELAY_URL from Step 3 above>