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

Web REPL

The fastest way to start exploring data is the built-in browser-based SQL console:

node bin/teide.js

This opens a SQL console at http://127.0.0.1:3141 with a CodeMirror editor, autocomplete, and virtual-scrolling result tables. Load a CSV file and start querying:

.load path/to/sales.csv
SELECT category, SUM(price) FROM sales GROUP BY category;

To specify column types explicitly, use types or read_csv():

.load data.csv types i32,sym,f64
SELECT * FROM read_csv('data.csv', 'i32,sym,f64');

Press Ctrl+Enter to execute. See the Web REPL guide for the full interface reference.

Node.js API

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