Automate with the TypeScript SDK - Narrative I/O Knowledge Base

The Narrative TypeScript SDK provides type-safe access to the Narrative API, enabling you to automate data workflows, execute NQL queries, and manage datasets programmatically.

This tutorial assumes you have completed Write Your First NQL Query and have a basic understanding of NQL.

Prerequisites

Node.js 18 or later
A Narrative I/O account
An API key with appropriate permissions (see API Keys)

What you’ll learn

How to install and configure the SDK
How to execute an NQL query programmatically
How to work with query results

Install the SDK

Initialize your project

Create a new directory and initialize a Node.js project:

mkdir narrative-demo && cd narrative-demo
npm init -y

Install the SDK

Install the Narrative TypeScript SDK:

npm
yarn
bun

npm install @narrative.io/data-collaboration-sdk-ts

yarn add @narrative.io/data-collaboration-sdk-ts

bun add @narrative.io/data-collaboration-sdk-ts

Configure TypeScript (optional)

If you’re using TypeScript, install the necessary dependencies:

npm install typescript ts-node @types/node --save-dev
npx tsc --init

Initialize the SDK

Create a new file called index.ts (or index.js if using JavaScript):

import { NarrativeApi } from '@narrative.io/data-collaboration-sdk-ts';

// Initialize the SDK with your API key
const api = new NarrativeApi({
  apiKey: process.env.NARRATIVE_API_KEY,
});

Never commit API keys to source control. Use environment variables or a secrets manager to store sensitive credentials.

Set your API key as an environment variable before running your code:

export NARRATIVE_API_KEY="your-api-key-here"

Execute your first query

Add the following code to execute an NQL query:

import { NarrativeApi } from '@narrative.io/data-collaboration-sdk-ts';

async function main() {
  const api = new NarrativeApi({
    apiKey: process.env.NARRATIVE_API_KEY,
  });

  // Execute an NQL query
  const result = await api.executeNql({
    nql: `
      SELECT _nio_id, _nio_updated_at
      FROM company_data."my_dataset"
      LIMIT 10
    `,
    data_plane_id: null,
  });

  console.log('Query completed:', result.state);
  console.log('Rows returned:', result.result.rows);
}

main().catch(console.error);

Run your script:

TypeScript
JavaScript

npx ts-node index.ts

node index.js

Work with datasets

You can also use the SDK to manage datasets:

import { NarrativeApi } from '@narrative.io/data-collaboration-sdk-ts';

async function listDatasets() {
  const api = new NarrativeApi({
    apiKey: process.env.NARRATIVE_API_KEY,
  });

  // List all datasets
  const datasets = await api.getDatasets();

  console.log(`Found ${datasets.records.length} datasets:`);
  for (const dataset of datasets.records) {
    console.log(`- ${dataset.name} (ID: ${dataset.id})`);
  }

  // Get details for a specific dataset
  const datasetId = datasets.records[0]?.id;
  if (datasetId) {
    const dataset = await api.getDataset(datasetId);
    console.log('\nDataset details:', dataset.name);
    console.log('Status:', dataset.status);
    console.log('Created:', dataset.created_at);
  }
}

listDatasets().catch(console.error);

Validate a query before execution

Use the compileNql method to validate and see the transpiled SQL without executing:

const compiled = await api.compileNql({
  nql: `
    SELECT _nio_id
    FROM company_data."my_dataset"
    LIMIT 100
  `,
  data_plane_id: null,
});

console.log('Transpiled SQL:', compiled.sql);

if (compiled.mappingErrors) {
  console.log('Mapping errors:', compiled.mappingErrors);
}

Next steps

Now that you’ve executed your first SDK query, explore these resources to learn more:

Authentication Guide

Configure API keys and environments

Executing Queries

Advanced query patterns and options

Managing Datasets

Create, update, and manage datasets

SDK Reference

Complete API reference documentation

​Prerequisites

​What you’ll learn

​Install the SDK

​Initialize the SDK

​Execute your first query

​Work with datasets

​Validate a query before execution

​Next steps

Authentication Guide

Executing Queries

Managing Datasets

SDK Reference

Prerequisites

What you’ll learn

Install the SDK

Initialize the SDK

Execute your first query

Work with datasets

Validate a query before execution

Next steps