Get a table

import { CreateTableDefinition, DataAPIClient, InferTableSchema, SomeRow, timestamp, uuid, vector } from '@datastax/astra-db-ts';

// Instantiate the client and connect to the database
const client = new DataAPIClient();
const db = client.db(process.env.CLIENT_DB_URL!, { token: process.env.CLIENT_DB_TOKEN! });

// Create table schema using bespoke Data API table definition syntax
const TableDefinition = <const>{                  // <const> ensures the exact literal type of the object is used, not a widened type
  columns: {
    matchId: 'text',                              // Represented by a native JS string
    round: 'tinyint',                             // All non-varint/decimal numbers are represented as JS numbers
    mVector: { type: 'vector', dimension: 3 },    // Vectors are represented as DataAPIVectors by default to enable some optimizations
    score: 'int',
    when: 'timestamp',                            // Represented by DataAPITimestamps instead of Dates
    winner: 'text',
    fighters: { type: 'set', valueType: 'uuid' }, // Sets/maps/lists are represented as native JS Sets/Maps/Arrays
  },                                              // But the UUID is represented as a provided UUID class.
  primaryKey: {
    partitionBy: ['matchId'],                     // 'matchId' is the sole partition key
    partitionSort: { round: 1 },                  // 'round' is the sole clustering key
  },
} satisfies CreateTableDefinition;                // Ensures the table definition is valid

// Infer the TS-equivalent type from the table definition. Equivalent to:
//
// interface TableSchema {
//   matchId: string,                // Primary key components are not nullable
//   round: number,
//   score?: number | null,          // Non-primary key columns are optional and can return as null
//   winner?: string | null,
//   when?: DataAPITimestamp | null,
//   fighters?: Set<UUID>,           // Maps, lists, and sets are optional to insert, but returns as empty instead of null
//   mVector?: DataAPIVector | null, // Vectors can be null.
// }
//
// The preceding definition uses some custom types, like DataAPITimestamp, UUID, and DataAPIVector.
// If necessary, you can modify the ser/des logic to use different datatypes instead.
// However, you must provide your own types in that case.
// For more information, see the Typescript client usage documentation.
type TableSchema = InferTableSchema<typeof TableDefinition>;

(async function () {
  // Create a table using the given TableSchema type or error if a 'games' table already exists
  const table = await db.createTable<TableSchema>('games', { definition: TableDefinition });

  // Attempt to create the same table again.
  // This errors because a table with the given name already exists,
  // and it uses the default of 'ifNotExists: false'.
  await db.createTable<TableSchema>('games', { definition: TableDefinition })
    .catch((e => console.error(e.message)));

  // Attempt to create the same table again.
  // Because 'ifNotExists: true', the command does not throw an error
  // if the working keyspace already has an table named 'games'.
  await db.createTable<TableSchema>('games', { definition: TableDefinition, ifNotExists: true });

  // Insert a single row
  await table.insertOne({
    matchId: 'match_0',
    round: 1,                                       // All non-varint/decimal numbers are represented as JS numbers
    score: 18,
    when: timestamp(),                              // Shorthand for new DataAPITimestamp(new Date())
    winner: 'Victor',
    fighters: new Set([                             // Uses native Maps/Sets/Arrays for collections
      uuid('a4e4e5b0-1f3b-4b4d-8e1b-4e6b3f1f3b4d'), // You can nest datatypes in collections
      uuid(4),                                      // Shorthand for UUID.v4()
    ]),
    mVector: vector([0.2, -0.3, -0.5]),             // Shorthand for new DataAPIVector([0.2, -0.3, -0.5])
  });

  // Use createTable to create an untyped reference to the table.
  const untypedTable = await db.createTable<SomeRow>('games', { definition: TableDefinition, ifNotExists: true });

  // Attempt to insert a row into the untyped table.
  // This errors at runtime (not statically) because it's untyped.
  await untypedTable.insertOne({ matchId: '32', round: 1, badfield: 3 })
    .catch((e => console.error(e.message)));

  // The following examples demonstrate various ways to get a reference to a table (a Table object)

  // Create the table if it doesn't already exist, but don't retain the Table object
  await db.createTable('games', { definition: TableDefinition, ifNotExists: true });

  // Create an untyped table object
  const untypedTable = db.table('games');

  // Flexible but not type-safe, errors at runtime
  const inserted1 = await untypedTable.insertOne({ matchId: 'fight7' });

  // Return type of inserted primary key not known either
  console.log(inserted1.insertedId["I don't know who I am..."]);

  // Return types of find operations, not type-safe
  const found1 = await untypedTable.findOne({ matchId: 'fight7', round: 3 });
  console.log(found1?.["I guess you could say that I'm having an IDentity crisis :)"]);

  // Create a typed table object
  const typedTable = db.table<TableSchema, TablePK>('games');

  // @ts-expect-error
  // Type-safe, errors when compiling
  // You must ensure the types are correct
  const inserted2 = await typedTable.insertOne({ matchId: 'fight7' });

  // @ts-expect-error
  // Type-safe, errors when compiling
  console.log(inserted2.insertedId["uh oh I've been caught"]);

  // Still type-safe
  const found2 = await typedTable.findOne({ matchId: 'fight7', round: 3 })
  console.log(found2?.winner);

  // Uncomment the following line to drop the table and any related indexes.
  // await table.drop();
})();