Skip to main content
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

1

Initialize your project

Create a new directory and initialize a Node.js project:
mkdir narrative-demo && cd narrative-demo
npm init -y
2

Install the SDK

Install the Narrative TypeScript SDK:
npm install @narrative.io/data-collaboration-sdk-ts
3

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: 
npx ts-node index.ts

​
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