Create a table

This Astra DB Serverless feature is currently in public preview. Development is ongoing, and the features and functionality are subject to change. Astra DB Serverless, and the use of such, is subject to the DataStax Preview Terms.

The Data API tables commands are available through HTTP and the clients.

If you use a client, tables commands are available only in client versions 2.0-preview or later. For more information, see Data API client upgrade guide.

Creates a new table in a keyspace in a Serverless (Vector) database.

Method signature

  • Python

  • TypeScript

  • Java

  • curl

database.create_table(
  name: str,
  *,
  definition: CreateTableDefinition | dict[str, Any],
  row_type: type[Any],
  keyspace: str,
  if_not_exists: bool,
  table_admin_timeout_ms: int,
  request_timeout_ms: int,
  timeout_ms: int,
  embedding_api_key: str | EmbeddingHeadersProvider | UnsetType,
  spawn_api_options: APIOptions | UnsetType,
) -> Table[ROW]
database.createTable<const Def extends CreateTableDefinition>(
  name: string,
  options: {
    definition: CreateTableDefinition,
    ifNotExists: boolean,
    embeddingApiKey?: string | EmbeddingHeadersProvider,
    logging?: DataAPILoggingConfig,
    serdes?: TableSerDesConfig,
    timeoutDefaults?: Partial<TimeoutDescriptor>,
    keyspace?: string,

  }
): Promise<Table<InferTableSchema<Def>, InferTablePrimaryKey<Def>>>
<T> Table<T> createTable(
  String tableName,
  TableDefinition tableDefinition,
  Class<T> rowClass,
  CreateTableOptions createTableOptions
)
<T> Table<T> createTable(
  String tableName,
  TableDefinition tableDefinition,
  Class<T> rowClass
)
<T> Table<T> createTable(Class<T> rowClass)
<T> Table<T> createTable(
  Class<T> rowClass,
  CreateTableOptions createTableOptions
)
<T> Table<T> createTable(
  String tableName,
  Class<T> rowClass,
  CreateTableOptions createTableOptions
)
Table<Row> createTable(
  String tableName,
  TableDefinition tableDefinition,
  CreateTableOptions options
)
Table<Row> createTable(
  String tableName,
  TableDefinition tableDefinition
)
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "createTable": {
    "name": "TABLE_NAME",
    "definition": {
      "columns": {
        "COLUMN_NAME": "DATA_TYPE",
        "COLUMN_NAME": "DATA_TYPE"
      },
      "primaryKey": "COLUMN_NAME"
    }
  }
}'

Result

  • Python

  • TypeScript

  • Java

  • curl

Creates a table with the specified parameters.

Returns a Table object. You can use this object to work with rows in the table.

Unless you specify the row_type parameter, the table is typed as Table[dict].

For more information, see Typing support.

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

Creates a table with the specified parameters.

Returns a Table<T> object. You can use this object to work with rows in the table.

Unless you specify the rowClass parameter, the table is typed as Table<Row>.

Creates a table with the specified parameters.

If the command succeeds, the response indicates the success.

Example response:

{
  "status": {
    "ok": 1
  }
}

Parameters

When you create a table, you specify the following:

  • Table name

  • Column names and data types

  • Primary key, which is the unique identifier for the rows in the table

  • Additional table, command, or client-specific settings, which can be optional

  • Python

  • TypeScript

  • Java

  • curl

Name Type Summary

name

str

The name of the table.

definition

CreateTableDefinition | dict

A complete table definition for the table, including the column names, data types, other column settings, and the primary key.

This can be an instance of CreateTableDefinition or an equivalent nested dictionary, in which case it is parsed into a CreateTableDefinition. For examples of both formats, see the Example for this command.

Some types require specific column definitions, particularly maps, lists, sets, and vector columns. For more information about all types, see Column data types.

row_type

type

This parameter acts a formal specifier for the type checker. If omitted, the resulting Table is implicitly a Table[dict]. If provided, row_type must match the type hint specified in the assignment. For more information, see the Example for this command and Typing support.

keyspace

str | None

The keyspace where the table is to be created. If not specified, the general keyspace setting for the database is used.

if_not_exists

bool | None

If True, the command doesn’t throw an error if a table with the given name already exists. In this case, the command silently does nothing and no actual table creation takes place on the database.

If False (default), an error occurs if a table with the specified name already exists in the database.

if_not_exists: True, does not check the definition of any existing tables. This parameter checks table names only.

