Create a table (Python)

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

Parameters

Use the create_table method, which belongs to the astrapy.Database class.

Method signature

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,
  spawn_api_options: APIOptions,
) -> Table[ROW]

Name Type Summary

Name	Type	Summary
`name`	`str`	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
`definition`	`CreateTableDefinition` \| `dict`	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.
`row_type`	`type`	Optional. A formal specifier for the type checker. If provided, `row_type` must match the type hint specified in the assignment. For more information, see Typing support. Default: `Table[dict]`
`keyspace`	`str`	Optional if you specified a working keyspace when you created the `Database` object. The keyspace in which to create the table. Default: The working keyspace set when you created the `Database` object, if one was provided.
`if_not_exists`	`bool`	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
`spawn_api_options`	`APIOptions`	Optional. A complete or partial specification of the APIOptions to override the defaults inherited from the `Database`. Use this to customize the interaction of the Python client with the table. For example, you can change the serialization/deserialization options or default timeouts. If `APIOptions` is passed together with a named parameter such as a timeout, the latter takes precedence over the corresponding `spawn_api_options` setting.
`table_admin_timeout_ms`	`int`	Optional. A timeout, in milliseconds, for the underlying HTTP request. If not provided, the `Database` setting is used. This parameter is aliased as `request_timeout_ms` and `timeout_ms` for convenience.

name

str

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

definition

CreateTableDefinition | dict

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.

row_type

type

Optional. A formal specifier for the type checker. If provided, row_type must match the type hint specified in the assignment. For more information, see Typing support.

Default: Table[dict]

keyspace

str

Optional if you specified a working keyspace when you created the Database object. The keyspace in which to create the table.

Default: The working keyspace set when you created the Database object, if one was provided.

if_not_exists

bool

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

spawn_api_options

APIOptions

Optional. A complete or partial specification of the APIOptions to override the defaults inherited from the Database. Use this to customize the interaction of the Python client with the table. For example, you can change the serialization/deserialization options or default timeouts.

If APIOptions is passed together with a named parameter such as a timeout, the latter takes precedence over the corresponding spawn_api_options setting.

table_admin_timeout_ms

int

Optional. A timeout, in milliseconds, for the underlying HTTP request. If not provided, the Database setting is used. This parameter is aliased as request_timeout_ms and timeout_ms for convenience.

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 (Python).

The Python client supports multiple ways to create a table. In all cases, you must define the table schema, and then pass the definition to the create_table method.

The following example uses untyped documents or rows, but you can define a client-side type for your collection to help statically catch errors. For examples, see Typing support.

CreateTableDefinition object
Fluent interface
Dictionary

You can define the table as a CreateTableDefinition and then build the table from the CreateTableDefinition object.

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TableKeyValuedColumnType,
    TableKeyValuedColumnTypeDescriptor,
    TablePrimaryKeyDescriptor,
    TableScalarColumnTypeDescriptor,
    TableValuedColumnType,
    TableValuedColumnTypeDescriptor,
)

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
    keyspace="KEYSPACE_NAME",
)

table_definition = CreateTableDefinition(
    # Define all of the columns in the table
    columns={
        "title": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.TEXT
        ),
        "number_of_pages": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.INT
        ),
        "rating": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.FLOAT
        ),
        "genres": TableValuedColumnTypeDescriptor(
            column_type=TableValuedColumnType.SET,
            value_type=ColumnType.TEXT,
        ),
        "metadata": TableKeyValuedColumnTypeDescriptor(
            column_type=TableKeyValuedColumnType.MAP,
            key_type=ColumnType.TEXT,
            value_type=ColumnType.TEXT,
        ),
        "is_checked_out": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.BOOLEAN
        ),
        "due_date": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.DATE
        ),
    },
    # Define the primary key for the table.
    # In this case, the table uses a single-column primary key.
    primary_key=TablePrimaryKeyDescriptor(
        partition_by=["title"], partition_sort={}
    ),
)

table = database.create_table(
    "example_table", definition=table_definition
)

You can use a fluent interface to build the table definition and then create the table from the definition.

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.info import ColumnType, CreateTableDefinition

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
    keyspace="KEYSPACE_NAME",
)

table_definition = (
    CreateTableDefinition.builder()
    # Define all of the columns in the table
    .add_column("title", ColumnType.TEXT)
    .add_column("number_of_pages", ColumnType.INT)
    .add_column("rating", ColumnType.FLOAT)
    .add_set_column("genres", ColumnType.TEXT)
    .add_map_column(
        "metadata",
        # This is the key type for the map column
        ColumnType.TEXT,
        # This is the value type for the map column
        ColumnType.TEXT,
    )
    .add_column("is_checked_out", ColumnType.BOOLEAN)
    .add_column("due_date", ColumnType.DATE)
    # Define the primary key for the table.
    # In this case, the table uses a single-column primary key.
    .add_partition_by(["title"])
    # Finally, build the table definition.
    .build()
)

table = database.create_table(
    "example_table", definition=table_definition
)

You can define the table as a dictionary and then build the table from the dictionary.

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
    keyspace="KEYSPACE_NAME",
)

