Hyper-Converged Database (HCD) quickstart for tables (TypeScript)

import {
  DataAPIClient,
  Db,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

/**
 * Connects to your database.
 * This function retrieves the database endpoint, username, and password from the
 * environment variables `API_ENDPOINT`, `USERNAME`, and `PASSWORD`.
 *
 * @returns An instance of the connected database.
 * @throws Will throw an error if the environment variables
 * `API_ENDPOINT`, `USERNAME`, or `PASSWORD` are not defined.
 */
export function connectToDatabase(): Db {
  const {
    API_ENDPOINT: endpoint,
    USERNAME: username,
    PASSWORD: password,
  } = process.env; (1)

  if (!endpoint || !username || !password) {
    throw new Error(
      "Environment variables API_ENDPOINT, USERNAME, and PASSWORD must be defined.",
    );
  }

  // Create an instance of the `DataAPIClient` class
  const client = new DataAPIClient({ environment: "hcd" });

  // Get the database specified by your endpoint and provide the token
  const database = client.db(endpoint, {
    token: new UsernamePasswordTokenProvider(username, password),
  });

  console.log("Connected to database");

  return database;
}

import { connectToDatabase } from "./quickstart-connect"; (1)

(async function () {
  const database = connectToDatabase();

  // Get an admin object
  const admin = database.admin({ environment: "hcd" });

  // Create a keyspace
  await admin.createKeyspace("quickstart_keyspace"); (2)

  console.log("Created keyspace");
})();

import { connectToDatabase } from "./quickstart-connect"; (1)
import {
  Table,
  InferTablePrimaryKey,
  InferTableSchema,
} from "@datastax/astra-db-ts";

const database = connectToDatabase();

const tableDefinition = Table.schema({
  // Define all of the columns in the table
  columns: {
    title: "text",
    author: "text",
    number_of_pages: "int",
    rating: "float",
    publication_year: "int",
    summary: "text",
    genres: { type: "set", valueType: "text" },
    metadata: {
      type: "map",
      keyType: "text",
      valueType: "text",
    },
    is_checked_out: "boolean",
    borrower: "text",
    due_date: "date",
    // This column will store vector embeddings. (2)
    summary_genres_vector: { type: "vector", dimension: 5 },
  },
  // Define the primary key for the table.
  // In this case, the table uses a composite primary key.
  primaryKey: {
    partitionBy: ["title", "author"],
  },
});

// Infer the TypeScript-equivalent type of the table's schema and primary key.
// Export the types for later use.
export type TableSchema = InferTableSchema<typeof tableDefinition>;
export type TablePrimaryKey = InferTablePrimaryKey<typeof tableDefinition>;

(async function () {
  const table = await database.createTable<TableSchema, TablePrimaryKey>(
    "quickstart_table", (3)
    {
      definition: tableDefinition,
      keyspace: "quickstart_keyspace", (4)
    },
  );

  console.log("Created table");

  // Index any columns that you want to sort and filter on.
  await table.createIndex("rating_index", "rating");

  await table.createIndex("number_of_pages_index", "number_of_pages");

  await table.createVectorIndex(
    "summary_genres_vector_index",
    "summary_genres_vector",
    {
      options: {
        metric: "cosine", (5)
      },
    },
  );

  console.log("Indexed columns");
})();

import { connectToDatabase } from "./quickstart-connect"; (1)
import { TableSchema, TablePrimaryKey } from "./quickstart-create-table"; (2)
import { DataAPIDate, DataAPIVector } from "@datastax/astra-db-ts";
import fs from "fs";

(async function () {
  const database = connectToDatabase();

  const table = database.table<TableSchema, TablePrimaryKey>(
    "quickstart_table",
    { keyspace: "quickstart_keyspace" },
  ); (3)

  const dataFilePath = "PATH_TO_DATA_FILE"; (4)

  // Read the JSON file and parse it into a JSON array.
  const rawData = fs.readFileSync(dataFilePath, "utf8");
  const jsonData = JSON.parse(rawData);

  const rows = jsonData.map((data: any) => ({
    ...data,
    genres: new Set(data.genres),
    metadata: new Map(Object.entries(data.metadata)),
    due_date: data.due_date ? new DataAPIDate(data.due_date) : null,
    summary_genres_vector: new DataAPIVector(data["summary_genres_vector"]),
  }));

  const insertedResult = await table.insertMany(rows);

  console.log(`Inserted ${insertedResult.insertedCount} rows.`);
})();

import { connectToDatabase } from "./quickstart-connect"; (1)
import { TableSchema, TablePrimaryKey } from "./quickstart-create-table"; (2)

(async function () {
  const database = connectToDatabase();

  const table = database.table<TableSchema, TablePrimaryKey>(
    "quickstart_table",
    { keyspace: "quickstart_keyspace" },
  ); (3)

  // Find rows that match a filter
  console.log("\nFinding books with rating greater than 4.7...");

  const ratingCursor = table.find(
    { rating: { $gt: 4.7 } },
    {
      limit: 10,
      projection: { title: true, rating: true },
    },
  );

  for await (const row of ratingCursor) {
    console.log(`${row.title} is rated ${row.rating}`);
  }

  // Perform a vector search to find the closest match to a search vector
  console.log("\nUsing vector search to find a book...");

  const singleVectorMatch = await table.findOne(
    {},
    {
      sort: {
        summary_genres_vector: [
          0.016326904, -0.031677246, 0.04815674, 0.0033435822, 0.01876831,
        ],
      },
      projection: { title: true },
    },
  );

  console.log(`${singleVectorMatch?.title} is the best match`);

  // Combine a filter, vector search, and projection to find the 3 books with
  // more than 400 pages that are the closest matches to a search vector
  console.log(
    "\nUsing filters and vector search to find 3 books with more than 400 pages, returning just the title and author...",
  );

  const vectorCursor = table.find(
    { number_of_pages: { $gt: 400 } },
    {
      sort: {
        summary_genres_vector: [
          0.016326904, -0.031677246, 0.04815674, 0.0033435822, 0.01876831,
        ],
      },
      limit: 3,
      projection: { title: true, author: true },
    },
  );

  for await (const row of vectorCursor) {
    console.log(row);
  }
})();