Create a table (TypeScript)

Creates a new table in a keyspace in a database.

After you create a table, index columns that you want to sort or filter. This optimizes your queries and avoids resource intensive, long running allow filtering operations.

You can also modify the table columns later. To add data to your table, insert rows.

Ready to write code? See the examples for this method to get started. If you are new to the Data API, check out the quickstart.

Result

Creates a table with the specified parameters.

Returns a promise that resolves to a <Table<Schema, PKey>> object. You can use this object to work with rows in the table.

Unless you specify the Schema, the table is typed as Table<Record<string, any>>.

Parameters

Use the createTable method, which belongs to the Db class.

Method signature

async createTable<const Def extends CreateTableDefinition>(
  name: string,
  options: {
    definition: CreateTableDefinition,
    ifNotExists?: boolean,
    logging?: DataAPILoggingConfig,
    serdes?: TableSerDesConfig,
    timeoutDefaults?: Partial<TimeoutDescriptor>,
    keyspace?: string,
  }
): Table<InferTableSchema<Def>, InferTablePrimaryKey<Def>>

Parameters:

Name Type Summary

Name	Type	Summary
`name`	`string`	The name of the table. Table names must follow these rules: Can contain letters, numbers, and underscores Cannot exceed 48 characters Must be unique within the keyspace
`options`	`CreateTableOptions`	The options for this operation. See Properties of `options` for more details.

name

string

The name of the table.

Table names must follow these rules:

Can contain letters, numbers, and underscores
Cannot exceed 48 characters
Must be unique within the keyspace

options

CreateTableOptions

The options for this operation. See Properties of options for more details.

Properties of `options`
Name	Type	Summary
`definition`	`CreateTableDefinition`	The full schema for the table, including column names, column data types, and the primary key. See the examples for usage. All column names used in the schema must be unique within the table.
`ifNotExists`	`boolean`	Optional. Whether the command should silently succeed even if a table with the given name already exists in the keyspace and no new table was created. This option only checks table names. It does not check table schemas. Default: false
`keyspace`	`string`	Optional if you specified a working keyspace when you created the `Db` object. The keyspace in which to create the table. Default: The working keyspace set when you created the `Db` object, if one was provided.
`logging`	`DataAPILoggingConfig`	Optional. The configuration for logging events emitted by the `DataAPIClient`. For more information, see Logging.
`timeoutDefaults`	`Partial<TimeoutDescriptor>`	Optional. The default timeout options for any operation performed on this `Table` instance. For more information, see TypeScript client internals: TimeoutDescriptor.
`serdes`	`TableSerDesConfig`	Optional. Lower-level serialization/deserialization configuration for this table. For more information, see Custom Ser/Des.

Examples

The following examples demonstrate how to create a table.

Create a table with a single-column primary key

A single-column primary key is a primary key consisting of one column. For more information, see Primary keys in tables (TypeScript).

The TypeScript client supports multiple ways to create a table. The method you choose depends on your typing preferences and whether you modified the ser/des configuration.

For more information, see Collection and table typing.

Automatic type inference
Manually typed tables
Untyped tables

The TypeScript client can automatically infer the TypeScript-equivalent type of the table’s schema and primary key.

To do this, first create the table definition. Then, use InferTableSchema and InferTablePrimaryKey to infer the type of the table and of the primary key. To create the table, provide the table definition and the inferred types to the createTable method.

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

// Get an existing database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
  keyspace: "KEYSPACE_NAME",
});

const tableDefinition = Table.schema({
  // Define all of the columns in the table
  columns: {
    title: "text",
    number_of_pages: "int",
    rating: "float",
    genres: { type: "set", valueType: "text" },
    metadata: {
      type: "map",
      keyType: "text",
      valueType: "text",
    },
    is_checked_out: "boolean",
    due_date: "date",
  },
  // Define the primary key for the table.
  // In this case, the table uses a single-column primary key.
  primaryKey: {
    partitionBy: ["title"],
  },
});

