Create a table (Python)

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,
  embedding_api_key: str | EmbeddingHeadersProvider,
  spawn_api_options: APIOptions,
) -> Table[ROW]
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. The keyspace in which to create the table.

For an example, see Create a table and specify the keyspace.

Default: The working keyspace for the database. This is default_keyspace unless you set a different working keyspace when you created the Database object.

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

embedding_api_key

str | EmbeddingHeadersProvider

Optional. This only applies to tables that have a vector column with a vectorize embedding provider integration.

Use this option to provide the embedding provider API key directly with headers instead of using an API key in the Astra DB KMS.

The API key is sent to the Data API for every operation on the table. It is useful when a vectorize integration is configured but no credentials are stored, or when you want to override the stored credentials. For more information, see Manage embedding provider integrations for vectorize.

You can use this authentication method only if all affected columns use the same embedding provider.

If you use an AWS embedding provider, the embedding_api_key argument must instead use the AWSEmbeddingHeadersProvider class to pass your access ID and secret ID.

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.info import (
    ColumnType,
    CreateTableDefinition,
    TableKeyValuedColumnType,
    TableKeyValuedColumnTypeDescriptor,
    TablePrimaryKeyDescriptor,
    TableScalarColumnTypeDescriptor,
    TableValuedColumnType,
    TableValuedColumnTypeDescriptor,
)

# Get an existing database
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

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.info import ColumnType, CreateTableDefinition

# Get an existing database
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

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

# Get an existing database
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# 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.info import (
    ColumnType,
    CreateTableDefinition,
    TableKeyValuedColumnType,
    TableKeyValuedColumnTypeDescriptor,
    TablePrimaryKeyDescriptor,
    TableScalarColumnTypeDescriptor,
    TableValuedColumnType,
    TableValuedColumnTypeDescriptor,
)

# Get an existing database
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

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.info import ColumnType, CreateTableDefinition

# Get an existing database
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

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

# Get an existing database
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# 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.constants import SortMode
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TableKeyValuedColumnType,
    TableKeyValuedColumnTypeDescriptor,
    TablePrimaryKeyDescriptor,
    TableScalarColumnTypeDescriptor,
    TableValuedColumnType,
    TableValuedColumnTypeDescriptor,
)

# Get an existing database
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

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.constants import SortMode
from astrapy.info import ColumnType, CreateTableDefinition

# Get an existing database
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

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

# Get an existing database
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# 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.info import (
    ColumnType,
    CreateTableDefinition,
    TablePrimaryKeyDescriptor,
    TableScalarColumnTypeDescriptor,
    TableVectorColumnTypeDescriptor,
)

# Get an existing database
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

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.info import ColumnType, CreateTableDefinition

# Get an existing database
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

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

# Get an existing database
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# 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,
)

Create a table with a column to automatically generate vector embeddings

If you want to automatically generate vector embeddings, create a table with a vector column and configure an embedding provider integration for the column.

The configuration depends on the embedding provider.

You can also configure an embedding provider integration after table creation. For more information, see Alter a table (Python).

If you want to store the original text in addition to the vector embeddings that were generated from the text, then you need to create a separate column to store the text.

You can configure a different embedding provider for each vector column in the table. If you want to use the same embedding provider for all vector columns in the table, you must still configure the embedding provider for each vector column.

Configure Azure OpenAI as the embedding provider

For more detailed instructions, see Integrate Azure OpenAI as an embedding provider.

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.

  • TableDefinition object

  • Fluent interface

  • Dictionary

from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TablePrimaryKeyDescriptor,
    TableScalarColumnTypeDescriptor,
    TableVectorColumnTypeDescriptor,
    TableVectorIndexOptions,
    VectorServiceOptions,
)

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = CreateTableDefinition(
    columns={
        # This column will store vector embeddings.
        # The configured vector service
        # will automatically generate vector embeddings
        # for any text inserted to this column.
        "VECTOR_COLUMN_NAME": TableVectorColumnTypeDescriptor(
            dimension=MODEL_DIMENSIONS,
            service=VectorServiceOptions(
                provider="azureOpenAI",
                model_name="MODEL_NAME",
                authentication={
                    "providerKey": "API_KEY_NAME",
                },
                parameters={
                    "resourceName": "RESOURCE_NAME",
                    "deploymentId": "DEPLOYMENT_ID",
                },
            ),
        ),
        # If you want to store the original text
        # in addition to the generated embeddings
        # you must create a separate column.
        "TEXT_COLUMN_NAME": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.TEXT
        ),
    },
    # You should change the primary key definition to meet the needs of your data.
    primary_key=TablePrimaryKeyDescriptor(
        partition_by=["TEXT_COLUMN_NAME"], partition_sort={}
    ),
)

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TableVectorIndexOptions,
    VectorServiceOptions,
)

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = (
    CreateTableDefinition.builder()
    # This column will store vector embeddings.
    # The configured vector service
    # will automatically generate vector embeddings
    # for any text inserted to this column.
    .add_vector_column(
        "VECTOR_COLUMN_NAME",
        dimension=MODEL_DIMENSIONS,
        service=VectorServiceOptions(
            provider="azureOpenAI",
            model_name="MODEL_NAME",
            authentication={
                "providerKey": "API_KEY_NAME",
            },
            parameters={
                "resourceName": "RESOURCE_NAME",
                "deploymentId": "DEPLOYMENT_ID",
            },
        ),
    )
    # If you want to store the original text
    # in addition to the generated embeddings
    # you must create a separate column.
    .add_column("TEXT_COLUMN_NAME", ColumnType.TEXT)
    # You should change the primary key definition to meet the needs of your data.
    .add_partition_by(["TEXT_COLUMN_NAME"])
    # Finally, build the table definition.
    .build()
)

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import TableVectorIndexOptions

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = {
    "columns": {
        # This column will store vector embeddings.
        # The configured vector service
        # will automatically generate vector embeddings
        # for any text inserted to this column.
        "VECTOR_COLUMN_NAME": {
            "type": "vector",
            "dimension": MODEL_DIMENSIONS,
            "service": {
                "provider": "azureOpenAI",
                "model_name": "MODEL_NAME",
                "authentication": {
                    "providerKey": "API_KEY_NAME",
                },
                "parameters": {
                    "resourceName": "RESOURCE_NAME",
                    "deploymentId": "DEPLOYMENT_ID",
                },
            },
        },
        # If you want to store the original text
        # in addition to the generated embeddings
        # you must create a separate column.
        "TEXT_COLUMN_NAME": {"type": "text"},
    },
    # You should change the primary key definition to meet the needs of your data.
    "primaryKey": {
        "partitionBy": ["TEXT_COLUMN_NAME"],
        "partitionSort": {},
    },
}

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)

