Options
All
  • Public
  • Public/Protected
  • All
Menu

rockset

rockset-node-client v2 npm version npm version

Official Rockset Javascript/Typescript SDK.

npm i rockset

What's new

Supports ES6 promises and Typescript out of the box.

Requirements

At least Node v4.3.2

If you are using Webpack, you should have ES6 support.

Optionally use Typescript for type checking.

Documentation

Full API Reference of the Javascript SDK can be found in the Rockset Docs.

Usage

Import Using Require

const rockset = require("rockset").default(
  apikey,
  "https://api.rs2.usw2.rockset.com"
);

await rockset.queries.query({
  sql: { query: "SELECT count(*) FROM _events" },
});

Import Using ES6 Syntax

import rocksetConfigure from "rockset";
const rockset = rocksetConfigure(apikey, "https://api.rs2.usw2.rockset.com");

await rockset.queries.query({
  sql: { query: "SELECT count(*) FROM _events" },
});

Create a Collection

Create a collection using the client object as follows:

client.collections
  .createCollection("commons", {
    name: "my-first-collection",
    description: "my first collection",
  })
  .then(console.log);

Create an Integration

If you have an Amazon S3 bucket that you want to ingest data from, create a Rockset Integration to store credentials required to access the bucket. Create an integration object using the client object as follows:

client.integrations
  .createIntegration({
    name: "my-first-integration",
    description: "my-first-integration",
    s3: {
      aws_role: {
        aws_role_arn: "...",
      },
      aws_access_key: {
        aws_access_key_id: "...",
        aws_secret_access_key: "...",
      },
    },
  })
  .then(console.log);

Create a Collection from Amazon S3

Prior to creating a collection using Amazon S3 as source, create a Rockset Integration first as described above.

client.collections
  .createCollection("commons", {
    name: "my-first-s3-collection",
    description: "my first s3 collection",
    sources: [
      {
        integration_name: "my-first-integration",
        s3: {
          bucket: "bucket-name",
        },
      },
    ],
  })
  .then(console.log);

Add Documents

Add documents to an existing collection using the client object.

client.documents
  .addDocuments("commons", "my-first-collection", {
    data: [
      {
        name: "foo",
        address: "bar",
      },
    ],
  })
  .then(console.log);

Query

Make queries to Rockset using the client object.

client.queries
  .query({
    sql: {
      query: "SELECT count(*) FROM _events;",
    },
  })
  .then(console.log);

Create a Query Lambda

Create a Query Lambda using the client object.

client.queryLambdas
  .createQueryLambda("commons", {
    name: "myQueryLambda",
    sql: {
      query: "SELECT :param as echo",
      default_parameters: [
        {
          name: "param",
          type: "string",
          value: "Hello world!",
        },
      ],
    },
  })
  .then(console.log);

Execute a Query Lambda

Execute a Query Lambda using the client object.

// Run a Query Lambda with default parameters (or no parameters)
client.queryLambdas
  .executeQueryLambda(
    /* workspace */ "commons",
    /* queryName */ "myQuery",
    /* version */ "1ab853df3eab33b"
  )
  .then(console.log)
  .catch(console.error);

// Run a Query Lambda with custom parameters
client.queryLambdas
  .executeQueryLambda("commons", "myQuery", "1ab853df3eab33b", {
    parameters: [
      {
        name: "param",
        type: "string",
        value: "All work and no play makes Jack a dull boy",
      },
    ],
  })
  .then(console.log)
  .catch(console.error);

Custom Fetch Function

By default, the rockset-node-client is a thin wrapper that sends REST calls to Rockset using node-fetch. Many applications may require more complex behavior. If additional functionality is required, rockset-node-client can be configured to generate the parameters for a REST call, and pass them to a custom fetch function to be handled accordingly.

Here is an example that shows how to support cancelling API calls using a custom fetch function with Axios. To supply a custom fetch function, we pass it in as the last parameter to rocksetConfigure.

Note this does not cancel the API request on Rockset's servers

import axios from "axios";
import rocksetConfigure from "rockset";

// Super simple fetch with axios: axios docs show how to check for errors, cancel requests etc.
const customFetchAxios = async (
  url: string,
  { headers, method, body: data, queryParams: params, cancelToken }: any
) => {
  const res = await axios.request({
    url,
    headers,
    method,
    data,
    params,
    cancelToken,
  });

  return res.data;
};

// Configure
const basePath = "https://api.rs2.usw2.rockset.com";
const apikey = "<your apikey>";

const rockset = rocksetConfigure(apikey, basePath, customFetchAxios);
const cancelSource = axios.CancelToken.source();

// To execute a query
rockset.queries
  .query(
    { sql: { query: "SELECT count(*) FROM _events" } },
    { cancelToken: cancelSource.token }
  )
  .then(console.log)
  .catch(console.error);

// To cancel the request through axios
// *** THIS DOES NOT CANCEL THE QUERY ON OUR SERVERS ***
cancelSource.cancel();

You can see a few more sample examples of how to create a collection, how to put documents in a collection and how to use SQL to query your collections.

Testing

Unit tests are available in the tests folder.

Set ROCKSET_APIKEY and ROCKSET_HOST endpoint in the environment variables. To run tests:

npm test

This runs unit tests and integration tests.

How to contribute

Please feel free to submit a pull request for modifications that can benefit other users in the community. It is best to have a unit test associated with each pull request.

Support

Feel free to log issues against this client through GitHub.

License

The Rockset Node Client is licensed under the Apache 2.0 License

Generated using TypeDoc