wherobots-sql-driver
v0.1.0-alpha.2
Published
TypeScript SDK for Wherobots DB
Downloads
200
Maintainers
Readme
Wherobots TypeScript SDK
TypeScript SDK for interacting with WherobotsDB. This package implements a Node.js client that programmatically connects to a WherobotsDB runtime and execute Spatial SQL queries.
:warning: WARNING: This package is currently in Alpha. It is not recommended for use in production. API interfaces are subject to change.
Prerequisites
- Node.js version 18 or higher
- TypeScript version 5.x (if using TypeScript)
- A Wherobots API Key. See the Wherobots API Key Documentation for instructions on how to generate a key.
Installation
$ npm install wherobots-sql-driver
Usage
Example: Executing SQL statement and printing results
This example follows the typical pattern of an async
function to establish the connection to WherobotsDB.
After establishing this connection, you can call async
methods to execute SQL queries through this connection.
import { Connection, Runtime } from "wherobots-sql-driver";
(async () => {
const conn = await Connection.connect({
apiKey: "YOUR-WHEROBOTS-API-KEY",
runtime: Runtime.SEDONA,
});
const results = await conn.execute("SHOW SCHEMAS IN wherobots_open_data");
console.log(JSON.stringify(results.toArray(), null, 2));
conn.close();
})();
Running this example returns the results of the query as JSON:
[
{
"namespace": "overture"
},
{
"namespace": "overture_2024_02_15"
},
{
"namespace": "overture_2024_05_16"
},
{
"namespace": "overture_2024_07_22"
},
{
"namespace": "test_db"
}
]
Code example explanation
- Calling
Connection.connect()
asynchronously establishes a SQL Session connection in Wherobots Cloud and returns aConnection
instance. - Calling the connection's
execute()
methods runs the given SQL statement and asynchronously returns the result as an Apache Arrow Table instance. - The Arrow Table instance can be converted to a primitive by calling
toArray()
, and then printed to the console as formatted JSON withJSON.stringify()
. - Calling the connection's
close()
method tears down the SQL Session connection.
- Paste the contents of the above code example into a file called
wherobots-example.js
- Run the example with:
node wherobots-example.js
- Paste the contents of the above code example into a file called
wherobots-example.ts
- Run the example with:
npx tsx wherobots-example.ts
Runtime and region selection
You can chose the Wherobots runtime you want to use using the runtime
parameter, passing in one of the Runtime
enum values. For more
information on runtime sizing and selection, please consult the
Wherobots product documentation.
Additional parameters
The Connection.connect()
can take the following additional options:
resultsFormat
: one of theResultsFormat
enum values; Arrow encoding is the default and most efficient format for receiving query results.- NOTE: currently only Arrow encoding is supported
dataCompression
: one of theDataCompression
enum values; Brotli compression is the default and the most efficient compression algorithm for receiving query results.- NOTE: currently only Brotli compression is supported
geometryRepresentation
: one of theGeometryRepresentation
enum values; selects the encoding of geometry columns returned to the client application. The default is EWKT (string) and the most convenient for human inspection while still being usable by geospatial data manipulation libraries.region
: Currently, the only supported Wherobots compute region isaws-us-west-2
, in AWS's Oregon (us-west-2
) region.