Connect with the Node.js driver
This guide provides an end-to-end workflow for 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
-
Install a cluster and start HCD
-
Install a current Node.js LTS version
-
Install
npm
package manager (included with Node.js)
HCD APIs use the term keyspace to refer to both namespaces and keyspaces. |
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 authProvider = new cassandra.auth.PlainTextAuthProvider('token', process.env['DB_APPLICATION_TOKEN']);
const client = new cassandra.Client({ cloud, authProvider });
async function run() {
await client.connect();
// ...
}
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 = 'cycling';
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: 'ChatGPT 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);
The Node.js driver is now connected to your database, a set of vector embeddings has been loaded, and a similarity search to find vectors that are close to the one in your query has been performed.
Troubleshoot the Node.js driver
The following common issues can occur when using the Node.js driver:
-
Connection timeout: Ensure your database host and port are correct
-
Authentication failed: Verify your client ID and client secret
-
Keyspace not found: Make sure the keyspace exists and you have access to it
-
Package installation errors: Check Node.js and npm versions