Node.js Document Collection Client

Connect your app to {astra_db} using the Document API in node.js.

The {astra_db} Collection Node.js Client connects to the {astra_db} Document API.

Set up your environment

  1. Install the {astra_db} JS Collection:

npm install @astrajs/collections
  1. Open a browser, navigate to {astra_generic}, and log in.

  2. From your Dashboard page, select your database.

  3. Copy the Cluster ID of your database.

You can also find the Cluster ID in the URL, which is the last UUID in the path:{org-Id}/database/{databaseid}

  1. Add the Cluster ID as an environment variable with the following command:

export ASTRA_DB_ID={databaseid}


export ASTRA_DB_ID=b5285f63-8da5-4c6e-afd8-ade371a48795
  1. Copy the Region of your database, the region where your database is located.

  2. Add the Region as an environment variable with the following command:

export ASTRA_DB_REGION={region}


export ASTRA_DB_REGION=us-east1
  1. Add your username and your password as environment variables with the following command:

  1. Use printenv to ensure the environment variables were exported.

Use Client with Nodejs

Document API

const { createClient } = require("@astrajs/collections");

// create an {astra_db} client
const astraClient = await createClient({
    astraDatabaseId: process.env.ASTRA_DB_ID,
    astraDatabaseRegion: process.env.ASTRA_DB_REGION,
    applicationToken: process.env.ASTRA_DB_APPLICATION_TOKEN,

// create a shortcut to the users collection in the app namespace/keyspace
// collections are created automatically
const usersCollection = astraClient.namespace("app").collection("users");

// get a single user by document id
const user = await usersCollection.get("");

// get a subdocument by path
const userBlogComments = await usersCollection.get("");

// search a collection of documents
const users = await usersCollection.find({ name: { $eq: "Cliff" } });

// find a single user
const user = await usersCollection.findOne({ name: { $eq: "dang" } });

// create a new document (a documentId is generated)
const user = await usersCollection.create({
  name: "New Guy",

// create a new user (specifying documentId)
const user = await usersCollection.create("", {
  name: "cliff",

// create a user subdocument
const user = await usersCollection.create("", {
  title: "new blog",

// partially update user
const user = await usersCollection.update("", {
  name: "cliff",

// partially update a user subdocument
const userBlog = await usersCollection.update("", {
  title: "my spot",

// replace a user subdocumet
const userBlog = await usersCollection.replace("", {
  title: "New Blog",

// delete a user
const user = await usersCollection.delete("");

// delete a user subdocument
const userBlog = await usersCollection.delete("");