oceanum-js

@oceanum/datamesh

@oceanum/datamesh / index / Connector

Class: Connector

Defined in: packages/datamesh/src/lib/connector.ts:20

Constructors

Constructor

new Connector(token?, options?): Connector

Defined in: packages/datamesh/src/lib/connector.ts:46

Datamesh connector constructor

Parameters

token?

string = ...

Your datamesh access token. Defaults to environment variable DATAMESH_TOKEN is defined else as literal string “DATAMESH_TOKEN”. DO NOT put your Datamesh token directly into public facing browser code.

options?

Constructor options.

gateway?

string

URL of gateway service. Defaults to “https://gateway.".

jwtAuth?

string

JWT for Oceanum service.

nocache?

boolean

Disable caching of datamesh results.

service?

string

URL of datamesh service. Defaults to environment variable DATAMESH_SERVICE or “https://datamesh.oceanum.io”.

sessionDuration?

number

The desired length of time for acquired datamesh sessions in hours. Will be 1 hour by default.

Returns

Connector

Throws

Properties

gateway?

optional gateway?: string

Defined in: packages/datamesh/src/lib/connector.ts:31

service?

optional service?: string

Defined in: packages/datamesh/src/lib/connector.ts:30

LAZY_LOAD_SIZE

static LAZY_LOAD_SIZE: number = 1e8

Defined in: packages/datamesh/src/lib/connector.ts:21

Accessors

host

Get Signature

get host(): string

Defined in: packages/datamesh/src/lib/connector.ts:101

Get datamesh host.

Returns

string

The datamesh server host.

Methods

closeSession()

closeSession(finaliseWrite?): Promise<void>

Defined in: packages/datamesh/src/lib/connector.ts:460

Close the current session if one exists.

Parameters

finaliseWrite?

boolean = false

Whether to finalise any write operations. Defaults to false.

Returns

Promise<void>

A promise that resolves when the session is closed.

createSession()

createSession(options?): Promise<Session>

Defined in: packages/datamesh/src/lib/connector.ts:144

Create a new session.

Parameters

options?

Session options.

duration?

number

The desired length of time for the session in hours. Defaults to the value set in the constructor or 1 hour.

Returns

Promise<Session>

A new session instance.

getDataObject()

getDataObject(qhash, format): Promise<ArrayBuffer>

Defined in: packages/datamesh/src/lib/connector.ts:291

Download a staged query’s data in a given file format.

Fetches the staged result from the gateway with the requested f format (e.g. “nc” for NetCDF, “csv”, “geojson”, “arrow”) and returns the raw response bytes. Use stageRequest first to obtain the qhash (and to inspect formats/coordkeys).

Parameters

qhash

string

The hash of a staged query (from stageRequest).

format

string

The f query parameter, e.g. “nc” for NetCDF.

Returns

Promise<ArrayBuffer>

The raw response body as an ArrayBuffer.

getDatasource()

getDatasource(datasourceId): Promise<Datasource>

Defined in: packages/datamesh/src/lib/connector.ts:424

Get a datasource instance from the datamesh.

Parameters

datasourceId

string

Unique datasource ID.

Returns

Promise<Datasource>

The datasource instance.

Throws

getSession()

getSession(): Promise<Session>

Defined in: packages/datamesh/src/lib/connector.ts:158

Get the current session, or create a new one if none exists or the current one has expired.

Returns

Promise<Session>

The current session.

loadDatasource()

loadDatasource(datasourceId, parameters?): Promise<Dataset<HttpZarr | TempZarr> | null>

Defined in: packages/datamesh/src/lib/connector.ts:445

Load a datasource into the work environment.

Parameters

datasourceId

string

Unique datasource ID.

parameters?

Record<string, string | number> = {}

Additional datasource parameters.

Returns

Promise<Dataset<HttpZarr | TempZarr> | null>

The dataset.

openZarr()

openZarr(url, options?): Promise<Dataset<HttpZarr>>

Defined in: packages/datamesh/src/lib/connector.ts:408

Open a staged query’s zarr store with the connector’s session attached.

Use this for lazy or schema-only access to a staged result — e.g. reading dimensions and variables from .zmetadata without downloading chunks. It attaches the same session + auth headers as query, so callers never hand-roll zarr auth headers: the gateway requires a v1 session on every /zarr/query request and returns 401 "Session ID required" without it.

Parameters

url

string

Full zarr store URL, e.g. ${gateway}${stage.zarr_endpoint}.

options?

ZarrOptions = {}

Zarr open options (coordkeys, parameters, ttl, timeout, …).

Returns

Promise<Dataset<HttpZarr>>

A lazily-opened Dataset backed by the staged zarr store.

query()

query(query, options?): Promise<Dataset<HttpZarr | TempZarr> | null>

Defined in: packages/datamesh/src/lib/connector.ts:344

Execute a query to the datamesh.

Parameters

query

IQuery

The query to execute.

options?
timeout?

number

Additional options for the query.

Returns

Promise<Dataset<HttpZarr | TempZarr> | null>

The response from the server.

renewSession()

renewSession(stale?): Promise<Session>

Defined in: packages/datamesh/src/lib/connector.ts:207

Replace a session the gateway has rejected (401): oceanql sessions can be terminated server-side after inactivity, BEFORE their declared end time, so the endTime check in getSession() is not sufficient. Drops the cached session only if it is still the stale one (a concurrent caller may already have replaced it) and acquires a fresh session — concurrent renewals share one acquisition via getSession()’s single-flight.

Parameters

stale?

Session

The session that was rejected.

Returns

Promise<Session>

A fresh session.

stageRequest()

stageRequest(query): Promise<Stage | null>

Defined in: packages/datamesh/src/lib/connector.ts:311

Stage a query to the datamesh.

Parameters

query

IQuery

The query to stage.

Returns

Promise<Stage | null>

The staged response.

status()

status(): Promise<boolean>

Defined in: packages/datamesh/src/lib/connector.ts:110

Check the status of the metadata server.

Returns

Promise<boolean>

True if the server is up, false otherwise.

This site is open source. Improve this page.