This means that the command succeeds if the given table name is already in use, even if the table definition is different.

table_admin_timeout_ms

int | None

A timeout, in milliseconds, to impose on the underlying API request. If not provided, the Table defaults apply. This parameter is aliased as request_timeout_ms and timeout_ms for convenience.

embedding_api_key

str | EmbeddingHeadersProvider

Optional parameter for tables that have a vector column with a vectorize embedding provider integration. For more information, see Define a column to automatically generate vector embeddings.

As an alternative to Astra DB KMS authentication, use embedding_api_key to store one or more embedding provider API keys on the Table instance for vectorize header authentication. The client automatically passes the key as an X-embedding-api-key header (EmbeddingAPIKeyHeaderProvider) with operations that use vectorize.

Most embedding provider integrations accept a plain string for header authentication. However, some vectorize providers and models require specialized subclasses of EmbeddingHeadersProvider for header authentication.

spawn_api_options

APIOptions

A complete or partial specification of the APIOptions to override the defaults inherited from the Database. This allows for nuanced table configuration. For example, if APIOptions is passed together with named timeout parameters, the latter take precedence in their respective settings.

Parameters:

Name Type Summary

name

string

The name of the table.

option?

CreateTableOptions

The options for spawning the Table instance.

Options (CreateTableOptions<Schema>):

Name Type Summary

definition

CreateTableDefinition

A TypeScript object defining the table to create, including the following:

  • columns: An object defining the table’s columns as a series of key-value pairs where each key is a column name and each value is the column’s data type. Column names must be unique within a table.

    The Data API accepts column definitions in two formats:

    "columns": {
  "COLUMN_NAME": "DATA_TYPE",
  "COLUMN_NAME": {
    "type": "DATA_TYPE"
  }
}

    Data types are enums of supported data types, such as 'text', 'int', or 'boolean'.

    For 'map', 'list', and 'set', types, you must use the object format and provide additional options. For more information, see Map, list, and set types.

    For the 'vector' type, you must use the object format and provide information about the stored vectors, such as dimension and service options. For more information, see Vector type.

  • primaryKey: The table’s primary key definition as a single string or an object containing partition keys. For more information, see Primary keys.

ifNotExists

boolean

If true, the command doesn’t throw an error if a table with the given name already exists. In this case, the command silently does nothing and no actual table creation takes place on the database.

If false (default), an error occurs if a table with the specified name already exists in the database.

ifNotExists: true, does not check the schema of any existing tables. This parameter checks table names only.

This means that the command succeeds if the given table name is already in use, even if the schema is different.

keyspace?

string

The keyspace where you want to create the table. If not specified, the working keyspace of the Db is used.

embeddingApiKey?

string | EmbeddingHeadersProvider

Optional parameter for tables that have a vector column with a vectorize embedding provider integration. For more information, see Define a column to automatically generate vector embeddings.

As an alternative to Astra DB KMS authentication, use embeddingApiKey to store an embedding provider API key on the Table instance for vectorize header authentication. The client automatically passes the key as an X-embedding-api-key header with operations that use vectorize.

Most embedding provider integrations accept a plain string for header authentication. However, some vectorize providers and models require specialized subclasses of EmbeddingHeadersProvider for header authentication.

logging?

DataAPILoggingConfig

The configuration for logging events emitted by the DataAPIClient.

timeoutDefaults?

Partial<TimeoutDescriptor>

The default timeout options for any operation performed on this Table instance. For more information, see TimeoutDescriptor.

serdes?

TableSerDesConfig

Lower-level serialization/deserialization configuration for this table. For more information, see Custom Ser/Des.
Name Type Summary

name

String

The name of the table.

definition

TableDefinition

A complete table definition for the table, including the column names, data types, other column settings, and the primary key.

Some types require specific column definitions, particularly maps, lists, sets, and vector columns. For more information about all types, see Column data types.

rowClass

Class<?>

An optional specification of the class of the table’s row object. If not provided, the default is Row, which is close to a Map object.

createTableOptions

CreateTableOptions