Replace the following:

  • TABLE_NAME: The name for your table.

  • VECTOR_COLUMN_NAME: The name for your vector column.

  • TEXT_COLUMN_NAME: The name for the text column that will store the original text. Omit this column if you won’t store the original text in addition to the generated embeddings.

  • API_KEY_NAME: The name of the Azure OpenAI API key that you want to use. Must be the name of an existing Azure OpenAI API key in the Astra Portal. For more information, see Embedding provider authentication.

    Alternatively, you can omit this parameter and instead provide the authentication key in the embedding_api_key parameter when you instantiate a Table object with the commands to create a table or get a table. The client will send the x-embedding-api-key header with the specified key to any underlying HTTP request that requires vectorize authentication. Header authentication overrides the API_KEY_NAME parameter if you set both. If you use the header instead of specifying the API_KEY_NAME parameter, you must include the header in every command that uses vectorize, including writes and vector search. You can use this authentication method only if all affected columns use the same embedding provider.

  • MODEL_NAME: The model that you want to use to generate embeddings. The available models are: text-embedding-3-small, text-embedding-3-large, text-embedding-ada-002.

    For Azure OpenAI, you must select the model that matches the one deployed to your DEPLOYMENT_ID in Azure.

  • MODEL_DIMENSIONS: The number of dimensions that you want the generated vectors to have. Your chosen embedding model must support the specified number of dimensions.

    If you omit the dimension, Astra DB can use a default dimension value. However, some models don’t have default dimensions. You can use the Data API to find supported embedding providers and their configuration parameters, including dimensions ranges and default dimensions.

  • RESOURCE_NAME: The name of your Azure OpenAI Service resource, as defined in the resource’s Instance details. For more information, see the Azure OpenAI documentation.

  • DEPLOYMENT_ID: Your Azure OpenAI resource’s Deployment name. For more information, see the Azure OpenAI documentation.

Configure Hugging Face (Dedicated) as the embedding provider

For more detailed instructions, see Integrate Hugging Face Dedicated as an embedding provider.

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.

  • TableDefinition object

  • Fluent interface

  • Dictionary

from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TablePrimaryKeyDescriptor,
    TableScalarColumnTypeDescriptor,
    TableVectorColumnTypeDescriptor,
    TableVectorIndexOptions,
    VectorServiceOptions,
)

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = CreateTableDefinition(
    columns={
        # This column will store vector embeddings.
        # The configured vector service
        # will automatically generate vector embeddings
        # for any text inserted to this column.
        "VECTOR_COLUMN_NAME": TableVectorColumnTypeDescriptor(
            dimension=MODEL_DIMENSIONS,
            service=VectorServiceOptions(
                provider="huggingfaceDedicated",
                model_name="MODEL_NAME",
                authentication={
                    "providerKey": "API_KEY_NAME",
                },
                parameters={
                    "endpointName": "ENDPOINT_NAME",
                    "regionName": "REGION",
                    "cloudName": "CLOUD_PROVIDER",
                },
            ),
        ),
        # If you want to store the original text
        # in addition to the generated embeddings
        # you must create a separate column.
        "TEXT_COLUMN_NAME": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.TEXT
        ),
    },
    # You should change the primary key definition to meet the needs of your data.
    primary_key=TablePrimaryKeyDescriptor(
        partition_by=["TEXT_COLUMN_NAME"], partition_sort={}
    ),
)

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TableVectorIndexOptions,
    VectorServiceOptions,
)

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = (
    CreateTableDefinition.builder()
    # This column will store vector embeddings.
    # The configured vector service
    # will automatically generate vector embeddings
    # for any text inserted to this column.
    .add_vector_column(
        "VECTOR_COLUMN_NAME",
        dimension=MODEL_DIMENSIONS,
        service=VectorServiceOptions(
            provider="huggingfaceDedicated",
            model_name="MODEL_NAME",
            authentication={
                "providerKey": "API_KEY_NAME",
            },
            parameters={
                "endpointName": "ENDPOINT_NAME",
                "regionName": "REGION",
                "cloudName": "CLOUD_PROVIDER",
            },
        ),
    )
    # If you want to store the original text
    # in addition to the generated embeddings
    # you must create a separate column.
    .add_column("TEXT_COLUMN_NAME", ColumnType.TEXT)
    # You should change the primary key definition to meet the needs of your data.
    .add_partition_by(["TEXT_COLUMN_NAME"])
    # Finally, build the table definition.
    .build()
)

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import TableVectorIndexOptions

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = {
    "columns": {
        # This column will store vector embeddings.
        # The configured vector service
        # will automatically generate vector embeddings
        # for any text inserted to this column.
        "VECTOR_COLUMN_NAME": {
            "type": "vector",
            "dimension": MODEL_DIMENSIONS,
            "service": {
                "provider": "huggingfaceDedicated",
                "model_name": "MODEL_NAME",
                "authentication": {
                    "providerKey": "API_KEY_NAME",
                },
                "parameters": {
                    "endpointName": "ENDPOINT_NAME",
                    "regionName": "REGION",
                    "cloudName": "CLOUD_PROVIDER",
                },
            },
        },
        # If you want to store the original text
        # in addition to the generated embeddings
        # you must create a separate column.
        "TEXT_COLUMN_NAME": {"type": "text"},
    },
    # You should change the primary key definition to meet the needs of your data.
    "primaryKey": {
        "partitionBy": ["TEXT_COLUMN_NAME"],
        "partitionSort": {},
    },
}

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)

