Clients

Official native clients are listed on this page.

• JavaScript
• Python

For other programming languages, it is possible to create small client libraries such as these using the HTTP and WebSocket APIs.

The clients support both HTTP and WebSocket APIs. To access Endb over HTTP, create an Endb instance and call the sql method on it. To access Endb over WebSockets, create an EndbWebSocket instance and call the sql method on it.

JavaScript

NPM Package: @endatabas/endb

Install

npm install @endatabas/endb
npm install ws

Usage Examples

Import

import { Endb, EndbWebSocket } from '@endatabas/endb';

Endb

Use the Endb class to communicate with Endb over HTTP. It accepts an optional url parameter. Options can be supplied for accept, username, and password. Accept headers default to LD-JSON and can be set to any valid content type listed in the HTTP API. If you choose application/vnd.apache.arrow.file or application/vnd.apache.arrow.stream, the raw response body will be be returned from sql().

var e = new Endb();
var e = new Endb('http://localhost:3803/sql');
var e = new Endb('http://localhost:3803/sql', {accept: 'text/csv'});
var e = new Endb('http://localhost:3803/sql', {accept: 'application/json', username: 'zig', password: 'zag'});

NOTE: Choosing accept headers other than LD-JSON will return JavaScript data structures symmetrical with those returned from the respective accept header provided to the HTTP API. text/csv returns comma-delimited strings, application/json returns tuples as arrays, and so on.

EndbWebSocket

Use the EndbWebSocket class to communicate with Endb over WebSockets. It accepts an optional url parameter. Options can be supplied for ws (any implementation of the JavaScript WebSocket interface definition), username, and password. In a web browser, ws will default to the web browser's WebSocket implementation. EndbWebSocket only communicates in LD-JSON, so the accept header cannot be set.

// in web browser:
var ews = new EndbWebSocket();
var ews = new EndbWebSocket('ws://localhost:3803/sql', {username: 'zig', password: 'zag'});

// in node.js:
import WebSocket from 'ws';
var ews = new EndbWebSocket({ws: WebSocket});
var ews = new EndbWebSocket('ws://localhost:3803/sql', {ws: WebSocket, username: 'zig', password: 'zag'});

sql()

The asynchronous sql method is available to both Endb and EndbWebSocket. It accepts q, and optional p, m, and accept parameters and returns an array of strongly-typed documents. (See JavaScript API Reference.)

To ignore the p or m parameters but still supply an accept header, supply the default values or null.

e.sql("SELECT * FROM users;");
e.sql("INSERT INTO USERS (date, name, email) VALUES (?, ?, ?);", [new Date(), 'Aaron', 'aaron@canadahealth.ca']);
e.sql("INSERT INTO USERS (name) VALUES (?);", [['Aaron'], ['Kurt'], ['Cindy']], true);
e.sql("SELECT * FROM users;", [], false, 'text/csv');
e.sql("SELECT * FROM users;", null, null, 'application/json');
e.sql("INSERT INTO USERS (name) VALUES (?);", [['Aaron'], ['Kurt'], ['Cindy']], true, 'text/csv');

It is possible to use Template Literals (string templating) to pass named SQL parameters. The signature which accepts Template Literals does not accept any other parameters to the method:

var n = 'Michael';
e.sql`INSERT INTO USERS (name) VALUES (${n});`;

Data Types

When an LD-JSON (default) accept header is used, strongly typed data is returned according to this mapping:

• null - null
• xsd:date - Date
• xsd:dateTime - Date
• xsd:base64Binary - Uint8Array
• xsd:integer - BigInt

For more information on Endb data types, see the Data Types doc.

Complete Examples

import { Endb } from '@endatabas/endb';

var e = new Endb();
await e.sql("INSERT INTO users {name: 'Thupil'};");
var result = await e.sql("SELECT * FROM users;");
console.log(result);

var e2 = new Endb('http://localhost:3803/sql', {accept: 'application/json', username: 'zig', password: 'zag'});
await e.sql("INSERT INTO USERS (name) VALUES (?);", [['Aaron'], ['Kurt'], ['Cindy']], true, 'text/csv');
result = await e.sql("SELECT * FROM users;", null, null, 'application/json');
console.log(result);

import WebSocket from 'ws';
import { EndbWebSocket } from '@endatabas/endb';

var ews = new EndbWebSocket({ws: WebSocket});
await ews.sql("insert into users {name: 'Lydia'};");
var ws_result = await ews.sql("select * from users;");
console.log(ws_result);