Options and additional parameters for the createTable operation, such as ifNotExists, timeout, and embeddingAuthProvider:

  • ifNotExists(): If true, the command doesn’t throw an error if a table with the given name already exists. In this case, the command silently does nothing and no actual table creation takes place on the database.

    If false (default), an error occurs if a table with the specified name already exists in the database.

    ifNotExists(true), does not check the definition of any existing tables. This parameter checks table names only.

    This means that the command succeeds if the given table name is already in use, even if the table definition is different.

  • timeout(): A timeout, in milliseconds, to impose on the underlying API request.

  • embeddingAuthProvider(): Optional parameter for tables that have a vector column with a vectorize embedding provider integration. For more information, see Define a column to automatically generate vector embeddings.

    As an alternative to Astra DB KMS authentication, use embeddingAuthProvider to store an embedding provider API key on the Table instance for vectorize header authentication. The client automatically passes the key as an X-embedding-api-key header with operations that use vectorize.

    Most embedding provider integrations accept a plain string for header authentication. However, some vectorize providers and models require specialized subclasses of EmbeddingHeadersProvider for header authentication.
Name Type Summary

createTable

command

The Data API command to create a table in a Serverless (Vector) database. It acts as a container for all the attributes and settings required to create the table.

name

string

The name of the table. This must be unique within the database specified in the request URL.

definition

object

Contains the columns and primary key definition for the table.

definition.columns

object

Defines the table’s columns as a series of key-value pairs where each key is a column name and each value is the column’s data type. Column names must be unique within a table.

The Data API accepts column definitions in two formats:

"columns": {
  "COLUMN_NAME": "DATA_TYPE",
  "COLUMN_NAME": {
    "type": "DATA_TYPE"
  }
}

Data types are enums of supported data types, such as "text", "int", or "boolean".

For map, list, and set, types, you must use the object format and provide additional options. For more information, see Map, list, and set types.

For the vector type, you must use the object format and provide information about the stored vectors, such as dimension and service options. For more information, see Vector type.

definition.primaryKey

string or object

Defines the primary key for the table. For more information, see Primary keys.

Examples

The following examples demonstrate how to create a table.

  • Python

  • TypeScript

  • Java

  • curl

Create a table using a fluent interface for its definition:

table_definition = (
    CreateTableDefinition.builder()
    .add_column("match_id", ColumnType.TEXT)
    .add_column("round", ColumnType.INT)
    .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()
)
my_table = database.create_table(
    "games",
    definition=table_definition,
)

Use if_not_exists to call create_table without throwing an error if a table with the given name already exists. In which case, the request silently does nothing.

table_definition = ...  # (omitted)
my_table = database.create_table(
    "games",
    definition=table_definition,
    if_not_exists=True,
)

Example:

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

# Create a table using the fluent syntax for definition:
from astrapy.constants import SortMode
from astrapy.info import (
    CreateTableDefinition,
    ColumnType,
)
table_definition = (
    CreateTableDefinition.builder()
    .add_column("match_id", ColumnType.TEXT)
    .add_column("round", ColumnType.INT)
    .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()
)
my_table = database.create_table(
    "games",
    definition=table_definition,
)

# Create a table with the definition as object:
# (and do not raise an error if the table exists already)
from astrapy.info import (
    CreateTableDefinition,
    TablePrimaryKeyDescriptor,
    TableScalarColumnTypeDescriptor,
    TableValuedColumnType,
    TableValuedColumnTypeDescriptor,
    TableVectorColumnTypeDescriptor,
)
table_definition_1 = CreateTableDefinition(
    columns={
        "match_id": TableScalarColumnTypeDescriptor(
            ColumnType.TEXT,
        ),
        "round": TableScalarColumnTypeDescriptor(
            ColumnType.INT,
        ),
        "m_vector": TableVectorColumnTypeDescriptor(
            column_type="vector", dimension=3
        ),
        "score": TableScalarColumnTypeDescriptor(
            ColumnType.INT,
        ),
        "when": TableScalarColumnTypeDescriptor(
            ColumnType.TIMESTAMP,
        ),
        "winner": TableScalarColumnTypeDescriptor(
            ColumnType.TEXT,
        ),
        "fighters": TableValuedColumnTypeDescriptor(
            column_type=TableValuedColumnType.SET,
            value_type=ColumnType.UUID,
        ),
    },
    primary_key=TablePrimaryKeyDescriptor(
        partition_by=["match_id"],
        partition_sort={"round": SortMode.ASCENDING},
    ),
)
my_table_1 = database.create_table(
    "games",
    definition=table_definition_1,
    if_not_exists=True,
)