// Infer the TypeScript-equivalent type of the table's schema and primary key
type TableSchema = InferTableSchema<typeof tableDefinition>;
type TablePrimaryKey = InferTablePrimaryKey<typeof tableDefinition>;

(async function () {
  // Provide the types and the definition
  const table = await database.createTable<TableSchema, TablePrimaryKey>(
    "example_table",
    { definition: tableDefinition, keyspace: "KEYSPACE_NAME" },
  );
})();

You can use the TableSchema type as you would any other type. For example, this gives a type error since the TableSchema type from the previous example does not include bad_field:

  const row: TableSchema = {
    title: "Wind with No Name",
    number_of_pages: 193,
    bad_field: "I will error",
  };

You can manually define the type for your table’s schema and primary key. To create the table, provide the table definition and the types to the createTable method.

This may be necessary if you modify the table’s default ser/des configuration.

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

// Get an existing database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
  keyspace: "KEYSPACE_NAME",
});

const tableDefinition = Table.schema({
  // Define all of the columns in the table
  columns: {
    title: "text",
    number_of_pages: "int",
    rating: "float",
    genres: { type: "set", valueType: "text" },
    metadata: {
      type: "map",
      keyType: "text",
      valueType: "text",
    },
    is_checked_out: "boolean",
    due_date: "date",
  },
  // Define the primary key for the table.
  // In this case, the table uses a single-column primary key.
  primaryKey: {
    partitionBy: ["title"],
  },
});

// Manually define the type of the table's schema and primary key
type TableSchema = {
  title: string;
  number_of_pages?: number | null | undefined;
  rating?: number | null | undefined;
  genres?: Set<string> | undefined;
  metadata?: Map<string, string> | undefined;
  is_checked_out?: boolean | null | undefined;
  due_date?: DataAPIDate | null | undefined;
};

type TablePrimaryKey = Pick<TableSchema, "title">;

(async function () {
  // Provide the types and the definition to create the table
  const table = await database.createTable<TableSchema, TablePrimaryKey>(
    "example_table",
    { definition: tableDefinition, keyspace: "KEYSPACE_NAME" },
  );
})();

You can use the TableSchema type as you would any other type. For example, this gives a type error since the TableSchema type from the previous example does not include bad_field:

  const row: TableSchema = {
    title: "Wind with No Name",
    number_of_pages: 193,
    bad_field: "I will error",
  };

To create a table without any typing, pass SomeRow as the single generic type parameter to the createTable method. This types the table’s rows as Record<string, any>.

This is the most flexible but least type-safe option.

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

// Get an existing database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
  keyspace: "KEYSPACE_NAME",
});

const tableDefinition = Table.schema({
  // Define all of the columns in the table
  columns: {
    title: "text",
    number_of_pages: "int",
    rating: "float",
    genres: { type: "set", valueType: "text" },
    metadata: {
      type: "map",
      keyType: "text",
      valueType: "text",
    },
    is_checked_out: "boolean",
    due_date: "date",
  },
  // Define the primary key for the table.
  // In this case, the table uses a single-column primary key.
  primaryKey: {
    partitionBy: ["title"],
  },
});

(async function () {
  // Provide the types and the definition to create the table
  const table = await database.createTable<SomeRow>("example_table", {
    definition: tableDefinition,
  });
})();

Create a table with a composite primary key

A composite primary key is a primary key consisting of multiple columns. For more information, see Primary keys in tables (TypeScript).

The TypeScript client supports multiple ways to create a table. The method you choose depends on your typing preferences and whether you modified the ser/des configuration.

For more information, see Collection and table typing.

Automatic type inference
Manually typed tables
Untyped tables

The TypeScript client can automatically infer the TypeScript-equivalent type of the table’s schema and primary key.

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

// Get an existing database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
  keyspace: "KEYSPACE_NAME",
});