var ews2 = new EndbWebSocket({ws: WebSocket, username: 'zig', password: 'zag'});
await ews2.sql("INSERT INTO USERS (name) VALUES (?);", [['Aaron'], ['Kurt'], ['Cindy']], true, 'text/csv');
ws_result = await ews2.sql("SELECT * FROM users;", null, null, 'application/json');
console.log(ws_result);

JavaScript API Reference

NOTE: The following API documentation is generated from source code docstrings in the endb repository.

Classes

Endb

Endatabas client for the HTTP API

EndbWebSocket

Endatabas client for the WebSocket API

Endb

Endatabas client for the HTTP API

Kind: global class

• Endb
  • new Endb([url], [opt])
  • .sql(q, [p], [m], [accept]) ⇒ Promise.<Array>

new Endb([url], [opt])

Create an Endb object (Endatabas client for the HTTP API)

endb.sql(q, [p], [m], [accept]) ⇒ Promise.<Array>

Execute a SQL statement over HTTP

Kind: instance method of Endb
Returns: Promise.<Array> - - Array of documents

Example

// Simple query
sql("SELECT * FROM users;");
// Positional parameters
sql("INSERT INTO users (date, name) VALUES (?, ?);", [new Date(), 'Aaron']);
// Named parameters
sql("INSERT INTO users {date: :d, name: :n};", {d: new Date(), n: 'Aaron'});
// Many positional parameters (batches)
sql("INSERT INTO users (name) VALUES (?);", [['Aaron'], ['Kurt'], ['Cindy']], true);
// Many named parameters (batches)
sql("INSERT INTO users {name: :n};", [{n: 'Judy'}, {n: 'Addis'}], true);
// All parameters (many parameters and accept header)
sql("INSERT INTO users (name) VALUES (?);", [['Aaron'], ['Kurt'], ['Cindy']], true, 'text/csv');
// Named parameters via Template Literals
sql(`INSERT INTO users (name) VALUES (${u});`, [{u: 'Michael'}]);

EndbWebSocket

Endatabas client for the WebSocket API

Kind: global class

• EndbWebSocket
  • new EndbWebSocket([url], [opt])
  • .sql(q, [p], [m], [accept]) ⇒ Promise.<Array>

new EndbWebSocket([url], [opt])

Create an EndbWebSocket object (Endatabas client for the WebSocket API)

endbWebSocket.sql(q, [p], [m], [accept]) ⇒ Promise.<Array>

Execute a SQL statement over a WebSocket with LD-JSON

Kind: instance method of EndbWebSocket
Returns: Promise.<Array> - - Array of documents

Example

// Simple query
sql("SELECT * FROM users;");
// Positional parameters
sql("INSERT INTO users (date, name) VALUES (?, ?);", [new Date(), 'Aaron']);
// Named parameters
sql("INSERT INTO users {date: :d, name: :n};", {d: new Date(), n: 'Aaron'});
// Many positional parameters (batches)
sql("INSERT INTO users (name) VALUES (?);", [['Aaron'], ['Kurt'], ['Cindy']], true);
// Many named parameters (batches)
sql("INSERT INTO users {name: :n};", [{n: 'Judy'}, {n: 'Addis'}], true);
// All parameters (many parameters and accept header)
sql("INSERT INTO users (name) VALUES (?);", [['Aaron'], ['Kurt'], ['Cindy']], true, 'text/csv');
// Named parameters via Template Literals
sql(`INSERT INTO users (name) VALUES (${u});`, [{u: 'Michael'}]);

Python

PyPI Package: endb

Install

pip install endb
pip install websockets  # optional WebSocket support
pip install pyarrow     # optional Apache Arrow support

Usage Examples

Import

from endb import (Endb, EndbWebSocket)

Endb

Use Endb to communicate with Endb over HTTP. It accepts optional url, accept, username, and password parameters. Accept headers default to LD-JSON and can be set to any valid content type listed in the HTTP API. If you have pyarrow installed, you can also use application/vnd.apache.arrow.file and application/vnd.apache.arrow.stream.

e = Endb()
e = Endb('http://localhost:3803/sql')
e = Endb('http://localhost:3803/sql', 'text/csv')
e = Endb('http://localhost:3803/sql', 'application/json', 'zig', 'zag')

NOTE: Choosing accept headers other than LD-JSON will return Python data structures symmetrical with those returned from the respective accept header provided to the HTTP API. text/csv returns comma-delimited strings, application/json returns tuples as lists, and so on.

EndbWebSocket

Use the EndbWebSocket class to communicate with Endb over WebSockets. It accepts optional url, username, and password parameters.