# Create a table with the definition as plain dictionary:
# (and do not raise an error if the table exists already)
table_definition_2 = {
    "columns": {
        "match_id": {"type": "text"},
        "round": {"type": "int"},
        "m_vector": {"type": "vector", "dimension": 3},
        "score": {"type": "int"},
        "when": {"type": "timestamp"},
        "winner": {"type": "text"},
        "fighters": {"type": "set", "valueType": "uuid"},
    },
    "primaryKey": {
        "partitionBy": ["match_id"],
        "partitionSort": {"round": 1},
    },
}
my_table_2 = database.create_table(
    "games",
    definition=table_definition_2,
    if_not_exists=True,
)

The TypeScript client provides multiple ways to create create tables, depending on your typing preferences and ser/des configuration (if modified). The following strategies and examples focus on typing your tables. For details about other parameters, such as table definitions, see the Parameters and Example for this command.

  • Automatic type inference

  • Manually typed tables

  • Untyped tables

Like Zod or arktype, the Data API TypeScript client can automatically infer the type of the table’s schema.

By default, the client infers TS-equivalent type of the table’s schema from the definition object that you provide. There are several ways to extract this type to reuse within your application.

Infer from definition object

To infer the type from the definition object, you must specify the definition with a <const> assertion so that TypeScript can infer the exact unwidened type of the object.

Additionally, DataStax strongly recommends using satisfies CreateTableDefinition for typechecking purposes.

import { CreateTableDefinition, DataAPIClient, InferTablePrimaryKey, InferTableSchema } from '@datastax/astra-db-ts';

// Instantiate the client and connect to the database
const client = new DataAPIClient();
const db = client.db('ENDPOINT', { token: 'TOKEN' });

// Create table schema using bespoke Data API table definition syntax
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;

// 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>;

// Infer the TS-equivalent type of the primary key from the table definition. Equivalent to:
// type TablePK = Pick<TableSchema, 'matchId' | 'round'>;
type TablePK = InferTablePrimaryKey<typeof TableDefinition>;

// Main function
(async function bootstrap() {
  // Provide the type explicitly, so TypeScript doesn't have to run any additional typechecking, just to get the same result
  const table = await db.createTable<TableSchema, TablePK>('games', { definition: TableDefinition });

  // You can then use TableSchema as you would any other type.
  // @ts-expect-error - 'badfield' is not a valid column as per the table's type
  const row: TableSchema = { matchId: 'match01', round: 1, badfield: 'Shhh!' }

  // res.insertedId :: { matchId: string, round: number }
  const res = await table.insertOne(row);
})();
Infer from created table

For this strategy, you must write the table definition inline or create it with a <const> assertion. For an example of <const>, see Infer from definition object.

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

// Instantiate the client and connect to the database
const client = new DataAPIClient();
const db = client.db('ENDPOINT', { token: 'TOKEN' });

// You must put createTable in its own function with no explicit return type annotation.
// This ensures that the type of the table is available from the top-level scope.
//
// If the environment doesn't allow top-level awaits, then you can't call createTable from the top level
// (without creating an unawaited promise) to then extract the type from.
//
// Therefore, you must extract the type from the function itself, and then the function called.
async function mkGamesTable() {
  return await db.createTable('games', {
    definition: {
      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 },
      },
    }
  });
}

// 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 mkGamesTable>;

// Infer the TS-equivalent type of the primary key from the table definition. Equivalent to:
// type TablePK = Pick<TableSchema, 'matchId' | 'round'>;
type TablePK = InferTablePrimaryKey<typeof mkGamesTable>;

// Main function
(async function bootstrap() {
  // Call the function to actually create the table
  const table = await mkGamesTable();

  // You can then use TableSchema as you would any other type.
  // @ts-expect-error - 'badfield' is not a valid column as per the table's type
  const row: TableSchema = { matchId: 'match01', round: 1, badfield: 'Shhh!' }

  // res.insertedId :: { matchId: string, round: number }
  const res = await table.insertOne(row);
})();
Infer from created table with ES2022 top-level await

For this strategy, you must write the table definition inline or create it with a <const> assertion. For an example of <const>, see Infer from definition object.

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

// Instantiate the client and connect to the database
const client = new DataAPIClient();
const db = client.db('ENDPOINT', { token: 'TOKEN' });

// You can use this if top-level awaits are allowed in your environment
const table = await db.createTable('games', {
  definition: {
    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 },
    },
  }
});

// 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 table>;

