oceanum-js

@oceanum/datamesh

@oceanum/datamesh / index / Connector

Class: Connector

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

Constructors

Constructor

new Connector(token?, options?): Connector

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

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.

adminService?

string

URL of the oceanum.io admin service that serves notices about datasources. Defaults to “https://admin.oceanum.io” for the Datamesh service “https://datamesh.oceanum.io” (“https://admin.oceanum.tech” for “https://datamesh.oceanum.tech”); for any other service, notices are not fetched unless this is set.

gateway?

string

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

jwtAuth?

string

JWT for Oceanum service.

nocache?

boolean

Disable caching of datamesh results.

notices?

boolean

Check for notices when a datasource is queried or loaded, and console.warn about action_required and outage notices (see getNotices). Defaults to true: the first query of each datasource then sends this connector’s credential (Datamesh token or JWT) to the admin service, which forwards it to Datamesh to check access. Set to false to turn this off.

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:115

service?

optional service?: string

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

LAZY_LOAD_SIZE

static LAZY_LOAD_SIZE: number = 1e8

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

Accessors

host

Get Signature

get host(): string

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

Get datamesh host.

Returns

string

The datamesh server host.

Methods

closeSession()

closeSession(finaliseWrite?): Promise<void>

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

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:244

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:391

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:526

Get a datasource instance from the datamesh.

Parameters

datasourceId

string

Unique datasource ID.

Returns

Promise<Datasource>

The datasource instance.

Throws

getNotices()

getNotices(datasourceId): Promise<Notice[]>

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

Get the published, unexpired oceanum.io notices about a datasource, such as deprecations, changes or outages, newest first.

Notices are requested from the admin service (see the adminService constructor option) with this connector’s own credential, which the admin service forwards to Datamesh to check access: notices are only returned for datasources that credential can read. Results are cached per datasource for 10 minutes (a failed request for 30 seconds).

This never throws: if no admin service is known for the Datamesh service, the request fails or takes longer than 3 seconds, or the datasource is unknown or not readable, it resolves to an empty list. Malformed notices are left out.

Parameters

datasourceId

string

Unique datasource ID.

Returns

Promise<Notice[]>

The datasource’s notices, newest first; empty if there are none.

getSession()

getSession(): Promise<Session>

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

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:547

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:510

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:444

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:307

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:411

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:210

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.