# Define the columns and primary key for the table
table_definition = {
    "columns": {
        "title": {"type": "text"},
        "number_of_pages": {"type": "int"},
        "rating": {"type": "float"},
        "genres": {"type": "set", "valueType": "text"},
        "metadata": {
            "type": "map",
            "keyType": "text",
            "valueType": "text",
        },
        "is_checked_out": {"type": "boolean"},
        "due_date": {"type": "date"},
    },
    "primaryKey": {
        "partitionBy": ["title"],
        "partitionSort": {},
    },
}

table = database.create_table(
    "example_table", definition=table_definition
)

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 (Python).

The Python client supports multiple ways to create a table. In all cases, you must define the table schema, and then pass the definition to the create_table method.

The following example uses untyped documents or rows, but you can define a client-side type for your collection to help statically catch errors. For examples, see Typing support.

CreateTableDefinition object
Fluent interface
Dictionary

You can define the table as a CreateTableDefinition and then build the table from the CreateTableDefinition object.

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TableKeyValuedColumnType,
    TableKeyValuedColumnTypeDescriptor,
    TablePrimaryKeyDescriptor,
    TableScalarColumnTypeDescriptor,
    TableValuedColumnType,
    TableValuedColumnTypeDescriptor,
)

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
    keyspace="KEYSPACE_NAME",
)

table_definition = CreateTableDefinition(
    # Define all of the columns in the table
    columns={
        "title": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.TEXT
        ),
        "number_of_pages": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.INT
        ),
        "rating": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.FLOAT
        ),
        "genres": TableValuedColumnTypeDescriptor(
            column_type=TableValuedColumnType.SET,
            value_type=ColumnType.TEXT,
        ),
        "metadata": TableKeyValuedColumnTypeDescriptor(
            column_type=TableKeyValuedColumnType.MAP,
            key_type=ColumnType.TEXT,
            value_type=ColumnType.TEXT,
        ),
        "is_checked_out": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.BOOLEAN
        ),
        "due_date": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.DATE
        ),
    },
    # Define the primary key for the table.
    # In this case, the table uses a composite primary key.
    primary_key=TablePrimaryKeyDescriptor(
        partition_by=["title", "rating"], partition_sort={}
    ),
)

table = database.create_table(
    "example_table", definition=table_definition
)

You can use a fluent interface to build the table definition and then create the table from the definition.

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.info import ColumnType, CreateTableDefinition

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
    keyspace="KEYSPACE_NAME",
)

table_definition = (
    CreateTableDefinition.builder()
    # Define all of the columns in the table
    .add_column("title", ColumnType.TEXT)
    .add_column("number_of_pages", ColumnType.INT)
    .add_column("rating", ColumnType.FLOAT)
    .add_set_column("genres", ColumnType.TEXT)
    .add_map_column(
        "metadata",
        # This is the key type for the map column
        ColumnType.TEXT,
        # This is the value type for the map column
        ColumnType.TEXT,
    )
    .add_column("is_checked_out", ColumnType.BOOLEAN)
    .add_column("due_date", ColumnType.DATE)
    # Define the primary key for the table.
    # In this case, the table uses a composite primary key.
    .add_partition_by(["title", "rating"])
    # Finally, build the table definition.
    .build()
)

table = database.create_table(
    "example_table", definition=table_definition
)

You can define the table as a dictionary and then build the table from the dictionary.

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
    keyspace="KEYSPACE_NAME",
)

# Define the columns and primary key for the table
table_definition = {
    "columns": {
        "title": {"type": "text"},
        "number_of_pages": {"type": "int"},
        "rating": {"type": "float"},
        "genres": {"type": "set", "valueType": "text"},
        "metadata": {
            "type": "map",
            "keyType": "text",
            "valueType": "text",
        },
        "is_checked_out": {"type": "boolean"},
        "due_date": {"type": "date"},
    },
    "primaryKey": {
        "partitionBy": ["title", "rating"],
        "partitionSort": {},
    },
}

table = database.create_table(
    "example_table", definition=table_definition
)

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 (Python).

The Python client supports multiple ways to create a table. In all cases, you must define the table schema, and then pass the definition to the create_table method.

The following example uses untyped documents or rows, but you can define a client-side type for your collection to help statically catch errors. For examples, see Typing support.

CreateTableDefinition object
Fluent interface
Dictionary

You can define the table as a CreateTableDefinition and then build the table from the CreateTableDefinition object.

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment, SortMode
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TableKeyValuedColumnType,
    TableKeyValuedColumnTypeDescriptor,
    TablePrimaryKeyDescriptor,
    TableScalarColumnTypeDescriptor,
    TableValuedColumnType,
    TableValuedColumnTypeDescriptor,
)

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
    keyspace="KEYSPACE_NAME",
)

