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.

API reference

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 package

npm 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.ts

import { 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

Support

Was This Helpful?

Need More Help?

Ask the Astra community Get in touch with support