Insert a row

TableInsertOneResult(
  inserted_id={'match_id': 'match_0', 'round': 1},
  inserted_id_tuple=('match_0', 1),
  raw_results=...
)

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")
database = client.get_database("API_ENDPOINT")

from astrapy.constants import SortMode
from astrapy.info import (
    CreateTableDefinition,
    ColumnType,
)

my_table = database.create_table(
    "games",
    definition=(
        CreateTableDefinition.builder()
        .add_column("match_id", ColumnType.TEXT)
        .add_column("round", ColumnType.TINYINT)
        .add_vector_column("m_vector", dimension=3)
        .add_column("score", ColumnType.INT)
        .add_column("when", ColumnType.TIMESTAMP)
        .add_column("winner", ColumnType.TEXT)
        .add_set_column("fighters", ColumnType.UUID)
        .add_partition_by(["match_id"])
        .add_partition_sort({"round": SortMode.ASCENDING})
        .build()
    ),
)

# a full-row insert using astrapy's datatypes
from astrapy.data_types import (
    DataAPISet,
    DataAPITimestamp,
    DataAPIVector,
)
from astrapy.ids import UUID

insert_result = my_table.insert_one(
    {
        "match_id": "match_0",
        "round": 1,
        "m_vector": DataAPIVector([0.4, -0.6, 0.2]),
        "score": 18,
        "when": DataAPITimestamp.from_string("2024-11-28T11:30:00Z"),
        "winner": "Victor",
        "fighters": DataAPISet([
            UUID("0193539a-2770-8c09-a32a-111111111111"),
        ]),
    },
)
insert_result.inserted_id
# {'match_id': 'match_0', 'round': 1}
insert_result.inserted_id_tuple
# ('match_0', 1)

# a partial-row (which in this case overwrites some of the values)
my_table.insert_one(
    {
        "match_id": "match_0",
        "round": 1,
        "winner": "Victor Vector",
        "fighters": DataAPISet([
            UUID("0193539a-2770-8c09-a32a-111111111111"),
            UUID("0193539a-2880-8875-9f07-222222222222"),
        ]),
    },
)
# TableInsertOneResult(inserted_id={'match_id': 'match_0', 'round': 1} ...

# another insertion demonstrating standard-library datatypes in values
import datetime

my_table.insert_one(
    {
        "match_id": "match_0",
        "round": 2,
        "winner": "Angela",
        "score": 25,
        "when": datetime.datetime(
            2024, 7, 13, 12, 55, 30, 889,
            tzinfo=datetime.timezone.utc,
        ),
        "fighters": {
            UUID("019353cb-8e01-8276-a190-333333333333"),
        },
        "m_vector": [0.4, -0.6, 0.2],
    },
)
# TableInsertOneResult(inserted_id={'match_id': 'match_0', 'round': 2}, ...

{
  insertedId: { matchId: 'match_0', round: 1 },
}