Replace the following:

  • TABLE_NAME: The name for your table.

  • VECTOR_COLUMN_NAME: The name for your vector column.

  • TEXT_COLUMN_NAME: The name for the text column that will store the original text. Omit this column if you won’t store the original text in addition to the generated embeddings.

  • API_KEY_NAME: The name of the Hugging Face Dedicated user access token that you want to use. Must be the name of an existing Hugging Face Dedicated user access token in the Astra Portal. For more information, see Embedding provider authentication.

    Alternatively, you can omit this parameter and instead provide the authentication key in the embedding_api_key parameter when you instantiate a Table object with the commands to create a table or get a table. The client will send the x-embedding-api-key header with the specified key to any underlying HTTP request that requires vectorize authentication. Header authentication overrides the API_KEY_NAME parameter if you set both. If you use the header instead of specifying the API_KEY_NAME parameter, you must include the header in every command that uses vectorize, including writes and vector search. You can use this authentication method only if all affected columns use the same embedding provider.

  • MODEL_NAME: The model that you want to use to generate embeddings. The available models are: endpoint-defined-model.

    For Hugging Face Dedicated, you must deploy the model as a text embeddings inference (TEI) container.

    You must set MODEL_NAME to endpoint-defined-model because this integration uses the model specified in your dedicated endpoint configuration.

  • MODEL_DIMENSIONS: The number of dimensions that you want the generated vectors to have. Your chosen embedding model must support the specified number of dimensions.

    If you omit the dimension, Astra DB can use a default dimension value. However, some models don’t have default dimensions. You can use the Data API to find supported embedding providers and their configuration parameters, including dimensions ranges and default dimensions.

  • ENDPOINT_NAME: The programmatically-generated name of your Hugging Face Dedicated endpoint. This is the first part of the endpoint URL. For example, if your endpoint URL is https://mtp1x7muf6qyn3yh.us-east-2.aws.endpoints.huggingface.cloud, the endpoint name is mtp1x7muf6qyn3yh.

  • REGION: The cloud provider region your Hugging Face Dedicated endpoint is deployed to. For example, us-east-2.

  • CLOUD_PROVIDER: The cloud provider your Hugging Face Dedicated endpoint is deployed to. For example, aws.

Configure Hugging Face (Serverless) as the embedding provider

For more detailed instructions, see Integrate Hugging Face Serverless as an embedding provider.

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.

  • TableDefinition object

  • Fluent interface

  • Dictionary

from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TablePrimaryKeyDescriptor,
    TableScalarColumnTypeDescriptor,
    TableVectorColumnTypeDescriptor,
    TableVectorIndexOptions,
    VectorServiceOptions,
)

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = CreateTableDefinition(
    columns={
        # This column will store vector embeddings.
        # The configured vector service
        # will automatically generate vector embeddings
        # for any text inserted to this column.
        "VECTOR_COLUMN_NAME": TableVectorColumnTypeDescriptor(
            dimension=MODEL_DIMENSIONS,
            service=VectorServiceOptions(
                provider="huggingface",
                model_name="MODEL_NAME",
                authentication={
                    "providerKey": "API_KEY_NAME",
                },
            ),
        ),
        # If you want to store the original text
        # in addition to the generated embeddings
        # you must create a separate column.
        "TEXT_COLUMN_NAME": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.TEXT
        ),
    },
    # You should change the primary key definition to meet the needs of your data.
    primary_key=TablePrimaryKeyDescriptor(
        partition_by=["TEXT_COLUMN_NAME"], partition_sort={}
    ),
)

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TableVectorIndexOptions,
    VectorServiceOptions,
)

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = (
    CreateTableDefinition.builder()
    # This column will store vector embeddings.
    # The configured vector service
    # will automatically generate vector embeddings
    # for any text inserted to this column.
    .add_vector_column(
        "VECTOR_COLUMN_NAME",
        dimension=MODEL_DIMENSIONS,
        service=VectorServiceOptions(
            provider="huggingface",
            model_name="MODEL_NAME",
            authentication={
                "providerKey": "API_KEY_NAME",
            },
        ),
    )
    # If you want to store the original text
    # in addition to the generated embeddings
    # you must create a separate column.
    .add_column("TEXT_COLUMN_NAME", ColumnType.TEXT)
    # You should change the primary key definition to meet the needs of your data.
    .add_partition_by(["TEXT_COLUMN_NAME"])
    # Finally, build the table definition.
    .build()
)

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import TableVectorIndexOptions

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = {
    "columns": {
        # This column will store vector embeddings.
        # The configured vector service
        # will automatically generate vector embeddings
        # for any text inserted to this column.
        "VECTOR_COLUMN_NAME": {
            "type": "vector",
            "dimension": MODEL_DIMENSIONS,
            "service": {
                "provider": "huggingface",
                "model_name": "MODEL_NAME",
                "authentication": {
                    "providerKey": "API_KEY_NAME",
                },
            },
        },
        # If you want to store the original text
        # in addition to the generated embeddings
        # you must create a separate column.
        "TEXT_COLUMN_NAME": {"type": "text"},
    },
    # You should change the primary key definition to meet the needs of your data.
    "primaryKey": {
        "partitionBy": ["TEXT_COLUMN_NAME"],
        "partitionSort": {},
    },
}

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)