table_definition = CreateTableDefinition(
    # Define all of the columns in the table
    columns={
        "title": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.TEXT
        ),
        "number_of_pages": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.INT
        ),
        "rating": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.FLOAT
        ),
        "genres": TableValuedColumnTypeDescriptor(
            column_type=TableValuedColumnType.SET,
            value_type=ColumnType.TEXT,
        ),
        "metadata": TableKeyValuedColumnTypeDescriptor(
            column_type=TableKeyValuedColumnType.MAP,
            key_type=ColumnType.TEXT,
            value_type=ColumnType.TEXT,
        ),
        "is_checked_out": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.BOOLEAN
        ),
        "due_date": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.DATE
        ),
    },
    # Define the primary key for the table.
    # In this case, the table uses a compound primary key.
    primary_key=TablePrimaryKeyDescriptor(
        partition_by=["title", "rating"],
        partition_sort={
            "number_of_pages": SortMode.ASCENDING,
            "is_checked_out": SortMode.DESCENDING,
        },
    ),
)

table = database.create_table(
    "example_table", definition=table_definition
)

You can use a fluent interface to build the table definition and then create the table from the definition.

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment, SortMode
from astrapy.info import ColumnType, CreateTableDefinition

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
    keyspace="KEYSPACE_NAME",
)

table_definition = (
    CreateTableDefinition.builder()
    # Define all of the columns in the table
    .add_column("title", ColumnType.TEXT)
    .add_column("number_of_pages", ColumnType.INT)
    .add_column("rating", ColumnType.FLOAT)
    .add_set_column("genres", ColumnType.TEXT)
    .add_map_column(
        "metadata",
        # This is the key type for the map column
        ColumnType.TEXT,
        # This is the value type for the map column
        ColumnType.TEXT,
    )
    .add_column("is_checked_out", ColumnType.BOOLEAN)
    .add_column("due_date", ColumnType.DATE)
    # Define the primary key for the table.
    # In this case, the table uses a compound primary key.
    .add_partition_by(["title", "rating"])
    .add_partition_sort(
        {
            "number_of_pages": SortMode.ASCENDING,
            "is_checked_out": SortMode.DESCENDING,
        }
    )
    # Finally, build the table definition.
    .build()
)

table = database.create_table(
    "example_table", definition=table_definition
)

You can define the table as a dictionary and then build the table from the dictionary.

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
    keyspace="KEYSPACE_NAME",
)

# Define the columns and primary key for the table
table_definition = {
    "columns": {
        "title": {"type": "text"},
        "number_of_pages": {"type": "int"},
        "rating": {"type": "float"},
        "genres": {"type": "set", "valueType": "text"},
        "metadata": {
            "type": "map",
            "keyType": "text",
            "valueType": "text",
        },
        "is_checked_out": {"type": "boolean"},
        "due_date": {"type": "date"},
    },
    "primaryKey": {
        "partitionBy": ["title", "rating"],
        "partitionSort": {"number_of_pages": 1, "is_checked_out": -1},
    },
}

table = database.create_table(
    "example_table", definition=table_definition
)

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 Python client supports multiple ways to create a table. In all cases, you must define the table schema, and then pass the definition to the create_table method.

The following example uses untyped documents or rows, but you can define a client-side type for your collection to help statically catch errors. For examples, see Typing support.

CreateTableDefinition object
Fluent interface
Dictionary

You can define the table as a CreateTableDefinition and then build the table from the CreateTableDefinition object.

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TablePrimaryKeyDescriptor,
    TableScalarColumnTypeDescriptor,
    TableVectorColumnTypeDescriptor,
)

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
    keyspace="KEYSPACE_NAME",
)

table_definition = CreateTableDefinition(
    # Define all of the columns in the table
    columns={
        "example_vector": TableVectorColumnTypeDescriptor(dimension=1024),
        "example_non_vector": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.TEXT
        ),
    },
    # Define the primary key for the table.
    # In this case, the table uses a single-column primary key.
    primary_key=TablePrimaryKeyDescriptor(
        partition_by=["example_non_vector"], partition_sort={}
    ),
)

table = database.create_table(
    "example_table", definition=table_definition
)

You can use a fluent interface to build the table definition and then create the table from the definition.

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.info import ColumnType, CreateTableDefinition

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
    keyspace="KEYSPACE_NAME",
)

table_definition = (
    CreateTableDefinition.builder()
    # Define all of the columns in the table
    .add_vector_column("example_vector", dimension=1024)
    .add_column("example_non_vector", ColumnType.TEXT)
    # Define the primary key for the table.
    # In this case, the table uses a single-column primary key.
    .add_partition_by(["example_non_vector"])
    # Finally, build the table definition.
    .build()
)

table = database.create_table(
    "example_table", definition=table_definition
)

You can define the table as a dictionary and then build the table from the dictionary.

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
    keyspace="KEYSPACE_NAME",
)

# Define the columns and primary key for the table
table_definition = {
    "columns": {
        "example_vector": {"type": "vector", "dimension": 1024},
        "example_non_vector": {"type": "text"},
    },
    "primaryKey": {
        "partitionBy": ["example_non_vector"],
        "partitionSort": {},
    },
}

table = database.create_table(
    "example_table", definition=table_definition
)

Client reference

For more information, see the client reference.

Create a table (Python)

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

Client reference

Was this helpful?

Give Feedback