Class DataAPIClient

Overview

The main entrypoint into working with the Data API. It sits at the top of the conceptual hierarchy of the SDK.

The client may take in a default token, which can be overridden by a stronger/weaker token when spawning a new Db or AstraAdmin instance.

It also takes in a set of default options (see DataAPIClientOptions) that may also generally be overridden as necessary.

Depending on the Data API backend used, you may need to set the environment option to "dse", "hcd", etc. See DataAPIEnvironment for all possible backends. It defaults to "astra".

Example

// Client with default token
const client1 = new DataAPIClient('AstraCS:...');

// Client with no default token; must provide token in .db() or .admin()
const client2 = new DataAPIClient();

// Client connecting to a local DSE instance
const dseToken = new UsernamePasswordTokenProvider('username', 'password');
const client3 = new DataAPIClient(dseToken, { environment: 'dse' });

const db1 = client1.db('https://<db_id>-<region>.apps.astra.datastax.com');
const db2 = client1.db('<db_id>', '<region>');

const coll = await db1.collections('my-collections');

const admin1 = client1.admin();
const admin2 = client1.admin({ adminToken: '<stronger_token>' });

console.log(await coll.insertOne({ name: 'John Joe' }));
console.log(await admin1.listDatabases());

See

DataAPIEnvironment

Hierarchy (view full)

Constructors

constructor

Properties

#listeners #options #parent

Methods

admin close db emit off on once removeAllListeners

Constructors

constructor

  • new DataAPIClient(options?): DataAPIClient

  • Constructs a new instance of the DataAPIClient without a default token. The token will instead need to be specified when calling .db() or .admin().

    Prefer this method when using a db-scoped token instead of a more universal token.

    Parameters

    Returns DataAPIClient

    Example

    const client = new DataAPIClient();

    // OK
    const db1 = client.db('<db_id>', '<region>', { token: 'AstraCS:...' });

    // Will throw error as no token is ever provided
    const db2 = client.db('<db_id>', '<region>');
  • new DataAPIClient(token, options?): DataAPIClient

  • Constructs a new instance of the DataAPIClient with a default token. This token will be used everywhere if no overriding token is provided in .db() or .admin().

    Prefer this method when using a universal/admin-scoped token.

    Parameters

    Returns DataAPIClient

    Example

    const client = new DataAPIClient('<default_token>');

    // OK
    const db1 = client.db('<db_id>', '<region>', { token: '<weaker_token>' });

    // OK; will use <default_token>
    const db2 = client.db('<db_id>', '<region>');

Properties

Private Readonly Internal #listeners

#listeners: Partial<Record<(keyof AdminCommandEventMap) | (keyof CommandEventMap), ((event) => void)[]>> = {}

Private Readonly #options

#options: ParsedRootClientOpts

Private Readonly Internal #parent

#parent: null | Pick<HierarchicalEmitter<DataAPIClientEventMap>, "emit">

Methods

admin

  • admin(options?): AstraAdmin

  • Spawns a new AstraAdmin instance using the given options to work with the DevOps API (for admin work such as creating/managing databases).

    NB. This method is only available for Astra databases.

    The given options will override any default options set when creating the DataAPIClient through a deep merge (i.e. unset properties in the options object will just default to the default options).

    Parameters

    Returns AstraAdmin

    A new AstraAdmin instance.

    Example

    const admin1 = client.admin();
    const admin2 = client.admin({ adminToken: '<stronger_token>' });

    const dbs = await admin1.listDatabases();
    console.log(dbs);

close

  • close(): Promise<void>

  • Closes the client and disconnects all underlying connections. This should be called when the client is no longer needed to free up resources.

    The client will be no longer usable after this method is called.

    Returns Promise<void>

    A promise that resolves when the client has been closed.

    Remarks

    This method is idempotent and can be called multiple times without issue.

    --

    For most users, this method isn't necessary to call, as resources will be freed up when the server is shut down or the process is killed. However, it's useful in long-running processes or when you want to free up resources immediately.

    --

    Think of it as using malloc or using a file descriptor. Freeing them isn't always strictly necessary for long-running usages, but it's there for when you need it.

db

  • db(endpoint, options?): Db

  • Spawns a new Db instance using a direct endpoint and given options.

    NB. This method does not validate the existence of the database—it simply creates a reference.

    This endpoint should include the protocol and the hostname, but not the path. It's typically in the form of https://<db_id>-<region>.apps.astra.datastax.com, but it can be used with DSE or any other Data-API-compatible endpoint.

    The given options will override any default options set when creating the DataAPIClient through a deep merge (i.e. unset properties in the options object will just default to the default options).

    Parameters

    • endpoint: string

      The direct endpoint to use.

    • Optional options: DbOptions

      Any options to override the default options set when creating the DataAPIClient.

    Returns Db

    A new Db instance.

    Example

    const db1 = client.db('https://<db_id>-<region>.apps.astra.datastax.com');

    const db2 = client.db('https://<db_id>-<region>.apps.astra.datastax.com', {
      keyspace: 'my-keyspace',
      useHttp2: false,
    });

    const db3 = client.db('https://<db_id>-<region>.apps.astra.datastax.com', {
      token: 'AstraCS:...'
    });

    Remarks

    Note that this does not perform any IO or validation on if the endpoint is valid or not. It's up to the user to ensure that the endpoint is correct. If you want to create an actual database, see AstraAdmin.createDatabase instead.

emit

  • emit<E>(eventName, event): void

  • Emit an event.

    Should probably never be used by the user directly.

    Note: Errors thrown by any listeners will be silently ignored. It will not stop the propagation of the event.

    Type Parameters

    • E extends (keyof AdminCommandEventMap) | (keyof CommandEventMap)

    Parameters

    Returns void

    true if the event had listeners, false otherwise.

off

on

  • on<E>(eventName, listener): (() => void)

  • Subscribe to an event.

    Type Parameters

    • E extends (keyof AdminCommandEventMap) | (keyof CommandEventMap)

    Parameters

    • eventName: E

      The event to listen for.

    • listener: ((event) => void)

      The callback to invoke when the event is emitted.

    Returns (() => void)

    A function to unsubscribe the listener.

      • (): void

      • Returns void

once

  • once<E>(eventName, listener): (() => void)

  • Subscribe to an event once.

    The listener will be automatically unsubscribed after the first time it is called.

    Note that the listener will be unsubscribed BEFORE the actual listener callback is invoked.

    Type Parameters

    • E extends (keyof AdminCommandEventMap) | (keyof CommandEventMap)

    Parameters

    • eventName: E

      The event to listen for.

    • listener: ((event) => void)

      The callback to invoke when the event is emitted.

    Returns (() => void)

    A function to prematurely unsubscribe the listener.

      • (): void

      • Returns void

removeAllListeners

Settings

Member Visibility

Theme

On This Page

constructor#listeners#options#parentadminclosedbemitoffononceremoveAllListeners