// Infer the TS-equivalent type of the primary key from the table definition. Equivalent to:
// type TablePK = Pick<TableSchema, 'matchId' | 'round'>;
type TablePK = InferTablePrimaryKey<typeof table>;

// You can then use `TableSchema` as you would any other type.
// @ts-expect-error - 'badfield' is not a valid column as per the table's type
const row: TableSchema = { matchId: 'match01', round: 1, badfield: 'Shhh!' }

// res.insertedId :: { matchId: string, round: number }
const res = await table.insertOne(row);

With any of these strategies, you can use InferTableSchema and InferTableReadSchema to extract the exact read/write schemas.

For more information, see Collection and Table typing.

You can manually provide your own type for your tables by passing the type as a generic parameter to the createTable method.

Optionally, you can provide your own type for the table’s primary key as a string literal union type of the primary key column names. For more information, see Get a table.

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

The following example passes the manual types MySchema and MyPK to createTable:

interface MySchema {
  matchId: string,
  round: number,
  score: number,
  winner: string,
  when: DataAPITimestamp,
  fighters: Set<UUID>,
  mVector: DataAPIVector,
}

interface MyPK = Pick<MySchema, 'matchId' | 'round'>;

(async function bootstrap() {
  const table = await db.createTable<MySchema, MyPK>('games', {
    definition: {
      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 },
      },
    }
  });

  // Use MySchema as you would any other type
  // @ts-expect-error - 'badfield' is not a valid column as per the table's type
  const row: MySchema = { matchId: 'match01', round: 1, badfield: 'Shhh!' }

  // res.insertedId :: { matchId: string, round: number }
  const res = await table.insertOne(row);
})();

If you need to provide different schemas for reads and writes, see Collection and Table typing.

If you want to create a table without any typing, then you must pass SomeRow as the single generic type parameter. This types the table’s rows as Record<string, any>, which is the most flexible but least type-safe option.

(async function bootstrap() {
  const table = await db.createTable<SomeRow>('games', {
    definition: {
      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 },
      },
    }
  });

  // No typechecking anymore
  await table.insertOne({ matchId: 'match01', round: 1, badfield: 'Shhh!' })

  // res.insertedId :: SomeRow
  const res = await table.insertOne(row);
})();

By default, the client creates the table in the database’s working keyspace. To create a table in a specific keyspace, include keyspace:

const table = await db.createTable<SomeRow>('games', {
  definition: /* omitted for brevity \*/,
  keyspace: 'KEYSPACE_NAME',
});

Example:

Full script 
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();
})();
// 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)));

Create a table in the database’s working keyspace by providing a TableDefinition and specializations through options:

TableDefinition tableDefinition = new TableDefinition()
  .addColumnText("match_id")
  .addColumnInt("round")
  .addColumnVector("m_vector",
    new ColumnDefinitionVector().dimension(3).metric(COSINE))
  .addColumn("score", ColumnTypes.INT)
  .addColumn("when",  ColumnTypes.TIMESTAMP)
  .addColumn("winner",  ColumnTypes.TEXT)
  .addColumnSet("fighters", ColumnTypes.UUID)
  .addPartitionBy("match_id")
  .addPartitionSort(ascending("round"));

// Default Table Creation
Table<Row> tableGames = database
  .createTable("games", tableDefinition);

You can use the following optional parameters to customize the createTable operation:

  • Class<T> (rowClass): Specify the type of the table’s row object. If not provided, the default is Row.

  • CreateTableOptions: Granular control over the createTable operation itself, such as timeouts.

  • TableOptions: Options for the returned Table<T> object, such as specific timeouts for that object.

// Specify options at creation
CreateTableOptions createTableOptions = new CreateTableOptions()
 .ifNotExists(true)
 .embeddingAuthProvider(new EmbeddingAPIKeyHeaderProvider("api-key"))
 .timeout(ofSeconds(5));

Table<Row> tableGames = database
 .createTable("games", tableDefinition, createTableOptions);

// Change the Type of objects in use instead of default Row
Table<Game> tableGames = database
 .createTable(
    "games",            // table name
    tableDefinition,    // table definition
    Game.class,         // bean for row
    createTableOptions);

Additionally, instead of explicitly defining the TableDefinition, you can use annotations to define the schema directly in your POJOs.

For example, given the following bean:

@EntityTable("game_ann1")
public class GameAnn1 {

    @PartitionBy(0)
    @Column(name ="match_id", type=TEXT )
    private String matchId;

