Create a table (C#)

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.

By default, the Table object is typed as Table<Row>, where Row is Dictionary<string, object>. You can enable stronger typing by specifying a type when you create the table. For more information and examples, see Custom typing for tables.

Parameters

Use the CreateTableAsync method, which belongs to the Database class. You can also use CreateTable, which is the synchronous version of the method.

Method signature 
public Task<Table<TRow>> CreateTableAsync<TRow>(
  TableDefinition definition, CreateTableOptions options = null
) where TRow : class, new();
public Task<Table<TRow>> CreateTableAsync<TRow>(
  string tableName,
  TableDefinition definition,
  CreateTableOptions options = null
) where TRow : class;
public Task<Table<TRow>> CreateTableAsync<TRow>(
  string tableName, CreateTableOptions options = null
) where TRow : class, new();
public Task<Table<Row>> CreateTableAsync(
  string tableName,
  TableDefinition definition,
  CreateTableOptions options = null
);
public Task<Table<TRow>> CreateTableAsync<TRow>(
  CreateTableOptions options = null
) where TRow : class, new();
Name Type Summary

tableName

string

The name of the table.

Table names must follow these rules:

  • Can contain letters, numbers, and underscores

  • Cannot exceed 48 characters

  • Must be unique within the keyspace

If not specified, the client attempts to extract it from the TableName attribute on the custom row class if one is used. For more information and examples, see Custom typing for tables.

definition

TableDefinition

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.

options

CreateTableOptions

Optional. Options for this operation. Keyspace is required unless you specified a working keyspace when instantiating the Database object. For more information and examples for general options such as timeout and keyspace, see Customize API interaction.

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 (C#).

  • Typed tables

  • Untyped tables

You can manually define a client-side type for your table to help statically catch errors. For more information and examples, see Custom typing for tables.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

// Define the type for the row
[TableName("TABLE_NAME")]
public class Book
{
  [ColumnPrimaryKey]
  [ColumnName("title")]
  public string Title { get; set; } = null!;

  [ColumnName("number_of_pages")]
  public int? NumberOfPages { get; set; }

  [ColumnName("rating")]
  public float? Rating { get; set; }

  [ColumnName("genres")]
  public string[]? Genres { get; set; }

  [ColumnName("metadata")]
  public Dictionary<string, string>? Metadata { get; set; }

  [ColumnName("is_checked_out")]
  public bool? IsCheckedOut { get; set; }

  [ColumnName("due_date")]
  public DateOnly? DueDate { get; set; }
}

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    // Connect to a database
    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    // Create a table
    var table = await database.CreateTableAsync<Book>();
  }
}

If you don’t pass a type parameter, the collection or table remains untyped. This is a more flexible but less type-safe option.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Tables;
using DataStax.AstraDB.DataApi.Utils;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    // Connect to a database
    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    // Create a table
    var definition = new TableDefinition()
      .AddColumn("title", DataAPIType.Text())
      .AddColumn("number_of_pages", DataAPIType.Int())
      .AddColumn("rating", DataAPIType.Float())
      .AddColumn("genres", DataAPIType.Set(DataAPIType.Text()))
      .AddColumn(
        "metadata",
        DataAPIType.Map(DataAPIType.Text(), DataAPIType.Text())
      )
      .AddColumn("is_checked_out", DataAPIType.Boolean())
      .AddColumn("due_date", DataAPIType.Date())
      // Define the primary key for the table.
      // In this case, the table uses a single-column primary key.
      .AddSinglePrimaryKey("title");

    var table = await database.CreateTableAsync(
      "TABLE_NAME",
      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 (C#).

  • Typed tables

  • Untyped tables

You can manually define a client-side type for your table to help statically catch errors. For more information and examples, see Custom typing for tables.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

// Define the type for the row
[TableName("TABLE_NAME")]
public class Book
{
  [ColumnPrimaryKey(1)]
  [ColumnName("title")]
  public string Title { get; set; } = null!;

  [ColumnName("number_of_pages")]
  public int? NumberOfPages { get; set; }

  [ColumnPrimaryKey(2)]
  [ColumnName("rating")]
  public float Rating { get; set; }

  [ColumnName("genres")]
  public string[]? Genres { get; set; }

  [ColumnName("metadata")]
  public Dictionary<string, string>? Metadata { get; set; }

  [ColumnName("is_checked_out")]
  public bool? IsCheckedOut { get; set; }

  [ColumnName("due_date")]
  public DateOnly? DueDate { get; set; }
}

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    // Connect to a database
    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    // Create a table
    var table = await database.CreateTableAsync<Book>();
  }
}

