Overview

Getting Started

Install Teide JS, set up your environment, and run your first query in under five minutes.

Prerequisites

• Node.js ≥ 18
• CMake ≥ 3.15
• A C17/C++17 compatible compiler (GCC 9+, Clang 10+, or MSVC 2019+)

Installation

From npm

npm install teidedb

Build from Source

git clone https://github.com/TeideDB/teide-js.git
cd teide-js
npm install
npm run build

This runs cmake to compile the native addon (debug mode) and then compiles the TypeScript layer. For an optimized release build:

npm run build:native:release

To verify everything is working:

npm test

Quick Start

Create a new file called demo.js and add the following:

import { Context } from 'teidedb';

// Create a context (initializes the Teide engine)
const ctx = new Context();

// Load a CSV file into a table
ctx.executeSync("CREATE TABLE sales AS SELECT * FROM read_csv('sales.csv')");

// Query with SQL
const top = ctx.executeSync(`
  SELECT region, SUM(revenue) AS total
  FROM sales
  GROUP BY region
  ORDER BY total DESC
  LIMIT 5
`);

console.log('Top regions by revenue:');
console.log('Columns:', top.columns);
console.log('Rows:', top.nRows);

// Clean up
ctx.destroy();

Run it:

node demo.js

Two Ways to Query

Teide JS gives you two interfaces to work with data. Use whichever fits your use case — or mix them freely.

SQL Interface

Execute any SQL statement directly. Results come back as a Table object with typed column accessors.

const result = ctx.executeSync(`
  SELECT name, age, department
  FROM employees
  WHERE age > 30
  ORDER BY name
`);

console.log(result.columns);  // ['name', 'age', 'department']
console.log(result.nRows);    // number of matching rows

Fluent API

Build queries programmatically with a chainable, type-safe API. Operations are lazy — nothing executes until you call collectSync() or collect().

import { Context, col, lit } from 'teidedb';

const ctx = new Context();
ctx.executeSync("CREATE TABLE t AS SELECT * FROM read_csv('data.csv')");
const table = ctx.executeSync("SELECT * FROM t");

const result = table
  .filter(col('price').gt(10))
  .sort('price')
  .head(5)
  .collectSync();

console.log(result.columns, result.nRows);

ctx.destroy();

What's Next