Replace the following:

  • TABLE_NAME: The name for your table.

  • VECTOR_COLUMN_NAME: The name for your vector column.

  • TEXT_COLUMN_NAME: The name for the text column that will store the original text. Omit this column if you won’t store the original text in addition to the generated embeddings.

  • API_KEY_NAME: The name of the Hugging Face Serverless user access token that you want to use. Must be the name of an existing Hugging Face Serverless user access token in the Astra Portal. For more information, see Embedding provider authentication.

    Alternatively, you can omit this parameter and instead provide the authentication key in the embedding_api_key parameter when you instantiate a Table object with the commands to create a table or get a table. The client will send the x-embedding-api-key header with the specified key to any underlying HTTP request that requires vectorize authentication. Header authentication overrides the API_KEY_NAME parameter if you set both. If you use the header instead of specifying the API_KEY_NAME parameter, you must include the header in every command that uses vectorize, including writes and vector search. You can use this authentication method only if all affected columns use the same embedding provider.

  • MODEL_NAME: The model that you want to use to generate embeddings. The available models are: sentence-transformers/all-MiniLM-L6-v2, intfloat/multilingual-e5-large, intfloat/multilingual-e5-large-instruct, BAAI/bge-small-en-v1.5, BAAI/bge-base-en-v1.5, BAAI/bge-large-en-v1.5.

  • MODEL_DIMENSIONS: The number of dimensions that you want the generated vectors to have. Your chosen embedding model must support the specified number of dimensions.

    If you omit the dimension, Astra DB can use a default dimension value. However, some models don’t have default dimensions. You can use the Data API to find supported embedding providers and their configuration parameters, including dimensions ranges and default dimensions.

Configure Jina AI as the embedding provider

For more detailed instructions, see Integrate Jina AI as an embedding provider.

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.

  • TableDefinition object

  • Fluent interface

  • Dictionary

from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TablePrimaryKeyDescriptor,
    TableScalarColumnTypeDescriptor,
    TableVectorColumnTypeDescriptor,
    TableVectorIndexOptions,
    VectorServiceOptions,
)

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = CreateTableDefinition(
    columns={
        # This column will store vector embeddings.
        # The configured vector service
        # will automatically generate vector embeddings
        # for any text inserted to this column.
        "VECTOR_COLUMN_NAME": TableVectorColumnTypeDescriptor(
            dimension=MODEL_DIMENSIONS,
            service=VectorServiceOptions(
                provider="jinaAI",
                model_name="MODEL_NAME",
                authentication={
                    "providerKey": "API_KEY_NAME",
                },
            ),
        ),
        # If you want to store the original text
        # in addition to the generated embeddings
        # you must create a separate column.
        "TEXT_COLUMN_NAME": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.TEXT
        ),
    },
    # You should change the primary key definition to meet the needs of your data.
    primary_key=TablePrimaryKeyDescriptor(
        partition_by=["TEXT_COLUMN_NAME"], partition_sort={}
    ),
)

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TableVectorIndexOptions,
    VectorServiceOptions,
)

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = (
    CreateTableDefinition.builder()
    # This column will store vector embeddings.
    # The configured vector service
    # will automatically generate vector embeddings
    # for any text inserted to this column.
    .add_vector_column(
        "VECTOR_COLUMN_NAME",
        dimension=MODEL_DIMENSIONS,
        service=VectorServiceOptions(
            provider="jinaAI",
            model_name="MODEL_NAME",
            authentication={
                "providerKey": "API_KEY_NAME",
            },
        ),
    )
    # If you want to store the original text
    # in addition to the generated embeddings
    # you must create a separate column.
    .add_column("TEXT_COLUMN_NAME", ColumnType.TEXT)
    # You should change the primary key definition to meet the needs of your data.
    .add_partition_by(["TEXT_COLUMN_NAME"])
    # Finally, build the table definition.
    .build()
)

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import TableVectorIndexOptions

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = {
    "columns": {
        # This column will store vector embeddings.
        # The configured vector service
        # will automatically generate vector embeddings
        # for any text inserted to this column.
        "VECTOR_COLUMN_NAME": {
            "type": "vector",
            "dimension": MODEL_DIMENSIONS,
            "service": {
                "provider": "jinaAI",
                "model_name": "MODEL_NAME",
                "authentication": {
                    "providerKey": "API_KEY_NAME",
                },
            },
        },
        # If you want to store the original text
        # in addition to the generated embeddings
        # you must create a separate column.
        "TEXT_COLUMN_NAME": {"type": "text"},
    },
    # You should change the primary key definition to meet the needs of your data.
    "primaryKey": {
        "partitionBy": ["TEXT_COLUMN_NAME"],
        "partitionSort": {},
    },
}

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)

Replace the following:

  • TABLE_NAME: The name for your table.

  • VECTOR_COLUMN_NAME: The name for your vector column.

  • TEXT_COLUMN_NAME: The name for the text column that will store the original text. Omit this column if you won’t store the original text in addition to the generated embeddings.

  • API_KEY_NAME: The name of the Jina AI API key that you want to use. Must be the name of an existing Jina AI API key in the Astra Portal. For more information, see Embedding provider authentication.

    Alternatively, you can omit this parameter and instead provide the authentication key in the embedding_api_key parameter when you instantiate a Table object with the commands to create a table or get a table. The client will send the x-embedding-api-key header with the specified key to any underlying HTTP request that requires vectorize authentication. Header authentication overrides the API_KEY_NAME parameter if you set both. If you use the header instead of specifying the API_KEY_NAME parameter, you must include the header in every command that uses vectorize, including writes and vector search. You can use this authentication method only if all affected columns use the same embedding provider.

  • MODEL_NAME: The model that you want to use to generate embeddings. The available models are: jina-embeddings-v2-base-en, jina-embeddings-v2-base-de, jina-embeddings-v2-base-es, jina-embeddings-v2-base-code, jina-embeddings-v2-base-zh.

  • MODEL_DIMENSIONS: The number of dimensions that you want the generated vectors to have. Your chosen embedding model must support the specified number of dimensions.

    If you omit the dimension, Astra DB can use a default dimension value. However, some models don’t have default dimensions. You can use the Data API to find supported embedding providers and their configuration parameters, including dimensions ranges and default dimensions.

Configure Mistral AI as the embedding provider

For more detailed instructions, see Integrate Mistral AI as an embedding provider.

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.

  • TableDefinition object

  • Fluent interface

  • Dictionary

