Create a table (TypeScript)

Tables with the Data API are currently in public preview. Development is ongoing, and the features and functionality are subject to change. Hyper-Converged Database (HCD), and the use of such, is subject to the DataStax Preview Terms.

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

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.

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

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

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: {
    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,
  });
})();

Client reference

For more information, see the client reference.

Was this helpful?

Give Feedback

How can we improve the documentation?

© Copyright IBM Corporation 2026 | Privacy policy | Terms of use |  Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: Contact IBM