Class Db

Use DataAPIClient.db to obtain an instance of this class.

The ID of the database, if it's an Astra database. If it's not an Astra database, this will throw an error.

Throws

Error - if the database is not an Astra database.

The default namespace to use for all operations in this database, unless overridden in a method call.

Example

// Uses 'default_keyspace' as the default namespace for all future db spawns
const client1 = new DataAPIClient('*TOKEN*');

// Overrides the default namespace for all future db spawns
const client2 = new DataAPIClient('*TOKEN*', {
  dbOptions: { namespace: 'my_namespace' },
});

// Created with 'default_keyspace' as the default namespace
const db1 = client1.db('*ENDPOINT*');

// Created with 'my_namespace' as the default namespace
const db2 = client1.db('*ENDPOINT*', {
  namespace: 'my_namespace'
});

// Uses 'default_keyspace'
const coll1 = db1.collection('users');

// Uses 'my_namespace'
const coll2 = db1.collection('users', {
  namespace: 'my_namespace'
});
Copy

Spawns a new AstraDbAdmin instance for this database, used for performing administrative operations on the database, such as managing namespaces, or getting database information.

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

If using a non-Astra backend, the environment option MUST be set as it is on the DataAPIClient

Example

const admin1 = db.admin();
const admin2 = db.admin({ adminToken: '<stronger-token>' });

const namespaces = await admin1.listNamespaces();
console.log(namespaces);
Copy

Throws

Error - if the database is not an Astra database.

Spawns a new DataAPIDbAdmin instance for this database, used for performing administrative operations on the database, such as managing namespaces, or getting database information.

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

If using a non-Astra backend, the environment option MUST be set as it is on the DataAPIClient

Example

const client = new DataAPIClient({ environment: 'dse' });
const db = client.db('*ENDPOINT*', { token });

// OK
const admin1 = db.admin({ environment: 'dse' });

// Will throw "mismatching environments" error
const admin2 = db.admin();

const namespaces = await admin1.listNamespaces();
console.log(namespaces);
Copy

Throws

Error - if the database is not an Astra database.

Establishes a reference to a collection in the database. This method does not perform any I/O.

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

Unlike the MongoDB driver, this method does not create a collection if it doesn't exist.

Use Db.createCollection to create a new collection instead.

Typed as Collection<SomeDoc> by default, but you can specify a schema type to get a typed collection. If left as SomeDoc, the collection will be untyped.

You can also specify a namespace in the options parameter, which will override the default namespace for this database.

Example

interface User {
  name: string,
  age?: number,
}

const users1 = db.collection<User>("users");
users1.insertOne({ name: "John" });

// Untyped collection from different namespace
const users2 = db.collection("users", {
  namespace: "my_namespace"
});
users2.insertOne({ nam3: "John" });
Copy

See

• SomeDoc
• VectorDoc

Establishes references to all the collections in the working/given namespace.

You can specify a namespace in the options parameter, which will override the default namespace for this Db instance.

Example

// Uses db's default namespace
const collections1 = await db.collections();
console.log(collections1); // [Collection<SomeDoc>, Collection<SomeDoc>]

// Overrides db's default namespace
const collections2 = await db.collections({ namespace: 'my_namespace' });
console.log(collections2); // [Collection<SomeDoc>]
Copy

Send a POST request to the Data API for this database with an arbitrary, caller-provided payload.

You can specify a collection to target in the options parameter, thereby allowing you to perform arbitrary collection-level operations as well.

You're also able to specify a namespace in the options parameter, which will override the default namespace for this database.

If no collection is specified, the command will be executed at the database level.

Example

const colls = await db.command({ findCollections: {} });
console.log(colls); // { status: { collections: [] } }

const users = await db.command({ findOne: {} }, { collection: 'users' });
console.log(users); // { data: { document: null } }
Copy

Creates a new collection in the database, and establishes a reference to it.