from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TablePrimaryKeyDescriptor,
    TableScalarColumnTypeDescriptor,
    TableVectorColumnTypeDescriptor,
    TableVectorIndexOptions,
    VectorServiceOptions,
)

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = CreateTableDefinition(
    columns={
        # This column will store vector embeddings.
        # The configured vector service
        # will automatically generate vector embeddings
        # for any text inserted to this column.
        "VECTOR_COLUMN_NAME": TableVectorColumnTypeDescriptor(
            dimension=MODEL_DIMENSIONS,
            service=VectorServiceOptions(
                provider="mistral",
                model_name="MODEL_NAME",
                authentication={
                    "providerKey": "API_KEY_NAME",
                },
            ),
        ),
        # If you want to store the original text
        # in addition to the generated embeddings
        # you must create a separate column.
        "TEXT_COLUMN_NAME": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.TEXT
        ),
    },
    # You should change the primary key definition to meet the needs of your data.
    primary_key=TablePrimaryKeyDescriptor(
        partition_by=["TEXT_COLUMN_NAME"], partition_sort={}
    ),
)

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TableVectorIndexOptions,
    VectorServiceOptions,
)

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = (
    CreateTableDefinition.builder()
    # This column will store vector embeddings.
    # The configured vector service
    # will automatically generate vector embeddings
    # for any text inserted to this column.
    .add_vector_column(
        "VECTOR_COLUMN_NAME",
        dimension=MODEL_DIMENSIONS,
        service=VectorServiceOptions(
            provider="mistral",
            model_name="MODEL_NAME",
            authentication={
                "providerKey": "API_KEY_NAME",
            },
        ),
    )
    # If you want to store the original text
    # in addition to the generated embeddings
    # you must create a separate column.
    .add_column("TEXT_COLUMN_NAME", ColumnType.TEXT)
    # You should change the primary key definition to meet the needs of your data.
    .add_partition_by(["TEXT_COLUMN_NAME"])
    # Finally, build the table definition.
    .build()
)

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import TableVectorIndexOptions

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = {
    "columns": {
        # This column will store vector embeddings.
        # The configured vector service
        # will automatically generate vector embeddings
        # for any text inserted to this column.
        "VECTOR_COLUMN_NAME": {
            "type": "vector",
            "dimension": MODEL_DIMENSIONS,
            "service": {
                "provider": "mistral",
                "model_name": "MODEL_NAME",
                "authentication": {
                    "providerKey": "API_KEY_NAME",
                },
            },
        },
        # If you want to store the original text
        # in addition to the generated embeddings
        # you must create a separate column.
        "TEXT_COLUMN_NAME": {"type": "text"},
    },
    # You should change the primary key definition to meet the needs of your data.
    "primaryKey": {
        "partitionBy": ["TEXT_COLUMN_NAME"],
        "partitionSort": {},
    },
}

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)

Replace the following:

  • TABLE_NAME: The name for your table.

  • VECTOR_COLUMN_NAME: The name for your vector column.

  • TEXT_COLUMN_NAME: The name for the text column that will store the original text. Omit this column if you won’t store the original text in addition to the generated embeddings.

  • API_KEY_NAME: The name of the Mistral AI API key that you want to use. Must be the name of an existing Mistral AI API key in the Astra Portal. For more information, see Embedding provider authentication.

    Alternatively, you can omit this parameter and instead provide the authentication key in the embedding_api_key parameter when you instantiate a Table object with the commands to create a table or get a table. The client will send the x-embedding-api-key header with the specified key to any underlying HTTP request that requires vectorize authentication. Header authentication overrides the API_KEY_NAME parameter if you set both. If you use the header instead of specifying the API_KEY_NAME parameter, you must include the header in every command that uses vectorize, including writes and vector search. You can use this authentication method only if all affected columns use the same embedding provider.

  • MODEL_NAME: The model that you want to use to generate embeddings. The available models are: mistral-embed.

  • MODEL_DIMENSIONS: The number of dimensions that you want the generated vectors to have. Your chosen embedding model must support the specified number of dimensions.

    If you omit the dimension, Astra DB can use a default dimension value. However, some models don’t have default dimensions. You can use the Data API to find supported embedding providers and their configuration parameters, including dimensions ranges and default dimensions.

Configure NVIDIA as the embedding provider

For more detailed instructions, see Integrate NVIDIA as an embedding provider. Your database must be in a supported region.

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.

  • TableDefinition object

  • Fluent interface

  • Dictionary

from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TablePrimaryKeyDescriptor,
    TableScalarColumnTypeDescriptor,
    TableVectorColumnTypeDescriptor,
    TableVectorIndexOptions,
    VectorServiceOptions,
)

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = CreateTableDefinition(
    columns={
        # This column will store vector embeddings.
        # The configured vector service
        # will automatically generate vector embeddings
        # for any text inserted to this column.
        "VECTOR_COLUMN_NAME": TableVectorColumnTypeDescriptor(
            service=VectorServiceOptions(
                provider="nvidia",
                model_name="nvidia/nv-embedqa-e5-v5",
            ),
        ),
        # If you want to store the original text
        # in addition to the generated embeddings
        # you must create a separate column.
        "TEXT_COLUMN_NAME": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.TEXT
        ),
    },
    # You should change the primary key definition to meet the needs of your data.
    primary_key=TablePrimaryKeyDescriptor(
        partition_by=["TEXT_COLUMN_NAME"], partition_sort={}
    ),
)

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TableVectorIndexOptions,
    VectorServiceOptions,
)

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = (
    CreateTableDefinition.builder()
    # This column will store vector embeddings.
    # The configured vector service
    # will automatically generate vector embeddings
    # for any text inserted to this column.
    .add_vector_column(
        "VECTOR_COLUMN_NAME",
        service=VectorServiceOptions(
            provider="nvidia",
            model_name="nvidia/nv-embedqa-e5-v5",
        ),
    )
    # If you want to store the original text
    # in addition to the generated embeddings
    # you must create a separate column.
    .add_column("TEXT_COLUMN_NAME", ColumnType.TEXT)
    # You should change the primary key definition to meet the needs of your data.
    .add_partition_by(["TEXT_COLUMN_NAME"])
    # Finally, build the table definition.
    .build()
)

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import TableVectorIndexOptions

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = {
    "columns": {
        # This column will store vector embeddings.
        # The configured vector service
        # will automatically generate vector embeddings
        # for any text inserted to this column.
        "VECTOR_COLUMN_NAME": {
            "type": "vector",
            "service": {
                "provider": "nvidia",
                "model_name": "nvidia/nv-embedqa-e5-v5",
            },
        },
        # If you want to store the original text
        # in addition to the generated embeddings
        # you must create a separate column.
        "TEXT_COLUMN_NAME": {"type": "text"},
    },
    # You should change the primary key definition to meet the needs of your data.
    "primaryKey": {
        "partitionBy": ["TEXT_COLUMN_NAME"],
        "partitionSort": {},
    },
}

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)

