https://github.com/boilingdata/node-boilingdata
BoilingData JS client (NodeJS and Browsers)
https://github.com/boilingdata/node-boilingdata
Last synced: 11 months ago
JSON representation
BoilingData JS client (NodeJS and Browsers)
- Host: GitHub
- URL: https://github.com/boilingdata/node-boilingdata
- Owner: boilingdata
- License: mit
- Created: 2022-04-21T17:41:16.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-04-02T07:24:11.000Z (almost 2 years ago)
- Last Synced: 2024-04-24T10:34:00.131Z (almost 2 years ago)
- Language: TypeScript
- Homepage:
- Size: 639 KB
- Stars: 19
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# BoilingData WebSocket client JS/TS SDK
You can use this SDK both on browser and with NodeJS.
> See also BoilingData command line client tool: [https://github.com/boilingdata/boilingdata-bdcli](https://github.com/boilingdata/boilingdata-bdcli).
## Installing the SDK
```shell
yarn add @boilingdata/node-boilingdata
```
## Browser
Copy and add `browser/boilingdata.min.js` script to your HTML.
```html
const bdInstance = new BoilingData({ username: "myUsername", password: "myPw" });
let isConnected = false;
async function connectAndRunQuery() {
if (!isConnected) {
await bdInstance.connect();
isConnected = true;
}
const rows = await bdInstance.execQueryPromise({ sql: "SELECT 42;" });
console.log({ rows });
}
connectAndRunQuery();
```
## Basic Examples
`execQueryPromise()` method can be used to await for the results directly.
```shell
yarn install @boilingdata/node-boilingdata
# copy paste the example to example.mjs file.
BD_USERNAME= BD_PASSWORD= node example.mjs
```
```typescript
import { BoilingData } from "@boilingdata/node-boilingdata";
async function main() {
const bdInstance = new BoilingData({ username: process.env["BD_USERNAME"], password: process.env["BD_PASSWORD"] });
await bdInstance.connect();
const start = Date.now();
const sql = `SELECT COUNT(*) FROM parquet_scan('s3://boilingdata-demo/demo.parquet');`;
const rows = await bdInstance.execQueryPromise({ sql });
const stop = Date.now();
console.log(JSON.parse(JSON.stringify(rows)));
console.log("Query time measured from this script (ms):", stop - start);
await bdInstance.close();
}
main();
```
`execQuery()` uses callbacks.
```typescript
import { BoilingData, isDataResponse } from "@boilingdata/node-boilingdata";
async function main() {
const bdInstance = new BoilingData({ username: process.env["BD_USERNAME"], password: process.env["BD_PASSWORD"] });
await bdInstance.connect();
const sql = `SELECT COUNT(*) FROM parquet_scan('s3://boilingdata-demo/demo.parquet');`;
const rows = await new Promise((resolve, reject) => {
let r: any[] = [];
bdInstance.execQuery({
sql,
callbacks: {
onData: (data: IBDDataResponse | unknown) => {
if (isDataResponse(data)) data.data.map(row => r.push(row));
},
onQueryFinished: () => resolve(r),
onLogError: (data: any) => reject(data),
},
});
});
console.log(rows);
await bdInstance.close();
}
```
`getTapClientToken()` method can be used to fetch [Data Taps client token](https://www.taps.boilingdata.com/). You need fresh token when sending data to a Data Tap shared to you (or with your own Data Tap too). This API call does not require `connect()` method to be called as the request goes through via REST API rather than WebSocket API.
```typescript
const bdInstance = new BoilingData({ username: process.env["BD_USERNAME"], password: process.env["BD_PASSWORD"] });
// first argument is token lifetime, max "24h", 2nd argument is the sharing user (unless your own Tap). Both arguments are optional.
const tapClientToken = await bdInstance.getTapClientToken("24h", "dforsber@gmail.com");
```
This repository contains JS/TS BoilingData client SDK that can be used both with NodeJS and in browser. Please see the integration tests on `tests/query.test.ts` for for more examples.
### Callbacks
The SDK uses the BoilingData Websocket API in the background, meaning that events can arrive at any time. We use a range of global and query-specific callbacks to allow you to hook into the events that you care about.
All callbacks work in both the global scope and the query scope; i.e. global callbacks will always be executed when a message arrives, query callbacks will only be executed when messages relating to that query arrive.
- onRequest - This event happens when your application sends a request to BoilingData
- onData - Query data response. A single query may have many onData events as processing is parallelised in the background.
- onQueryFinished - The processing of data has completed, and you should not expect any further onData events (although more info messages may arrive)
- onLambdaEvent - the status of your datasets, i.e. warm, warmingUp, shutdown
- onSocketOpen - executed when the socket API successfully opens (so it is safe to start sending SQL queries)
- onSocketClose - executed when the socket API has closed (intentionally or not)
- onInfo - information about a query - connection time, query time, execution time, etc.
- onLogError - Log Errors, such as SQL syntax errors.
- onLogWarn - Log warning messages
- onLogInfo - Log info messages
- onLogDebug - Log debug messsages
#### Setting Global Callbacks
Global callbacks can be set when creating the BoilingData instance.
```typescript
new BoilingData({
username,
password,
globalCallbacks: {
onRequest: req => {
console.log("A new request has been made with ID", req.requestId);
},
onQueryFinished: req => {
console.log("Request complete!", req.requestId);
},
onLogError: message => {
console.error("LogError", message);
},
onSocketOpen: socketInstance => {
console.log("The socket has opened!");
},
onLambdaEvent: message => {
console.log("Change in status of dataset: ", message);
},
},
});
```
#### Setting Query-level Callbacks
Query callbacks are set when creating the query
```typescript
bdInstance.execQuery({
sql: `SELECT COUNT(*) AS count FROM parquet_scan('s3://boilingdata-demo/demo2.parquet');`,
callbacks: {
onData: data => {
console.log("Some data for this query arrived", data);
},
onQueryFinished: () => resolve(r),
onLogError: (data: any) => reject(data),
},
});
```