Node.js driver quickstart

This driver doesn’t support the vector data type.

DataStax recommends CQL drivers only for Serverless (Non-Vector) databases, existing applications that previously used a CQL-based driver, or if you plan to exclusively use CQL.

It is possible to use CQL drivers for non-vector data in Serverless (Vector) databases. However, DataStax recommends the Data API and clients for Serverless (Vector) databases.

To determine the option that best suits your use case, see Compare connection methods.

This quickstart explains how to use the Node.js driver to connect to your database, load a set of vector embeddings, and perform a similarity search to find vectors that are close to the one in your query.

Prerequisites

An active Astra account
An active Serverless (Non-Vector) database
A Secure Connect Bundle (SCB)
An application token
A current Node.js LTS version with npm

Install the `cassandra-driver` package

Install the cassandra-driver package using npm to connect your Node.js application to your database:

npm install cassandra-driver

Import libraries and connect to the database

Import the necessary libraries and establish a connection to your database.

const cassandra = require('cassandra-driver');

const cloud = { secureConnectBundle: process.env['ASTRA_DB_SECURE_BUNDLE_PATH'] };
const authProvider = new cassandra.auth.PlainTextAuthProvider('token', process.env['ASTRA_DB_APPLICATION_TOKEN']);
const client = new cassandra.Client({ cloud, authProvider });

async function run() {
    await client.connect();

    // ...
}

After you connect to the database, you can use the driver to perform operations on your database.

Create a table and vector-compatible Storage Attached Index (SAI)

Create a table named vector_test in the default_keyspace of your database, with an integer id as the primary key, a text field, and a 5-dimensional float vector. This example code also establishes a custom index on the vector column for efficient similarity searches using the dot product.

// ...

const keyspace = 'default_keyspace';
const v_dimension = 5;

await client.execute(`
  CREATE TABLE IF NOT EXISTS ${keyspace}.vector_test (id INT PRIMARY KEY,
  text TEXT, vector VECTOR<FLOAT,${v_dimension}>);
`);

await client.execute(`
    CREATE CUSTOM INDEX IF NOT EXISTS idx_vector_test
    ON ${keyspace}.vector_test
        (vector) USING 'StorageAttachedIndex' WITH OPTIONS =
        {'similarity_function' : 'cosine'};
`);

// ...

Load data

Insert a few documents with embeddings into the collection:

// ...

const text_blocks = [
    { id: 1, text: 'Chat bot integrated sneakers that talk to you', vector: [0.1, 0.15, 0.3, 0.12, 0.05] },
    { id: 2, text: 'An AI quilt to help you sleep forever', vector: [0.45, 0.09, 0.01, 0.2, 0.11] },
    { id: 3, text: 'A deep learning display that controls your mood', vector: [0.1, 0.05, 0.08, 0.3, 0.6] },
];

for (let block of text_blocks) {
    const {id, text, vector} = block;
    await client.execute(
        `INSERT INTO ${keyspace}.vector_test (id, text, vector) VALUES (${id}, '${text}', [${vector}])`
    );
}

// ...

Perform a similarity search

Find documents that are close to a specific vector embedding:

// ...

  const ann_query = `
    SELECT id, text, similarity_cosine(vector, [0.15, 0.1, 0.1, 0.35, 0.55]) as sim
    FROM ${keyspace}.vector_test
    ORDER BY vector ANN OF [0.15, 0.1, 0.1, 0.35, 0.55] LIMIT 2
  `;

  const result = await client.execute(ann_query);
  result.rows.forEach(row => {
    console.log(`[${row.id}] "${row.text}" (sim: ${row.sim.toFixed(4)})`);
  });

  await client.shutdown();
}

run().catch(console.error);

Migrate the Node.js driver

If necessary, you can migrate an earlier DataStax Node.js driver to a version that can connect to your Astra DB database.

Complete the prerequisites.
Install the latest Node.js driver package.

In your existing DataStax Node.js driver code, modify the connection code to use the SCB credentials.

In the secureConnectBundle parameter, include the path to the SCB for your Astra DB database (secure-connect-DATABASE_NAME.zip).

const { Client } = require('cassandra-driver');
const client = new Client({
    cloud: { secureConnectBundle: 'SECURE_CONNECT_BUNDLE_PATH/secure-connect-DATABASE_NAME.zip' },
    credentials: { username: 'clientId', password: 'clientSecret' }
  });

Run your Node.js script to connect to your database.