Configure OpenAI as the embedding provider

For more detailed instructions, see Integrate OpenAI as an embedding provider.

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.

  • TableDefinition object

  • Fluent interface

  • Dictionary

from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TablePrimaryKeyDescriptor,
    TableScalarColumnTypeDescriptor,
    TableVectorColumnTypeDescriptor,
    TableVectorIndexOptions,
    VectorServiceOptions,
)

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = CreateTableDefinition(
    columns={
        # This column will store vector embeddings.
        # The configured vector service
        # will automatically generate vector embeddings
        # for any text inserted to this column.
        "VECTOR_COLUMN_NAME": TableVectorColumnTypeDescriptor(
            dimension=MODEL_DIMENSIONS,
            service=VectorServiceOptions(
                provider="openai",
                model_name="MODEL_NAME",
                authentication={
                    "providerKey": "API_KEY_NAME",
                },
                parameters={
                    "organizationId": "ORGANIZATION_ID",
                    "projectId": "PROJECT_ID",
                },
            ),
        ),
        # If you want to store the original text
        # in addition to the generated embeddings
        # you must create a separate column.
        "TEXT_COLUMN_NAME": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.TEXT
        ),
    },
    # You should change the primary key definition to meet the needs of your data.
    primary_key=TablePrimaryKeyDescriptor(
        partition_by=["TEXT_COLUMN_NAME"], partition_sort={}
    ),
)

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TableVectorIndexOptions,
    VectorServiceOptions,
)

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = (
    CreateTableDefinition.builder()
    # This column will store vector embeddings.
    # The configured vector service
    # will automatically generate vector embeddings
    # for any text inserted to this column.
    .add_vector_column(
        "VECTOR_COLUMN_NAME",
        dimension=MODEL_DIMENSIONS,
        service=VectorServiceOptions(
            provider="openai",
            model_name="MODEL_NAME",
            authentication={
                "providerKey": "API_KEY_NAME",
            },
            parameters={
                "organizationId": "ORGANIZATION_ID",
                "projectId": "PROJECT_ID",
            },
        ),
    )
    # If you want to store the original text
    # in addition to the generated embeddings
    # you must create a separate column.
    .add_column("TEXT_COLUMN_NAME", ColumnType.TEXT)
    # You should change the primary key definition to meet the needs of your data.
    .add_partition_by(["TEXT_COLUMN_NAME"])
    # Finally, build the table definition.
    .build()
)

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import TableVectorIndexOptions

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = {
    "columns": {
        # This column will store vector embeddings.
        # The configured vector service
        # will automatically generate vector embeddings
        # for any text inserted to this column.
        "VECTOR_COLUMN_NAME": {
            "type": "vector",
            "dimension": MODEL_DIMENSIONS,
            "service": {
                "provider": "openai",
                "model_name": "MODEL_NAME",
                "authentication": {
                    "providerKey": "API_KEY_NAME",
                },
                "parameters": {
                    "organizationId": "ORGANIZATION_ID",
                    "projectId": "PROJECT_ID",
                },
            },
        },
        # If you want to store the original text
        # in addition to the generated embeddings
        # you must create a separate column.
        "TEXT_COLUMN_NAME": {"type": "text"},
    },
    # You should change the primary key definition to meet the needs of your data.
    "primaryKey": {
        "partitionBy": ["TEXT_COLUMN_NAME"],
        "partitionSort": {},
    },
}

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)

Replace the following:

  • TABLE_NAME: The name for your table.

  • VECTOR_COLUMN_NAME: The name for your vector column.

  • TEXT_COLUMN_NAME: The name for the text column that will store the original text. Omit this column if you won’t store the original text in addition to the generated embeddings.

  • API_KEY_NAME: The name of the OpenAI API key that you want to use. Must be the name of an existing OpenAI API key in the Astra Portal. For more information, see Embedding provider authentication.

    Alternatively, you can omit this parameter and instead provide the authentication key in the embedding_api_key parameter when you instantiate a Table object with the commands to create a table or get a table. The client will send the x-embedding-api-key header with the specified key to any underlying HTTP request that requires vectorize authentication. Header authentication overrides the API_KEY_NAME parameter if you set both. If you use the header instead of specifying the API_KEY_NAME parameter, you must include the header in every command that uses vectorize, including writes and vector search. You can use this authentication method only if all affected columns use the same embedding provider.

  • MODEL_NAME: The model that you want to use to generate embeddings. The available models are: text-embedding-3-small, text-embedding-3-large, text-embedding-ada-002.

  • MODEL_DIMENSIONS: The number of dimensions that you want the generated vectors to have. Your chosen embedding model must support the specified number of dimensions.

    If you omit the dimension, Astra DB can use a default dimension value. However, some models don’t have default dimensions. You can use the Data API to find supported embedding providers and their configuration parameters, including dimensions ranges and default dimensions.

  • ORGANIZATION_ID: Optional. The ID of the OpenAI organization that owns the API key. Only required if your OpenAI account belongs to multiple organizations or if you are using a legacy user API key to access projects. For more information about organization IDs, see the OpenAI API reference.

  • PROJECT_ID: Optional. The ID of the OpenAI project that owns the API key. This cannot use the default project. Only required if your OpenAI account belongs to multiple organizations or if you are using a legacy user API key to access projects. For more information about project IDs, see the OpenAI API reference.