import { CreateTableDefinition, DataAPIClient, InferTablePrimaryKey, InferTableSchema, 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, and then infer the type.
// For information about table typing and definitions, see the documentation for createTable.
const TableDefinition = <const>{
  columns: {
    matchId: 'text'
    round: 'tinyint',
    mVector: { type: 'vector', dimension: 3 },
    score: 'int',
    when: 'timestamp',
    winner: 'text',
    fighters: { type: 'set', valueType: 'uuid' },
  },
  primaryKey: {
    partitionBy: ['matchId'],
    partitionSort: { round: 1 },
  },
} satisfies CreateTableDefinition;

type TableSchema = InferTableSchema<typeof TableDefinition>;
type TablePK = InferTablePrimaryKey<typeof TableDefinition>;

(async function () {
  // Create a table with the given TableSchema type if a 'games' table doesn't already exist
  const table = await db.createTable<TableSchema, TablePK>('games', { definition: TableDefinition, ifNotExists: true });

// Use insertOne and insertMany to insert rows into tables.
// Inserts are also upserts for tables.

// insertOne examples

  // Inserts a single row
  const res = 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([                             // Use native Maps, Sets, and Arrays for maps, sets, and lists.
        uuid('a4e4e5b0-1f3b-4b4d-8e1b-4e6b3f1f3b4d'), // You can nest datatypes in maps, sets, and lists.
        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 this instead of plain arrays to enable vector-specific optimizations

  // Returns primary key of type { id: string, time: DataAPITimestamp }
  const primaryKey = res.insertedId;
  console.log(primaryKey.matchId);

  // Inserts are also upserts in tables.
  // If the winner of round 1 was actually 'Cham P. Yun' instead of 'Victor',
  // you can use insertOne to modify the row identified by its primary key.
  await table.insertOne({
    matchId: 'match_0',
    round: 1,
    score: null,                // Set score to null to clear the previously inserted value
    winner: 'Cham P. Yun',
    mVector: [-0.6, 0.2, -0.7],
    });

  // The upserted row now has the following values:
  // { matchId: 'match_0', round: 1, score: null, when: <timestamp>, winner: 'Cham P. Yun', fighters: <uuid[]>, mVector: [-0.6, 0.2, -0.7] }

// insertMany examples

  // Inserts two rows in an unordered fashion.
  // Primary keys are required.
  // Unspecified columns are set to null.
  await table.insertMany([{
    matchId: 'fight4',
    round: 1,
    winner: 'Victor',
    score: 18,
    when: timestamp('2024-11-28T11:30:00Z'),
    fighters: new Set([
      uuid('0193539a-2770-8c09-a32a-111111111111'),
      uuid('019353e3-00b4-83f9-a127-222222222222'),
    ]),
    mVector: vector([0.4, -0.6, 0.2]),
    },
  // Insert with the primary key and 2 other values.
    {
    matchId: 'challenge6',
    round: 2,
    winner: 'Wynn Uhr',
    },
  ]);

  // Performs two inserts against the same row in an ordered fashion ('ordered: true').
  // Because inserts are also upserts in tables, if an ordered insert modifies the same row multiple times,
  // subsequent inserts overwrite prior inserts if the inserts modify the same columns.
  // In this example, the second insert overwrites the winner and mVector values from the first insert.
  //
  // In unordered inserts, upserts still occur, but the order is not guaranteed and the outcome is unpredictable.
  // However, unordered inserts are parallelized on the client and server.
  // They are generally more performant and recommended for most use cases.
  const res = await table.insertMany([
    {
      matchId: 'match_0',
      round: 1,                                       // All numbers are represented as JS numbers except varint and decimal
      score: 18,
      when: timestamp(),                              // Shorthand for new DataAPITimestamp(new Date())
      winner: 'Victor',
      fighters: new Set([                             // Use native Maps, Sets, and Arrays for maps, sets, and lists.
        uuid('a4e4e5b0-1f3b-4b4d-8e1b-4e6b3f1f3b4d'), // You can nest datatypes in maps, sets, and lists.
        uuid(7),                                      // Shorthand for UUID.v7()
      ]),
      mVector: vector([0.2, -0.3, -0.5]),             // Shorthand for new DataAPIVector([0.2, -0.3, -0.5])
    },                                                // Use this instead of plain arrays to enable vector-specific optimizations
    {
      matchId: 'match_0',
      round: 1,
      score: null,                                   // Set score to null to insert no value or clear a previously-inserted value
      winner: 'Cham P. Yun',
      mVector: [-0.6, 0.2, -0.7],
    }],
    {
      timeout: 60000,
      ordered: true,
    });

  // Returns primary key of type { matchId: string, round: number }[]
  // Because both inserts have the same matchId, the primary key is 'match_0' for both
  const primaryKey = res.insertedIds;
  console.log(primaryKey[0].matchId, primaryKey[1].matchId);

  // After both inserts, the row has the following values:
  // { matchId: 'match_0', round: 1, score: null, when: <timestamp>, winner: 'Cham P. Yun', fighters: <uuid[]>, mVector: [-0.6, 0.2, -0.7] }

  const docs: TableSchema[] = Array.from({ length: 101 }, (_, i) => ({
    matchId: `match_${i}`,
    round: 1,
  }));
  await table.insertMany(docs);

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

{
  "status": {
    "primaryKeySchema": {
      "email": {
        "type": "ascii"
      }
    },
    "insertedIds": [
      [
        "tal@example.com"
      ]
    ]
  }
}

{
  "status": {
    "primaryKeySchema": {
      "email": {
        "type": "ascii"
      },
      "graduation_year": {
        "type": "int"
      }
    },
    "insertedIds": [
      [
        "tal@example.com",
        2014
      ]
    ]
  }
}