NB. You are limited in the amount of collections you can create, so be wary when using this command.

This is a blocking command which performs actual I/O unlike Db.collection, which simply creates an unvalidated reference to a collection.

If checkExists: false, creation is idempotent, so if the collection already exists with the same options, this method will not throw an error. If the options mismatch, it will throw a DataAPIResponseError.

Typed as Collection<SomeDoc> by default, but you can specify a schema type to get a typed collection. If left as SomeDoc, the collection will be untyped.

If vector options are not specified, the collection will not support vector search.

You can also specify a namespace in the options parameter, which will override the default namespace for this database.

See CreateCollectionOptions for much more information on the options available.

Example

interface User {
  name: string,
  age?: number,
}

const users = await db.createCollection<User>("users");
users.insertOne({ name: "John" });

// Untyped collection with custom options in a different namespace
const users2 = await db.createCollection("users", {
  namespace: "my_namespace",
  defaultId: {
    type: "objectId",
  },
  checkExists: false,
});
Copy

Throws

CollectionAlreadyExistsError - if the collection already exists and checkExists is true or unset.

See

• SomeDoc
• VectorDoc

Drops a collection from the database, including all the contained documents.

You can also specify a namespace in the options parameter, which will override the default namespace for this database.

Example

// Uses db's default namespace
const success1 = await db.dropCollection("users");
console.log(success1); // true

// Overrides db's default namespace
const success2 = await db.dropCollection("users", {
  namespace: "my_namespace"
});
console.log(success2); // true
Copy

Remarks

Use with caution. Have steel-toe boots on. Don't say I didn't warn you.

Fetches information about the database, such as the database name, region, and other metadata.

NB. Only available for Astra databases.

For the full, complete, information, see AstraDbAdmin.info.

The method issues a request to the DevOps API each time it is invoked, without caching mechanisms; this ensures up-to-date information for usages such as real-time collection validation by the application.

Example

const info = await db.info();
console.log(info.name);
Copy

Throws

Error - if the database is not an Astra database.

Lists the collection names in the database.

If you want to include the collection options in the response, set nameOnly to false, using the other overload.

You can also specify a namespace in the options parameter, which will override the default namespace for this database.

Example

// [{ name: "users" }, { name: "posts" }]
console.log(await db.listCollections({ nameOnly: true }));
Copy

See

CollectionOptions

Lists the collections in the database.

If you want to use only the collection names, set nameOnly to true (or omit it completely), using the other overload.

You can also specify a namespace in the options parameter, which will override the default namespace for this database.

Example

// [{ name: "users" }, { name: "posts", options: { ... } }]
console.log(await db.listCollections());
Copy

See

CollectionOptions

Sets the default working namespace of the Db instance. Does not retroactively update any previous collections spawned from this Db to use the new namespace.

Example

// Spawns a `Db` with default working namespace `my_namespace`
const db = client.db('<endpoint>', { namespace: 'my_namespace' });

// Gets a collection from namespace `my_namespace`
const coll1 = db.collection('my_coll');

// `db` now uses `my_other_namespace` as the default namespace for all operations
db.useNamespace('my_other_namespace');

// Gets a collection from namespace `my_other_namespace`
// `coll1` still uses namespace `my_namespace`
const coll2 = db.collection('my_other_coll');

// Gets `my_coll` from namespace `my_namespace` again
// (The default namespace is still `my_other_namespace`)
const coll3 = db.collection('my_coll', { namespace: 'my_namespace' });
Copy

Example

// If using non-astra, this may be a common idiom:
const client = new DataAPIClient({ environment: 'dse' });
const db = client.db('<endpoint>', { token: '<token>' });

// Will internally call `db.useNamespace('new_namespace')`
await db.admin().createNamespace('new_namespace', {
  updateDbNamespace: true,
});

// Creates collection in namespace `new_namespace` by default now
const coll = db.createCollection('my_coll');
Copy