Configure Upstage as the embedding provider

For more detailed instructions, see Integrate Upstage as an embedding provider.

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.

  • TableDefinition object

  • Fluent interface

  • Dictionary

from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TablePrimaryKeyDescriptor,
    TableScalarColumnTypeDescriptor,
    TableVectorColumnTypeDescriptor,
    TableVectorIndexOptions,
    VectorServiceOptions,
)

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = CreateTableDefinition(
    columns={
        # This column will store vector embeddings.
        # The configured vector service
        # will automatically generate vector embeddings
        # for any text inserted to this column.
        "VECTOR_COLUMN_NAME": TableVectorColumnTypeDescriptor(
            dimension=MODEL_DIMENSIONS,
            service=VectorServiceOptions(
                provider="upstageAI",
                model_name="MODEL_NAME",
                authentication={
                    "providerKey": "API_KEY_NAME",
                },
            ),
        ),
        # If you want to store the original text
        # in addition to the generated embeddings
        # you must create a separate column.
        "TEXT_COLUMN_NAME": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.TEXT
        ),
    },
    # You should change the primary key definition to meet the needs of your data.
    primary_key=TablePrimaryKeyDescriptor(
        partition_by=["TEXT_COLUMN_NAME"], partition_sort={}
    ),
)

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TableVectorIndexOptions,
    VectorServiceOptions,
)

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = (
    CreateTableDefinition.builder()
    # This column will store vector embeddings.
    # The configured vector service
    # will automatically generate vector embeddings
    # for any text inserted to this column.
    .add_vector_column(
        "VECTOR_COLUMN_NAME",
        dimension=MODEL_DIMENSIONS,
        service=VectorServiceOptions(
            provider="upstageAI",
            model_name="MODEL_NAME",
            authentication={
                "providerKey": "API_KEY_NAME",
            },
        ),
    )
    # If you want to store the original text
    # in addition to the generated embeddings
    # you must create a separate column.
    .add_column("TEXT_COLUMN_NAME", ColumnType.TEXT)
    # You should change the primary key definition to meet the needs of your data.
    .add_partition_by(["TEXT_COLUMN_NAME"])
    # Finally, build the table definition.
    .build()
)

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import TableVectorIndexOptions

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = {
    "columns": {
        # This column will store vector embeddings.
        # The configured vector service
        # will automatically generate vector embeddings
        # for any text inserted to this column.
        "VECTOR_COLUMN_NAME": {
            "type": "vector",
            "dimension": MODEL_DIMENSIONS,
            "service": {
                "provider": "upstageAI",
                "model_name": "MODEL_NAME",
                "authentication": {
                    "providerKey": "API_KEY_NAME",
                },
            },
        },
        # If you want to store the original text
        # in addition to the generated embeddings
        # you must create a separate column.
        "TEXT_COLUMN_NAME": {"type": "text"},
    },
    # You should change the primary key definition to meet the needs of your data.
    "primaryKey": {
        "partitionBy": ["TEXT_COLUMN_NAME"],
        "partitionSort": {},
    },
}

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)

Replace the following:

  • TABLE_NAME: The name for your table.

  • VECTOR_COLUMN_NAME: The name for your vector column.

  • TEXT_COLUMN_NAME: The name for the text column that will store the original text. Omit this column if you won’t store the original text in addition to the generated embeddings.

  • API_KEY_NAME: The name of the Upstage API key that you want to use. Must be the name of an existing Upstage API key in the Astra Portal. For more information, see Embedding provider authentication.

    Alternatively, you can omit this parameter and instead provide the authentication key in the embedding_api_key parameter when you instantiate a Table object with the commands to create a table or get a table. The client will send the x-embedding-api-key header with the specified key to any underlying HTTP request that requires vectorize authentication. Header authentication overrides the API_KEY_NAME parameter if you set both. If you use the header instead of specifying the API_KEY_NAME parameter, you must include the header in every command that uses vectorize, including writes and vector search. You can use this authentication method only if all affected columns use the same embedding provider.

  • MODEL_NAME: The model that you want to use to generate embeddings. The available models are: solar-embedding-1-large.

  • MODEL_DIMENSIONS: The number of dimensions that you want the generated vectors to have. Your chosen embedding model must support the specified number of dimensions.

    If you omit the dimension, Astra DB can use a default dimension value. However, some models don’t have default dimensions. You can use the Data API to find supported embedding providers and their configuration parameters, including dimensions ranges and default dimensions.

Configure Voyage AI as the embedding provider

For more detailed instructions, see Integrate Voyage AI as an embedding provider.

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.

  • TableDefinition object

  • Fluent interface

  • Dictionary

from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TablePrimaryKeyDescriptor,
    TableScalarColumnTypeDescriptor,
    TableVectorColumnTypeDescriptor,
    TableVectorIndexOptions,
    VectorServiceOptions,
)

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = CreateTableDefinition(
    columns={
        # This column will store vector embeddings.
        # The configured vector service
        # will automatically generate vector embeddings
        # for any text inserted to this column.
        "VECTOR_COLUMN_NAME": TableVectorColumnTypeDescriptor(
            dimension=MODEL_DIMENSIONS,
            service=VectorServiceOptions(
                provider="voyageAI",
                model_name="MODEL_NAME",
                authentication={
                    "providerKey": "API_KEY_NAME",
                },
            ),
        ),
        # If you want to store the original text
        # in addition to the generated embeddings
        # you must create a separate column.
        "TEXT_COLUMN_NAME": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.TEXT
        ),
    },
    # You should change the primary key definition to meet the needs of your data.
    primary_key=TablePrimaryKeyDescriptor(
        partition_by=["TEXT_COLUMN_NAME"], partition_sort={}
    ),
)

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import (
    ColumnType,
    CreateTableDefinition,
    TableVectorIndexOptions,
    VectorServiceOptions,
)

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = (
    CreateTableDefinition.builder()
    # This column will store vector embeddings.
    # The configured vector service
    # will automatically generate vector embeddings
    # for any text inserted to this column.
    .add_vector_column(
        "VECTOR_COLUMN_NAME",
        dimension=MODEL_DIMENSIONS,
        service=VectorServiceOptions(
            provider="voyageAI",
            model_name="MODEL_NAME",
            authentication={
                "providerKey": "API_KEY_NAME",
            },
        ),
    )
    # If you want to store the original text
    # in addition to the generated embeddings
    # you must create a separate column.
    .add_column("TEXT_COLUMN_NAME", ColumnType.TEXT)
    # You should change the primary key definition to meet the needs of your data.
    .add_partition_by(["TEXT_COLUMN_NAME"])
    # Finally, build the table definition.
    .build()
)

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import TableVectorIndexOptions