ews = EndbWebSocket()
ews = EndbWebSocket('ws://localhost:3803/sql', 'zig', 'zag')

sql()

The sql method is available to both Endb and EndbWebSocket. It accepts q, and optional p, m, and accept parameters and returns an list of strongly-typed documents. (See Python API Reference.)

It is sychronous for Endb and asynchronous for EndbWebSocket. To ignore the p or m parameters but still supply an accept header, supply the default values or use a named (accept) parameter.

from datetime import date, datetime, timezone
e.sql("INSERT INTO USERS (date, name, email) VALUES (?, ?, ?);", [datetime.now(timezone.utc), 'Aaron', 'aaron@canadahealth.ca'])
e.sql("INSERT INTO USERS (name) VALUES (?);", [['Aaron'], ['Kurt'], ['Cindy']], True)
e.sql("SELECT * FROM users;", [], False, 'text/csv')
e.sql("SELECT * FROM users;", accept = 'text/csv')
e.sql("INSERT INTO USERS (name) VALUES (?);", [['Aaron'], ['Kurt'], ['Cindy']], True, 'text/csv')

Data Types

When an LD-JSON (default) accept header is used, strongly typed data is returned according to this mapping:

• null - None
• xsd:date - datetime.date
• xsd:time - datetime.time
• xsd:dateTime - datetime.datetime
• xsd:base64Binary - bytes (from base64)
• xsd:integer - int

Complete Examples

from endb import Endb
from datetime import date, datetime, timezone
e = Endb()
e.sql("INSERT INTO users {name: 'Yuvi'}")
e.sql("SELECT * FROM users;")

e2 = Endb('http://localhost:3803/sql', 'application/json', 'zig', 'zag')
e2.sql("INSERT INTO USERS (name) VALUES (?);", [['Aaron'], ['Kurt'], ['Cindy']], True, 'text/csv')
e2.sql("SELECT * FROM users;", [], False, 'application/json')

When the websockets dependency is installed, it is possible to return asynchronous results to the Python interactive shell directly if you start it with python3 -m asyncio:

from endb import EndbWebSocket
ews = EndbWebSocket()
await ews.sql("INSERT INTO users {name: 'Lydia'}")
ws_result = await ews.sql("SELECT * FROM users;")
print(ws_result)

ews2 = EndbWebSocket(username = 'zig', password = 'zag')
await ews2.sql("INSERT INTO USERS (name) VALUES (?);", [['Aaron'], ['Kurt'], ['Cindy']], True, 'text/csv')
ws_result = await ews2.sql("SELECT * FROM users;", [], False, 'application/json')
print(ws_result)

Python API Reference

NOTE: The following API documentation is generated from source code docstrings in the endb repository.

endb module

class endb.Endb(url='http://localhost:3803/sql', accept='application/ld+json', username=None, password=None)

Bases: AbstractEndb

An Endatabas client for the HTTP API

url

HTTP URL of an Endatabas instance

• Type: str

accept

Accept header content type

• Type: str

username

Username for HTTP Basic Auth

• Type: str

password

Password for HTTP Basic Auth

• Type: str

sql(q, p=[], m=False, accept=None)

Executes a SQL statement

The SQL statement is sent to Endb.url over HTTP.

• Parameters:
  • q (str) – SQL statement or query to execute
  • p (array_like , default= [ ]) – Positional or named SQL parameters (or an array of either, if using many parameters)
  • m (bool , default=False) – Many parameters flag
  • accept (str , optional) – Accept header content type (defaults to Endb.accept)
• Raises: TypeError – Internal error if attempting to translate an unknown type to LD-JSON.

class endb.EndbWebSocket(url='ws://localhost:3803/sql', username=None, password=None)

Bases: AbstractEndb

An Endatabas client for the HTTP API

url

HTTP URL of an Endatabas instance

• Type: str

username

Username for HTTP Basic Auth

• Type: str

password

Password for HTTP Basic Auth

• Type: str

async close()

Closes the WebSocket connection

async sql(q, p=[], m=False, accept=None)

Executes a SQL statement

The SQL statement is sent to Endb.url over WebSockets.

• Parameters:
  • q (str) – SQL statement or query to execute
  • p (array_like , default= [ ]) – Positional or named SQL parameters (or an array of either, if using many parameters)
  • m (bool , default=False) – Many parameters flag
  • accept (str , optional) – Ignored. WebSocket communication is always in LD-JSON.
• Raises:
  • AssertionError – If ‘id’ of request and response do not match.
  • RuntimeError – If response from server contains an error.