    @PartitionSort(position = 0, order= SortOrder.ASCENDING)
    @Column(name ="round", type=INT)
    private Integer round;

    @Column(name ="score", type=INT)
    private Integer score;

    @Column(name ="when", type=TIMESTAMP)
    private Instant when;

    @Column(name ="winner", type=TEXT)
    private String winner;

    @Column(name ="fighters", type=SET, valueType = UUID)
    private Set<java.util.UUID> fighters;

    @Column(name ="m_vector", type=VECTOR, dimension = 3, metric = SimilarityMetric.COSINE)
    private DataAPIVector vector;
}

The following command creates a table with the name game_ann1 using the schema defined in the previously described GameAnn1 class:

Table<GameAnn1> tablGameAnn1 = database
  .createTable(GameAnn1.class);

However, there are two ways to optimize the class:

  • If the column names in the POJO match the field names, then you can omit the property name in the @Column annotation.

  • If the column types in the POJO aren’t ambiguous, then you can omit the property type in the @Column annotation.

The resulting simplified class is as follows:

@Data
@EntityTable("game_ann2")
public class Game {

    private Integer score;
    private Instant when;
    private String winner;
    private Set<UUID> fighters;

    @PartitionBy(0)
    @Column(name ="match_id")
    private String matchId;

    @PartitionSort(position = 0, order = SortOrder.ASCENDING)
    private Integer round;

    @Column(name ="m_vector", dimension = 3)
    private DataAPIVector vector;

    // getter, setters, constructor
}

Example:

package com.datastax.astra.client.database;

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.core.auth.EmbeddingAPIKeyHeaderProvider;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.Game;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.TableDefinition;
import com.datastax.astra.client.tables.TableOptions;
import com.datastax.astra.client.tables.definition.columns.ColumnDefinitionVector;
import com.datastax.astra.client.tables.definition.columns.ColumnTypes;
import com.datastax.astra.client.tables.commands.options.CreateTableOptions;
import com.datastax.astra.client.tables.definition.rows.Row;

import static com.datastax.astra.client.core.query.Sort.ascending;
import static com.datastax.astra.client.core.vector.SimilarityMetric.COSINE;
import static java.time.Duration.ofSeconds;

public class CreateTable {

 public static void main(String[] args) {
  // Database astraDb = new DataAPIClient(token).getDatabase(endpoint);
  Database db = DataAPIClients.localDbWithDefaultKeyspace();

  // Definition of the table in fluent style
  TableDefinition tableDefinition = new TableDefinition()
   .addColumnText("match_id")
   .addColumnInt("round")
   .addColumnVector("m_vector", 
     new ColumnDefinitionVector().dimension(3).metric(COSINE))
   .addColumn("score", ColumnTypes.INT)
   .addColumn("when",  ColumnTypes.TIMESTAMP)
   .addColumn("winner",  ColumnTypes.TEXT)
   .addColumnSet("fighters", ColumnTypes.UUID)
   .addPartitionBy("match_id")
   .addPartitionSort(ascending("round"));


  // Minimal creation
  Table<Row> table1 =
    db.createTable("games", tableDefinition);

  // Minimal Creation with a Bean
  Table<Game> table2 =
    db.createTable("game2", tableDefinition, Game.class);

  // One can add options to setup the creation with finer grained:
  CreateTableOptions createTableOptions = new CreateTableOptions()
   .keyspace("ks2")
   .ifNotExists(true)
   .embeddingAuthProvider(new EmbeddingAPIKeyHeaderProvider("api-key"))
   .timeout(ofSeconds(5));
  Table<Row> table3 =
    db.createTable("game3", tableDefinition, createTableOptions);
 }
}

To create a table, the JSON payload must include the table name, column definitions, and primary key definition.

The format of column definitions depends on the column’s data type. For more information, see definition.columns in this command’s Parameters table.

The primary key definition depends on the primary key type. The following examples demonstrate the JSON for the three primary key types. For more information, see Primary keys.

  • Single-column primary key

  • Composite primary key

  • Compound primary key

Create a table with a single-column primary key:

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "createTable": {
    "name": "TABLE_NAME",
    "definition": {
      "columns": {
        "COLUMN_NAME": "DATA_TYPE",
        "COLUMN_NAME": "DATA_TYPE"
      },
      "primaryKey": "COLUMN_NAME"
    }
  }
}' | jq