# Instantiate the client
client = DataAPIClient()

# Connect to a database
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = {
    "columns": {
        # This column will store vector embeddings.
        # The configured vector service
        # will automatically generate vector embeddings
        # for any text inserted to this column.
        "VECTOR_COLUMN_NAME": {
            "type": "vector",
            "dimension": MODEL_DIMENSIONS,
            "service": {
                "provider": "voyageAI",
                "model_name": "MODEL_NAME",
                "authentication": {
                    "providerKey": "API_KEY_NAME",
                },
            },
        },
        # If you want to store the original text
        # in addition to the generated embeddings
        # you must create a separate column.
        "TEXT_COLUMN_NAME": {"type": "text"},
    },
    # You should change the primary key definition to meet the needs of your data.
    "primaryKey": {
        "partitionBy": ["TEXT_COLUMN_NAME"],
        "partitionSort": {},
    },
}

# Create the table
table = database.create_table(
    "TABLE_NAME",
    definition=table_definition,
)

Replace the following:

  • TABLE_NAME: The name for your table.

  • VECTOR_COLUMN_NAME: The name for your vector column.

  • TEXT_COLUMN_NAME: The name for the text column that will store the original text. Omit this column if you won’t store the original text in addition to the generated embeddings.

  • API_KEY_NAME: The name of the Voyage AI API key that you want to use. Must be the name of an existing Voyage AI API key in the Astra Portal. For more information, see Embedding provider authentication.

    Alternatively, you can omit this parameter and instead provide the authentication key in the embedding_api_key parameter when you instantiate a Table object with the commands to create a table or get a table. The client will send the x-embedding-api-key header with the specified key to any underlying HTTP request that requires vectorize authentication. Header authentication overrides the API_KEY_NAME parameter if you set both. If you use the header instead of specifying the API_KEY_NAME parameter, you must include the header in every command that uses vectorize, including writes and vector search. You can use this authentication method only if all affected columns use the same embedding provider.

  • MODEL_NAME: The model that you want to use to generate embeddings. The available models are: voyage-2, voyage-code-2, voyage-finance-2, voyage-large-2, voyage-large-2-instruct, voyage-law-2, voyage-multilingual-2.

  • MODEL_DIMENSIONS: The number of dimensions that you want the generated vectors to have. Your chosen embedding model must support the specified number of dimensions.

    If you omit the dimension, Astra DB can use a default dimension value. However, some models don’t have default dimensions. You can use the Data API to find supported embedding providers and their configuration parameters, including dimensions ranges and default dimensions.

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

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

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

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

The 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.info import (
    ColumnType,
    CreateTableDefinition,
    TableKeyValuedColumnType,
    TableKeyValuedColumnTypeDescriptor,
    TablePrimaryKeyDescriptor,
    TableScalarColumnTypeDescriptor,
    TableUDTColumnDescriptor,
    TableValuedColumnType,
    TableValuedColumnTypeDescriptor,
)

# Get an existing database
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

table_definition = CreateTableDefinition(
    # Define all of the columns in the table
    columns={
        "id": TableScalarColumnTypeDescriptor(
            column_type=ColumnType.UUID
        ),
        "group_leader": TableUDTColumnDescriptor(udt_name="person"),
        "group_members": TableValuedColumnTypeDescriptor(
            column_type=TableValuedColumnType.SET,
            value_type=TableUDTColumnDescriptor(
                udt_name="person",
            ),
        ),
        "group_roles": TableKeyValuedColumnTypeDescriptor(
            column_type=TableKeyValuedColumnType.MAP,
            key_type=ColumnType.TEXT,
            value_type=TableUDTColumnDescriptor(
                udt_name="person",
            ),
        ),
    },
    primary_key=TablePrimaryKeyDescriptor(
        partition_by=["id"], 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.info import (
    ColumnType,
    CreateTableDefinition,
    TableUDTColumnDescriptor,
)

# Get an existing database
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

table_definition = (
    CreateTableDefinition.builder()
    # Define all of the columns in the table
    .add_scalar_column("id", ColumnType.UUID)
    .add_userdefinedtype_column("group_leader", udt_name="person")
    .add_set_column(
        "group_members",
        value_type=TableUDTColumnDescriptor(
            udt_name="person",
        ),
    )
    .add_map_column(
        "group_roles",
        key_type=ColumnType.TEXT,
        value_type=TableUDTColumnDescriptor(
            udt_name="person",
        ),
    )
    # Define the primary key for the table.
    .add_partition_by(["id"])
    # 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

# Get an existing database
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Define the columns and primary key for the table
table_definition = {
    "columns": {
        "id": {"type": "uuid"},
        "group_leader": {
            "type": "userDefined",
            "udtName": "person",
        },
        "group_members": {
            "type": "set",
            "valueType": {
                "type": "userDefined",
                "udtName": "person",
            },
        },
        "group_roles": {
            "type": "map",
            "keyType": "text",
            "valueType": {
                "type": "userDefined",
                "udtName": "person",
            },
        },
    },
    "primaryKey": {
        "partitionBy": ["id"],
        "partitionSort": {},
    },
}

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

Create a table and specify the keyspace

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.

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

# Get an existing database
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

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,
    keyspace="KEYSPACE_NAME",
)

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