Node.js Collection Client

Connect your app to DataStax 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 DataStax Astra, 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: https://astra.datastax.com/org/{org-Id}/database/{databaseid}

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

export ASTRA_DB_ID={databaseid}

Example:

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}

Example:

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

export ASTRA_DB_APPLICATION_TOKEN={token}
  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("cliff@wicklow.com");

// get a subdocument by path
const userBlogComments = await usersCollection.get("cliff@wicklow.com/blog/comments");

// 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("cliff@wicklow.com", {
  name: "cliff",
});

// create a user subdocument
const user = await usersCollection.create("cliff@wicklow.com/blog", {
  title: "new blog",
});

// partially update user
const user = await usersCollection.update("cliff@wicklow.com", {
  name: "cliff",
});

// partially update a user subdocument
const userBlog = await usersCollection.update("cliff@wicklow.com/blog", {
  title: "my spot",
});

// replace a user subdocumet
const userBlog = await usersCollection.replace("cliff@wicklow.com/blog", {
  title: "New Blog",
});

// delete a user
const user = await usersCollection.delete("cliff@wicklow.com");

// delete a user subdocument
const userBlog = await usersCollection.delete("cliff@wicklow.com/blog");

REST API

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

// create an {astra_db} client
const astraClient = await createClient({
    astraDatabaseId: process.env.ASTRA_DB_ID,
    astraDatabaseRegion: process.env.ASTRA_DB_REGION,
    username: process.env.ASTRA_DB_USERNAME,
    password: process.env.ASTRA_DB_PASSWORD,
});

const basePath = "/api/rest/v2/KEYSPACES/<namespace>/collections/<collectionName>";

// get a single user by document id
const { data, status } = await astraClient.get(`${basePath}/<documentId>`);

// get a subdocument by path
const { data, status } = await astraClient.get(`${basePath}/<documentId>/<subdocument>/<subdocument>`);

// search a collection of documents
const { data, status } = await astraClient.get(basePath, {
  params: {
    where: {
      name: { $eq: "<documentId>" }
    }
  }
});

// create a new user without a document id
const { data, status } = await astraClient.post(basePath, {
  name: "<documentId>",
});

// create a new user with a document id
const { data, status } = await astraClient.put(`${basePath}/<documentId>`, {
  name: "cliff",
});

// create a user subdocument
const { data, status } = await astraClient.put(`${basePath}/<documentId>/<subdocument>`, {
  title: "new blog",
});

// partially update user
const { data, status } = await astraClient.patch(`${basePath}/<documentId>`, {
  name: "cliff",
});

// delete a user
const { data, status } = await astraClient.delete(`${basePath}/<documentId>`);