If you don’t pass a type parameter, the collection or table remains untyped. This is a more flexible but less type-safe option.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Tables;
using DataStax.AstraDB.DataApi.Utils;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    // Connect to a database
    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    // Create a table
    var definition = new TableDefinition()
      .AddColumn("title", DataAPIType.Text())
      .AddColumn("number_of_pages", DataAPIType.Int())
      .AddColumn("rating", DataAPIType.Float())
      .AddColumn("genres", DataAPIType.Set(DataAPIType.Text()))
      .AddColumn(
        "metadata",
        DataAPIType.Map(DataAPIType.Text(), DataAPIType.Text())
      )
      .AddColumn("is_checked_out", DataAPIType.Boolean())
      .AddColumn("due_date", DataAPIType.Date())
      // Define the primary key for the table.
      // In this case, the table uses a composite primary key.
      .AddCompositePrimaryKey(new[] { "title", "rating" });

    var table = await database.CreateTableAsync(
      "TABLE_NAME",
      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 (C#).

  • Typed tables

  • Untyped tables

You can manually define a client-side type for your table to help statically catch errors. For more information and examples, see Custom typing for tables.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

// Define the type for the row
[TableName("TABLE_NAME")]
public class Book
{
  [ColumnPrimaryKey(1)]
  [ColumnName("title")]
  public string Title { get; set; } = null!;

  [ColumnPrimaryKeySort(1, SortDirection.Ascending)]
  [ColumnName("number_of_pages")]
  public int NumberOfPages { get; set; }

  [ColumnPrimaryKey(2)]
  [ColumnName("rating")]
  public float Rating { get; set; }

  [ColumnName("genres")]
  public string[]? Genres { get; set; }

  [ColumnName("metadata")]
  public Dictionary<string, string>? Metadata { get; set; }

  [ColumnPrimaryKeySort(2, SortDirection.Descending)]
  [ColumnName("is_checked_out")]
  public bool IsCheckedOut { get; set; }

  [ColumnName("due_date")]
  public DateOnly? DueDate { get; set; }
}

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    // Connect to a database
    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    // Create a table
    var table = await database.CreateTableAsync<Book>();
  }
}

If you don’t pass a type parameter, the collection or table remains untyped. This is a more flexible but less type-safe option.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Tables;
using DataStax.AstraDB.DataApi.Utils;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    // Connect to a database
    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    // Create a table
    var definition = new TableDefinition()
      .AddColumn("title", DataAPIType.Text())
      .AddColumn("number_of_pages", DataAPIType.Int())
      .AddColumn("rating", DataAPIType.Float())
      .AddColumn("genres", DataAPIType.Set(DataAPIType.Text()))
      .AddColumn(
        "metadata",
        DataAPIType.Map(DataAPIType.Text(), DataAPIType.Text())
      )
      .AddColumn("is_checked_out", DataAPIType.Boolean())
      .AddColumn("due_date", DataAPIType.Date())
      // Define the primary key for the table.
      // In this case, the table uses a compound primary key.
      .AddCompoundPrimaryKey(
        new[] { "title", "rating" },
        new[]
        {
          new PrimaryKeySort("number_of_pages", SortDirection.Ascending),
          new PrimaryKeySort("is_checked_out", SortDirection.Descending),
        }
      );

    var table = await database.CreateTableAsync(
      "TABLE_NAME",
      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.

  • Typed tables

  • Untyped tables

You can manually define a client-side type for your table to help statically catch errors. For more information and examples, see Custom typing for tables.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

// Define the type for the row
[TableName("TABLE_NAME")]
public class ExampleRow
{
  [ColumnPrimaryKey]
  [ColumnName("example_non_vector")]
  public string ExampleNonVector { get; set; } = null!;

  [ColumnVector(1024)]
  [ColumnName("example_vector")]
  public float[]? ExampleVector { get; set; }
}

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    // Connect to a database
    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    // Create a table
    var table = await database.CreateTableAsync<ExampleRow>();
  }
}

If you don’t pass a type parameter, the collection or table remains untyped. This is a more flexible but less type-safe option.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Tables;
using DataStax.AstraDB.DataApi.Utils;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    // Connect to a database
    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    // Create a table
    var definition = new TableDefinition()
      .AddColumn("example_vector", DataAPIType.Vector(1024))
      .AddColumn("example_non_vector", DataAPIType.Text())
      // Define the primary key for the table.
      // In this case, the table uses a single-column primary key.
      .AddSinglePrimaryKey("example_non_vector");

    var table = await database.CreateTableAsync(
      "TABLE_NAME",
      definition
    );
  }
}

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.

  • Typed tables

  • Untyped tables

You can manually define a client-side type for your table to help statically catch errors. For more information and examples, see Custom typing for tables.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

// Define the user-defined type
// The type will be created if a type
// with the same name does not already exist
[UserDefinedType("person")]
public class Person
{
  [ColumnName("name")]
  public string? Name { get; set; }

  [ColumnName("level")]
  public int? Level { get; set; }
};

// Define the type for the row
[TableName("TABLE_NAME")]
public class ExampleRow
{
  [ColumnPrimaryKey]
  [ColumnName("id")]
  public Guid Id { get; set; }

  [ColumnName("group_leader")]
  public Person? GroupLeader { get; set; }

  [ColumnName("group_members")]
  public Person[]? GroupMembers { get; set; }

  [ColumnName("group_roles")]
  public Dictionary<string, Person>? GroupRoles { get; set; }
}

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    // Connect to a database
    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    // Create a table
    var table = await database.CreateTableAsync<ExampleRow>();
  }
}

If you don’t pass a type parameter, the collection or table remains untyped. This is a more flexible but less type-safe option.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Tables;
using DataStax.AstraDB.DataApi.Utils;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Instantiate the client
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    // Connect to a database
    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      ),
      "KEYSPACE_NAME"
    );

    // Create a table
    var definition = new TableDefinition()
      .AddColumn("id", DataAPIType.Uuid())
      .AddColumn("group_leader", DataAPIType.UserDefined("person"))
      .AddColumn(
        "group_members",
        DataAPIType.Set(DataAPIType.UserDefined("person"))
      )
      .AddColumn(
        "group_roles",
        DataAPIType.Map(
          DataAPIType.Text(),
          DataAPIType.UserDefined("person")
        )
      )
      .AddSinglePrimaryKey("id");

    var table = await database.CreateTableAsync(
      "TABLE_NAME",
      definition
    );
  }
}

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