TypeScript client reference
The DataStax Astra DB Serverless (Vector) documentation site is currently in Public Preview and is provided on an “AS IS” basis, without warranty or indemnity of any kind. For more, see the DataStax Preview Terms. |
Use TypeScript to interact with collections and documents in vector-enabled Astra DB databases.
Prerequisites
Before you develop a TypeScript client, ensure you’ve met the prerequisites. You will need:
-
Node.js v16.20.2 or higher. Download and install Node.js.
-
An Astra DB account and an active vector-enabled database created in Astra Portal.
-
An Astra DB application token associated with a Database Administrator role that you create in Astra Portal.
Initialize and install
Perform the following steps to install the astra-db-ts
client and the tsx
package.
-
Verify that Node is version 14 or higher.
node --version
-
Install the tsx package globally
npm install -g tsx
-
Install the
astra-db-ts
packagenpm install @datastax/astra-db-ts@latest
Create a vector-enabled Astra DB database
To create a vector-enabled Astra DB database:
-
Sign into your Astra Portal account.
-
Follow the New Experience prompts to create a vector database.
In Astra Portal, take note of the values for your vector database: ASTRA_DB_REGION
and ASTRA_DB_ID
, plus the generated ASTRA_DB_APPLICATION_TOKEN
.
When you generate the application token in Astra Portal, associate the Database Administrator role with the token. |
Environment variables
The TypeScript code will reference environment variables. You can use a package like dotenv
to load environment variables from a .env
file, or set them manually in your terminal.
-
To set the values as environment variables, export them. Examples:
-
Linux or macOS
-
Windows
-
Google Colab
export ASTRA_DB_APPLICATION_TOKEN="AstraCS:..." export ASTRA_DB_API_ENDPOINT="<Astra DB API endpoint>"
set ASTRA_DB_APPLICATION_TOKEN=AstraCS:... set ASTRA_DB_API_ENDPOINT=<Astra DB API endpoint>
import os os.environ["ASTRA_DB_APPLICATION_TOKEN"] = "AstraCS:..." os.environ["ASTRA_DB_API_ENDPOINT"] = "<Astra DB API endpoint>"
-
Set up your TypeScript client for similarity searches
Add the following code in your TypeScript source file. In this example, we’ll use the filename index.ts
.
-
Import the
astra-db-ts
library and initialize the client.client.tsimport { AstraDB } from "@datastax/astra-db-ts"; async function main() { const { ASTRA_DB_APPLICATION_TOKEN, ASTRA_DB_API_ENDPOINT } = process.env; const db = new AstraDB(ASTRA_DB_APPLICATION_TOKEN, ASTRA_DB_API_ENDPOINT); // Create a collection await db.createCollection( "vector_test", { "vector": { "dimension": 5, "metric": "cosine" } } ); const col = await db.collection("vector_test"); // ...
-
Use the API clauses that will load data into your vector database:
client.ts// ... const documents = [ { "_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], } ]; const results = await col.insertMany(documents); // ...
-
Add code that will perform a similarity search. Use the API to find documents that are most similar to the specified vector, based on a similarity metric. This metric produces a similarity score (such as 0.99444735), which shows how close each document is to that vector.
client.ts// ... interface Document { _id: string; text: string; $vector: number[]; } const options = { sort: { "$vector": [0.15, 0.1, 0.1, 0.35, 0.55], }, limit: 5 }; const document_list = await col.find({}, options).toArray(); document_list.forEach((doc: Document) => console.log(doc)); } main().catch(console.error);
A similarity score returned from a vector-enabled Astra DB database can range from 0 to 1. For example:
-
A value of 0 indicates that the vectors are diametrically opposed.
-
A value of 0.5 suggests the vectors are orthogonal (or perpendicular) and have no match.
-
A value of 1 indicates that the vectors are identical in direction.
Run your client
Run the code you defined above:
tsx client.ts