const tableDefinition = Table.schema({
  // Define all of the columns in the table
  columns: {
    title: "text",
    number_of_pages: "int",
    rating: "float",
    genres: { type: "set", valueType: "text" },
    metadata: {
      type: "map",
      keyType: "text",
      valueType: "text",
    },
    is_checked_out: "boolean",
    due_date: "date",
  },
  // Define the primary key for the table.
  // In this case, the table uses a composite primary key.
  primaryKey: {
    partitionBy: ["title", "rating"],
  },
});

// Infer the TypeScript-equivalent type of the table's schema and primary key
type TableSchema = InferTableSchema<typeof tableDefinition>;
type TablePrimaryKey = InferTablePrimaryKey<typeof tableDefinition>;

(async function () {
  // Provide the types and the definition
  const table = await database.createTable<TableSchema, TablePrimaryKey>(
    "example_table",
    { definition: tableDefinition, keyspace: "KEYSPACE_NAME" },
  );
})();

You can use the TableSchema type as you would any other type. For example, this gives a type error since the TableSchema type from the previous example does not include bad_field:

  const row: TableSchema = {
    title: "Wind with No Name",
    number_of_pages: 193,
    bad_field: "I will error",
  };

You can manually define the type for your table’s schema and primary key. To create the table, provide the table definition and the types to the createTable method.

This may be necessary if you modify the table’s default ser/des configuration.

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

// Get an existing database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
  keyspace: "KEYSPACE_NAME",
});

const tableDefinition = Table.schema({
  // Define all of the columns in the table
  columns: {
    title: "text",
    number_of_pages: "int",
    rating: "float",
    genres: { type: "set", valueType: "text" },
    metadata: {
      type: "map",
      keyType: "text",
      valueType: "text",
    },
    is_checked_out: "boolean",
    due_date: "date",
  },
  // Define the primary key for the table.
  // In this case, the table uses a composite primary key.
  primaryKey: {
    partitionBy: ["title", "rating"],
  },
});

// Manually define the type of the table's schema and primary key
type TableSchema = {
  title: string;
  number_of_pages?: number | null | undefined;
  rating?: number | null | undefined;
  genres?: Set<string> | undefined;
  metadata?: Map<string, string> | undefined;
  is_checked_out?: boolean | null | undefined;
  due_date?: DataAPIDate | null | undefined;
};

type TablePrimaryKey = Pick<TableSchema, "title" | "rating">;

(async function () {
  // Provide the types and the definition to create the table
  const table = await database.createTable<TableSchema, TablePrimaryKey>(
    "example_table",
    { definition: tableDefinition, keyspace: "KEYSPACE_NAME" },
  );
})();

You can use the TableSchema type as you would any other type. For example, this gives a type error since the TableSchema type from the previous example does not include bad_field:

  const row: TableSchema = {
    title: "Wind with No Name",
    number_of_pages: 193,
    bad_field: "I will error",
  };

To create a table without any typing, pass SomeRow as the single generic type parameter to the createTable method. This types the table’s rows as Record<string, any>.

This is the most flexible but least type-safe option.

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

// Get an existing database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
  keyspace: "KEYSPACE_NAME",
});

const tableDefinition = Table.schema({
  // Define all of the columns in the table
  columns: {
    title: "text",
    number_of_pages: "int",
    rating: "float",
    genres: { type: "set", valueType: "text" },
    metadata: {
      type: "map",
      keyType: "text",
      valueType: "text",
    },
    is_checked_out: "boolean",
    due_date: "date",
  },
  // Define the primary key for the table.
  // In this case, the table uses a composite primary key.
  primaryKey: {
    partitionBy: ["title", "rating"],
  },
});

(async function () {
  // Provide the types and the definition to create the table
  const table = await database.createTable<SomeRow>("example_table", {
    definition: tableDefinition,
  });
})();

Create a table with a compound primary key

A compound primary key is a primary key consisting of partition (grouping) columns and clustering (sorting) columns. For more information, see Primary keys in tables (TypeScript).

The TypeScript client supports multiple ways to create a table. The method you choose depends on your typing preferences and whether you modified the ser/des configuration.