Create a table with a composite primary key:

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "createTable": {
    "name": "TABLE_NAME",
    "definition": {
      "columns": {
        "COLUMN_NAME": {
          "type": "DATA_TYPE"
        },
        "COLUMN_NAME": {
          "type": "DATA_TYPE"
        }
      },
      "primaryKey": {
        "partitionBy": [
          "COLUMN_NAME", "COLUMN_NAME"
        ]
      }
    }
  }
}' | jq

Create a table with a compound primary key:

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "createTable": {
    "name": "TABLE_NAME",
    "definition": {
      "columns": {
        "COLUMN_NAME": {
          "type": "DATA_TYPE"
        },
        "COLUMN_NAME": {
          "type": "DATA_TYPE"
        }
      },
      "primaryKey": {
        "partitionBy": [
          "PARTITION_COLUMN_NAME"
        ]
        "partitionSort": {
          "SORT_COLUMN_NAME": -1
        }
      }
    }
  }
}' | jq

To store pre-generated vectors in a table, you must define a vector column:

      "columns": {
        "COLUMN_NAME": "DATA_TYPE",
        "COLUMN_NAME": "DATA_TYPE",
        "VECTOR_COLUMN_NAME": {
          "type": "vector",
          "dimension": NUM_DIMENSIONS
        }
      }

To automatically generate embeddings with vectorize, define a vector column with embedding provider service options. Astra DB stores the automatically-generated embeddings in this column.

      "columns": {
        "COLUMN_NAME": "DATA_TYPE",
        "COLUMN_NAME": "DATA_TYPE",
        "VECTOR_COLUMN_NAME": {
          "type": "vector",
          "dimension": NUM_DIMENSIONS,
          "service": {
            "provider": "EMBEDDINGS_PROVIDER_NAME",
            "modelName": "MODEL_NAME",
            "authentication": {
              "providerKey": "ASTRA_KMS_API_KEY_NAME",
            }
          }
        }
      }

You can alter vector columns at any time to change the vector configuration, including adding or removing a vectorize integration.

For more information about all aspects of vectors in tables, see Vector type.

Examples:

Create a table with a single-column primary key 
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/default_keyspace" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "createTable": {
    "name": "students",
    "definition": {
      "columns": {
        "name": "text",
        "email": "text",
        "graduated": "boolean",
        "graduation_year": {
          "type": "int"
        },
        "semester_gpas": {
          "type": "list",
          "valueType": "decimal"
        },
        "grades": {
          "type": "map",
          "keyType": "text",
          "valueType": "int"
        },
        "extracurriculars": {
          "type": "set",
          "valueType": "text"
        },
        "vect_emb": {
          "type": "vector",
          "dimension": 1024
        }
      },
      "primaryKey": "email"
    }
  }
}' | jq
Create a table with a composite primary key 
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/default_keyspace" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "createTable": {
    "name": "students",
    "definition": {
      "columns": {
        "name": "text",
        "email": "text",
        "graduated": "boolean",
        "graduation_year": {
          "type": "int"
        },
        "semester_gpas": {
          "type": "list",
          "valueType": "decimal"
        },
        "grades": {
          "type": "map",
          "keyType": "text",
          "valueType": "int"
        },
        "extracurriculars": {
          "type": "set",
          "valueType": "text"
        },
        "vect_emb": {
          "type": "vector",
          "dimension": 1024
        }
      },
      "primaryKey": {
        "partitionBy": [
          "name", "email"
        ]
      }
    }
  }
}' | jq
Create a table with a compound primary key 
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/default_keyspace" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "createTable": {
    "name": "students",
    "definition": {
      "columns": {
        "name": "text",
        "email": "text",
        "graduated": "boolean",
        "graduation_year": {
          "type": "int"
        },
        "semester_gpas": {
          "type": "list",
          "valueType": "decimal"
        },
        "grades": {
          "type": "map",
          "keyType": "text",
          "valueType": "int"
        },
        "extracurriculars": {
          "type": "set",
          "valueType": "text"
        },
        "vect_emb": {
          "type": "vector",
          "dimension": 1024
        }
      },
      "primaryKey": {
        "partitionBy": [
          "graduation_year"
        ],
        "partitionSort": {
          "email": -1
        }
      }
    }
  }
}' | jq

Client reference

  • Python

  • TypeScript

  • Java

  • curl

For more information, see the client reference.

For more information, see the client reference.

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax | 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: +1 (650) 389-6000, info@datastax.com