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

The client takes 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 be overridden as necessary.

Example

const client = new DataAPIClient('AstraCS:...');

const db1 = client.db('https://<db_id>-<region>.apps.astra.datastax.com');
const db2 = client.db('my-database', 'us-east1');

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

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

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

Hierarchy (view full)

Constructors

Properties

#options: InternalRootClientOpts
[asyncDispose]: (() => Promise<void>)

Allows for the await using syntax (if your typescript version >= 5.2) to automatically close the client when it's out of scope.

Equivalent to wrapping the client usage in a try/finally block and calling client.close() in the finally block.

Type declaration

    • (): Promise<void>
    • Returns Promise<void>

Example

async function main() {
  // Will unconditionally close the client when the function exits
  await using client = new DataAPIClient('*TOKEN*');

  // Using the client as normal
  const db = client.db('*ENDPOINT*');
  console.log(await db.listCollections());

  // Or pass it to another function to run your app
  app(client);
}
main();

This will only be defined if the Symbol.asyncDispose symbol is actually defined.

Methods

  • Type Parameters

    • E extends (keyof DataAPICommandEvents) | (keyof AdminCommandEvents)

    Parameters

    Returns this

  • 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);
  • 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.

  • 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: DbSpawnOptions

      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', {
      namespace: 'my-namespace',
      useHttp2: false,
    });

    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.

  • 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 overload is purely for user convenience, but it only supports using Astra as the underlying database. For DSE or any other Data-API-compatible endpoint, use the other overload instead.

    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

    • id: string

      The database ID to use.

    • region: string

      The region to use.

    • Optional options: DbSpawnOptions

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

    Returns Db

    A new Db instance.

    Example

    const db1 = client.db('a6a1d8d6-31bc-4af8-be57-377566f345bf', 'us-east1');

    const db2 = client.db('a6a1d8d6-31bc-4af8-be57-377566f345bf', 'us-east1', {
      namespace: 'my-namespace',
      useHttp2: false,
    });

    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.

  • Type Parameters

    • E extends (keyof DataAPICommandEvents) | (keyof AdminCommandEvents)

    Parameters

    Returns boolean

  • Returns (string | symbol)[]

  • Returns number

  • Type Parameters

    • E extends (keyof DataAPICommandEvents) | (keyof AdminCommandEvents)

    Parameters

    • event: E

    Returns number

  • Type Parameters

    • E extends (keyof DataAPICommandEvents) | (keyof AdminCommandEvents)

    Parameters

    • event: E

    Returns DataAPIClientEvents[E][]

  • Type Parameters

    • E extends (keyof DataAPICommandEvents) | (keyof AdminCommandEvents)

    Parameters

    Returns this

  • Type Parameters

    • E extends (keyof DataAPICommandEvents) | (keyof AdminCommandEvents)

    Parameters

    Returns this

  • Type Parameters

    • E extends (keyof DataAPICommandEvents) | (keyof AdminCommandEvents)

    Parameters

    Returns this

  • Type Parameters

    • E extends (keyof DataAPICommandEvents) | (keyof AdminCommandEvents)

    Parameters

    Returns this

  • Type Parameters

    • E extends (keyof DataAPICommandEvents) | (keyof AdminCommandEvents)

    Parameters

    Returns this

  • Type Parameters

    • E extends (keyof DataAPICommandEvents) | (keyof AdminCommandEvents)

    Parameters

    • event: E

    Returns DataAPIClientEvents[E][]

  • Type Parameters

    • E extends (keyof DataAPICommandEvents) | (keyof AdminCommandEvents)

    Parameters

    • Optional event: E

    Returns this

  • Type Parameters

    • E extends (keyof DataAPICommandEvents) | (keyof AdminCommandEvents)

    Parameters

    Returns this

  • Parameters

    • maxListeners: number

    Returns this