For more information, see Collection and table typing.

Automatic type inference
Manually typed tables
Untyped tables

The TypeScript client can automatically infer the TypeScript-equivalent type of the table’s schema and primary key.

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

// Get an existing database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
  keyspace: "KEYSPACE_NAME",
});

const tableDefinition = Table.schema({
  // Define all of the columns in the table
  columns: {
    title: "text",
    number_of_pages: "int",
    rating: "float",
    genres: { type: "set", valueType: "text" },
    metadata: {
      type: "map",
      keyType: "text",
      valueType: "text",
    },
    is_checked_out: "boolean",
    due_date: "date",
  },
  // Define the primary key for the table.
  // In this case, the table uses a compound primary key.
  primaryKey: {
    partitionBy: ["title", "rating"],
    partitionSort: { number_of_pages: 1, is_checked_out: -1 },
  },
});

// Infer the TypeScript-equivalent type of the table's schema and primary key
type TableSchema = InferTableSchema<typeof tableDefinition>;
type TablePrimaryKey = InferTablePrimaryKey<typeof tableDefinition>;

(async function () {
  // Provide the types and the definition
  const table = await database.createTable<TableSchema, TablePrimaryKey>(
    "example_table",
    { definition: tableDefinition, keyspace: "KEYSPACE_NAME" },
  );
})();

You can use the TableSchema type as you would any other type. For example, this gives a type error since the TableSchema type from the previous example does not include bad_field:

  const row: TableSchema = {
    title: "Wind with No Name",
    number_of_pages: 193,
    bad_field: "I will error",
  };

You can manually define the type for your table’s schema and primary key. To create the table, provide the table definition and the types to the createTable method.

This may be necessary if you modify the table’s default ser/des configuration.

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

// Get an existing database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
  keyspace: "KEYSPACE_NAME",
});

const tableDefinition = Table.schema({
  // Define all of the columns in the table
  columns: {
    title: "text",
    number_of_pages: "int",
    rating: "float",
    genres: { type: "set", valueType: "text" },
    metadata: {
      type: "map",
      keyType: "text",
      valueType: "text",
    },
    is_checked_out: "boolean",
    due_date: "date",
  },
  // Define the primary key for the table.
  // In this case, the table uses a compound primary key.
  primaryKey: {
    partitionBy: ["title", "rating"],
    partitionSort: { number_of_pages: 1, is_checked_out: -1 },
  },
});

// Manually define the type of the table's schema and primary key
type TableSchema = {
  title: string;
  number_of_pages?: number | null | undefined;
  rating?: number | null | undefined;
  genres?: Set<string> | undefined;
  metadata?: Map<string, string> | undefined;
  is_checked_out?: boolean | null | undefined;
  due_date?: DataAPIDate | null | undefined;
};

type TablePrimaryKey = Pick<TableSchema, "title" | "rating">;

(async function () {
  // Provide the types and the definition to create the table
  const table = await database.createTable<TableSchema, TablePrimaryKey>(
    "example_table",
    { definition: tableDefinition, keyspace: "KEYSPACE_NAME" },
  );
})();

You can use the TableSchema type as you would any other type. For example, this gives a type error since the TableSchema type from the previous example does not include bad_field:

  const row: TableSchema = {
    title: "Wind with No Name",
    number_of_pages: 193,
    bad_field: "I will error",
  };

To create a table without any typing, pass SomeRow as the single generic type parameter to the createTable method. This types the table’s rows as Record<string, any>.

This is the most flexible but least type-safe option.

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

// Get an existing database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
  keyspace: "KEYSPACE_NAME",
});

const tableDefinition = Table.schema({
  // Define all of the columns in the table
  columns: {
    title: "text",
    number_of_pages: "int",
    rating: "float",
    genres: { type: "set", valueType: "text" },
    metadata: {
      type: "map",
      keyType: "text",
      valueType: "text",
    },
    is_checked_out: "boolean",
    due_date: "date",
  },
  // Define the primary key for the table.
  // In this case, the table uses a compound primary key.
  primaryKey: {
    partitionBy: ["title", "rating"],
    partitionSort: { number_of_pages: 1, is_checked_out: -1 },
  },
});

