Class DataAPIClient

Overview

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

💡Tip: Prefer this overload when using a db-scoped token instead of a more universal token.

Example

const client = new DataAPIClient();

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

// Will throw error as no token is ever provided
const db2 = client.db('<endpoint>');
Copy

Overview

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().

💡Tip: Prefer this overload when using a universal/admin-scoped token.

Example

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

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

// OK; will use <default_token>
const db2 = client.db('<endpoint>');
Copy

Overview (Astra-only)

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

⚠️Warning: This method is only available for Astra databases. If you try to use it with a non-Astra database, it will throw an error.

Example

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

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

The options hierarchy

The options for the AstraAdmin instance are a deep merge of the options for the DataAPIClient and the options for the AstraAdmin itself.

Overview

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

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

Example

const client = new DataAPIClient(...);
await client.close();

// Error: Can't make requests on a closed client
const coll = client.db(...).collection(...);
await coll.findOne();
Copy

Idempotency

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

When to call this method

For most users, this method is not 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 strictly necessary when the resources are used for the duration of the program, but it's there for when you need it.

Overview

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

Example

const db = client.db('http://localhost:8181');

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

Disclaimer

🚨Important: This does not verify the existence of the database—it only creates a reference.

Use AstraAdmin.createDatabase to create a new database if you need to.

It is on the user to ensure that the database endpoint is correct.

The API endpoint

This endpoint should include the protocol and the hostname, but not the path.

If you're using Astra, this will typically be of the form https://<db_id>-<region>.apps.astra.datastax.com (the exception being private endpoints); any other database may have a completely unique domain.

⚠️Warning: Spawning a db using an ID and region is no longer supported in astra-db-ts v2.0+.

Use the buildAstraEndpoint to create the endpoint if you need to.

The options hierarchy

The options for the Db instance are a deep merge of the options for the DataAPIClient and the options for the Db itself.

Any options provided to DbOptions may generally also be overridden in any spawned classes' options (e.g. CollectionOptions).

Example

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

const coll = db.collection('my_coll', {
  keyspace: 'other_keyspace',
});
Copy