(async function () {
  // Provide the types and the definition to create the table
  const table = await database.createTable<SomeRow>("example_table", {
    definition: tableDefinition,
  });
})();

Create a table with a column to store vector embeddings

If you want to store pre-generated vector embeddings in a table, create a table with a vector column. A table can include more than one vector column.

The TypeScript client supports multiple ways to create a table. The method you choose depends on your typing preferences and whether you modified the ser/des configuration.

For more information, see Collection and table typing.

Automatic type inference
Manually typed tables
Untyped tables

The TypeScript client can automatically infer the TypeScript-equivalent type of the table’s schema and primary key.

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

// Get an existing database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
  keyspace: "KEYSPACE_NAME",
});

const tableDefinition = Table.schema({
  // Define all of the columns in the table
  columns: {
    example_vector: { type: "vector", dimension: 1024 },
    example_non_vector: "text",
  },
  // Define the primary key for the table.
  // In this case, the table uses a single-column primary key.
  primaryKey: {
    partitionBy: ["example_non_vector"],
  },
});

// Infer the TypeScript-equivalent type of the table's schema and primary key
type TableSchema = InferTableSchema<typeof tableDefinition>;
type TablePrimaryKey = InferTablePrimaryKey<typeof tableDefinition>;

(async function () {
  // Provide the types and the definition
  const table = await database.createTable<TableSchema, TablePrimaryKey>(
    "example_table",
    { definition: tableDefinition, keyspace: "KEYSPACE_NAME" },
  );
})();

You can manually define the type for your table’s schema and primary key. To create the table, provide the table definition and the types to the createTable method.

This may be necessary if you modify the table’s default ser/des configuration.

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

// Get an existing database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
  keyspace: "KEYSPACE_NAME",
});

const tableDefinition = Table.schema({
  // Define all of the columns in the table
  columns: {
    example_vector: { type: "vector", dimension: 1024 },
    example_non_vector: "text",
  },
  // Define the primary key for the table.
  // In this case, the table uses a single-column primary key.
  primaryKey: {
    partitionBy: ["example_non_vector"],
  },
});

// Manually define the type of the table's schema and primary key
type TableSchema = {
  example_vector: DataAPIVector;
  example_non_vector: string;
};

type TablePrimaryKey = Pick<TableSchema, "example_non_vector">;

(async function () {
  // Provide the types and the definition to create the table
  const table = await database.createTable<TableSchema, TablePrimaryKey>(
    "example_table",
    { definition: tableDefinition, keyspace: "KEYSPACE_NAME" },
  );
})();

To create a table without any typing, pass SomeRow as the single generic type parameter to the createTable method. This types the table’s rows as Record<string, any>.

This is the most flexible but least type-safe option.

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

// Get an existing database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
  keyspace: "KEYSPACE_NAME",
});

const tableDefinition = Table.schema({
  // Define all of the columns in the table
  columns: {
    example_vector: { type: "vector", dimension: 1024 },
    example_non_vector: "text",
  },
  // Define the primary key for the table.
  // In this case, the table uses a single-column primary key.
  primaryKey: {
    partitionBy: ["example_non_vector"],
  },
});

(async function () {
  // Provide the types and the definition to create the table
  const table = await database.createTable<SomeRow>("example_table", {
    definition: tableDefinition,
  });
})();

Create a table that uses a user-defined type (UDT)

In addition to the supported types, you can create a user-defined type to use in your table.

You can use a user-defined type as the type of a column or as the value type of a map, list, or set column. You can’t use a user-defined type as the key type of a map column or as a partitionKey or clustering key.

The following examples demonstrate how to use a user-defined type called person for the group_leader column, value type in the group_members set column, and value type in the group_roles map column.

The TypeScript client supports multiple ways to create a table. The method you choose depends on your typing preferences and whether you modified the ser/des configuration.

For more information, see Collection and table typing.

Automatic type inference
Manually typed tables
Untyped tables

The TypeScript client can automatically infer the TypeScript-equivalent type of the table’s schema and primary key.

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

// Get an existing database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
  keyspace: "KEYSPACE_NAME",
});

const tableDefinition = Table.schema({
  // Define all of the columns in the table
  columns: {
    id: "uuid",
    group_leader: {
      type: "userDefined",
      udtName: "person",
    },
    group_members: {
      type: "set",
      valueType: {
        type: "userDefined",
        udtName: "person",
      },
    },
    group_roles: {
      type: "map",
      keyType: "text",
      valueType: {
        type: "userDefined",
        udtName: "person",
      },
    },
  },
  // Define the primary key for the table.
  primaryKey: {
    partitionBy: ["id"],
  },
});

// Infer the TypeScript-equivalent type of the table's schema and primary key
type TableSchema = InferTableSchema<typeof tableDefinition>;
type TablePrimaryKey = InferTablePrimaryKey<typeof tableDefinition>;

(async function () {
  // Provide the types and the definition
  const table = await database.createTable<TableSchema, TablePrimaryKey>(
    "example_table",
    { definition: tableDefinition, keyspace: "KEYSPACE_NAME" },
  );
})();

You can manually define the type for your table’s schema and primary key. To create the table, provide the table definition and the types to the createTable method.

This may be necessary if you modify the table’s default ser/des configuration.

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

// Get an existing database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
  keyspace: "KEYSPACE_NAME",
});

const tableDefinition = Table.schema({
  // Define all of the columns in the table
  columns: {
    id: "uuid",
    group_leader: {
      type: "userDefined",
      udtName: "person",
    },
    group_members: {
      type: "set",
      valueType: {
        type: "userDefined",
        udtName: "person",
      },
    },
    group_roles: {
      type: "map",
      keyType: "text",
      valueType: {
        type: "userDefined",
        udtName: "person",
      },
    },
  },
  // Define the primary key for the table.
  primaryKey: {
    partitionBy: ["id"],
  },
});

// Manually define the type of the table's schema and primary key
type Person = { name: string; level: number };
type TableSchema = {
  id: UUID;
  group_leader: Person;
  group_members: Set<Person>;
  group_roles: Map<string, Person>;
};
type TablePrimaryKey = Pick<TableSchema, "id">;

(async function () {
  // Provide the types and the definition to create the table
  const table = await database.createTable<TableSchema, TablePrimaryKey>(
    "example_table",
    { definition: tableDefinition, keyspace: "KEYSPACE_NAME" },
  );
})();

To create a table without any typing, pass SomeRow as the single generic type parameter to the createTable method. This types the table’s rows as Record<string, any>.

This is the most flexible but least type-safe option.

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

// Get an existing database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
  keyspace: "KEYSPACE_NAME",
});

const tableDefinition = Table.schema({
  // Define all of the columns in the table
  columns: {
    id: "uuid",
    group_leader: {
      type: "userDefined",
      udtName: "person",
    },
    group_members: {
      type: "set",
      valueType: {
        type: "userDefined",
        udtName: "person",
      },
    },
    group_roles: {
      type: "map",
      keyType: "text",
      valueType: {
        type: "userDefined",
        udtName: "person",
      },
    },
  },
  // Define the primary key for the table.
  primaryKey: {
    partitionBy: ["id"],
  },
});

(async function () {
  // Provide the types and the definition to create the table
  const table = await database.createTable<SomeRow>("example_table", {
    definition: tableDefinition,
  });
})();

Client reference

For more information, see the client reference.

Create a table (TypeScript)

Result

Parameters

Examples

Create a table with a single-column primary key

Create a table with a composite primary key

Create a table with a compound primary key

Create a table with a column to store vector embeddings

Create a table that uses a user-defined type (UDT)

Client reference

Was this helpful?

Give Feedback