Create a table (Java)

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<T> object. You can use this object to work with rows in the table.

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

Parameters

Use the createTable method, which belongs to the com.datastax.astra.client.databases.Database class.

Method signature

<T> Table<T> createTable(
  String tableName,
  TableDefinition tableDefinition,
  Class<T> rowClass,
  CreateTableOptions createTableOptions
)

<T> Table<T> createTable(
  String tableName,
  TableDefinition tableDefinition,
  Class<T> rowClass
)

<T> Table<T> createTable(Class<T> rowClass)

<T> Table<T> createTable(
  Class<T> rowClass,
  CreateTableOptions createTableOptions
)

<T> Table<T> createTable(
  String tableName,
  Class<T> rowClass,
  CreateTableOptions createTableOptions
)

Table<Row> createTable(
  String tableName,
  TableDefinition tableDefinition,
  CreateTableOptions options
)

Table<Row> createTable(
  String tableName,
  TableDefinition tableDefinition
)

Name Type Summary

Name	Type	Summary
`name`	`String`	The name of the table. Table names must follow these rules: Can contain letters, numbers, and underscores Cannot exceed 48 characters Must be unique within the keyspace
`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.
`rowClass`	`Class<?>`	Optional. A specification of the class of the table’s row object. Default: `Row`, which is close to a `Map` object
`createTableOptions`	`CreateTableOptions`	Optional. The options for this operation. See Selected methods of `CreateTableOptions` for more details.

name

String

The name of the table.

Table names must follow these rules:

Can contain letters, numbers, and underscores
Cannot exceed 48 characters
Must be unique within the keyspace

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.

rowClass

Class<?>

Optional. A specification of the class of the table’s row object.

Default: Row, which is close to a Map object

createTableOptions

CreateTableOptions

Optional. The options for this operation. See Selected methods of CreateTableOptions for more details.

Selected methods of `CreateTableOptions`
Method	Parameters	Summary
`ifNotExists()`	`boolean`	Optional. Whether the command should silently succeed even if a table with the given name already exists in the keyspace and no new table was created. This option only checks table names. It does not check table schemas. Default: false
`timeout()`	`long` \| `Duration`	Optional. A timeout, in milliseconds, for the underlying HTTP request. If not provided, the `Database` setting is used.

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

The Java client supports multiple ways to create a table. In all cases, you must define the table schema.

Use a generic type
Define the row type

If you don’t specify the Class parameter when creating an instance of the generic class Table, the client defaults Table as the type. In this case, the working object type T is Row.class.

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.TableDefinition;
import com.datastax.astra.client.tables.definition.columns.TableColumnTypes;
import com.datastax.astra.client.tables.definition.rows.Row;

public class Example {
  public static void main(String[] args) {
    // Get an existing database
    Database database =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME");

    TableDefinition tableDefinition =
        new TableDefinition()
            // Define all of the columns in the table
            .addColumnText("title")
            .addColumnInt("number_of_pages")
            .addColumn("rating", TableColumnTypes.FLOAT)
            .addColumnSet("genres", TableColumnTypes.TEXT)
            .addColumnMap("metadata", TableColumnTypes.TEXT, TableColumnTypes.TEXT)
            .addColumnBoolean("is_checked_out")
            .addColumn("due_date", TableColumnTypes.DATE)
            // Define the primary key for the table.
            // In this case, the table uses a single-column primary key.
            .addPartitionBy("title");

    Table<Row> table = database.createTable("example_table", tableDefinition);
  }
}

Instead of using the default type Row.class, you can define your own working object, which will be serialized as a Row.

This working object can be annotated when the field names do not exactly match the column names or when you want to fully describe your table to enable its creation solely from the entity definition.

The following example defines a Book class and then uses it to create the table.

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.columns.TableColumnTypes;
import com.datastax.astra.client.tables.mapping.Column;
import com.datastax.astra.client.tables.mapping.EntityTable;
import com.datastax.astra.client.tables.mapping.PartitionBy;
import java.util.Date;
import java.util.Map;
import java.util.Set;
import lombok.Data;

public class Example {
  @EntityTable("example_table")
  @Data
  public class Book {
    @PartitionBy(0)
    @Column(name = "title", type = TableColumnTypes.TEXT)
    private String title;

    @Column(name = "number_of_pages", type = TableColumnTypes.INT)
    private Integer number_of_pages;

    @Column(name = "rating", type = TableColumnTypes.FLOAT)
    private Float rating;

    @Column(name = "genres", type = TableColumnTypes.SET, valueType = TableColumnTypes.TEXT)
    private Set<String> genres;

    @Column(
        name = "metadata",
        type = TableColumnTypes.MAP,
        keyType = TableColumnTypes.TEXT,
        valueType = TableColumnTypes.TEXT)
    private Map<String, String> metadata;

    @Column(name = "is_checked_out", type = TableColumnTypes.BOOLEAN)
    private Boolean is_checked_out;

    @Column(name = "due_date", type = TableColumnTypes.DATE)
    private Date due_date;
  }

  public static void main(String[] args) {
    // Get an existing database
    Database database =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME");

    Table<Book> table = database.createTable(Book.class);
  }
}

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

The Java client supports multiple ways to create a table. In all cases, you must define the table schema.

Use a generic type
Define the row type

If you don’t specify the Class parameter when creating an instance of the generic class Table, the client defaults Table as the type. In this case, the working object type T is Row.class.

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.TableDefinition;
import com.datastax.astra.client.tables.definition.columns.TableColumnTypes;
import com.datastax.astra.client.tables.definition.rows.Row;

public class Example {
  public static void main(String[] args) {
    // Get an existing database
    Database database =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME");

    TableDefinition tableDefinition =
        new TableDefinition()
            // Define all of the columns in the table
            .addColumnText("title")
            .addColumnInt("number_of_pages")
            .addColumn("rating", TableColumnTypes.FLOAT)
            .addColumnSet("genres", TableColumnTypes.TEXT)
            .addColumnMap("metadata", TableColumnTypes.TEXT, TableColumnTypes.TEXT)
            .addColumnBoolean("is_checked_out")
            .addColumn("due_date", TableColumnTypes.DATE)
            // Define the primary key for the table.
            // In this case, the table uses a composite primary key.
            .addPartitionBy("title")
            .addPartitionBy("rating");

    Table<Row> table = database.createTable("example_table", tableDefinition);
  }
}

Instead of using the default type Row.class, you can define your own working object, which will be serialized as a Row.

This working object can be annotated when the field names do not exactly match the column names or when you want to fully describe your table to enable its creation solely from the entity definition.

The following example defines a Book class and then uses it to create the table.

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.columns.TableColumnTypes;
import com.datastax.astra.client.tables.mapping.Column;
import com.datastax.astra.client.tables.mapping.EntityTable;
import com.datastax.astra.client.tables.mapping.PartitionBy;
import java.util.Date;
import java.util.Map;
import java.util.Set;
import lombok.Data;

public class Example {
  @EntityTable("example_table")
  @Data
  public class Book {
    @PartitionBy(0)
    @Column(name = "title", type = TableColumnTypes.TEXT)
    private String title;

    @Column(name = "number_of_pages", type = TableColumnTypes.INT)
    private Integer number_of_pages;

    @PartitionBy(1)
    @Column(name = "rating", type = TableColumnTypes.FLOAT)
    private Float rating;

    @Column(name = "genres", type = TableColumnTypes.SET, valueType = TableColumnTypes.TEXT)
    private Set<String> genres;

    @Column(
        name = "metadata",
        type = TableColumnTypes.MAP,
        keyType = TableColumnTypes.TEXT,
        valueType = TableColumnTypes.TEXT)
    private Map<String, String> metadata;

    @Column(name = "is_checked_out", type = TableColumnTypes.BOOLEAN)
    private Boolean is_checked_out;

    @Column(name = "due_date", type = TableColumnTypes.DATE)
    private Date due_date;
  }

  public static void main(String[] args) {
    // Get an existing database
    Database database =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME");

    Table<Book> table = database.createTable(Book.class);
  }
}

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

The Java client supports multiple ways to create a table. In all cases, you must define the table schema.

Use a generic type
Define the row type

If you don’t specify the Class parameter when creating an instance of the generic class Table, the client defaults Table as the type. In this case, the working object type T is Row.class.

import static com.datastax.astra.client.core.query.Sort.ascending;
import static com.datastax.astra.client.core.query.Sort.descending;

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.TableDefinition;
import com.datastax.astra.client.tables.definition.columns.TableColumnTypes;
import com.datastax.astra.client.tables.definition.rows.Row;

public class Example {
  public static void main(String[] args) {
    // Get an existing database
    Database database =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME");

    TableDefinition tableDefinition =
        new TableDefinition()
            // Define all of the columns in the table
            .addColumnText("title")
            .addColumnInt("number_of_pages")
            .addColumn("rating", TableColumnTypes.FLOAT)
            .addColumnSet("genres", TableColumnTypes.TEXT)
            .addColumnMap("metadata", TableColumnTypes.TEXT, TableColumnTypes.TEXT)
            .addColumnBoolean("is_checked_out")
            .addColumn("due_date", TableColumnTypes.DATE)
            // Define the primary key for the table.
            // In this case, the table uses a compound primary key.
            .addPartitionBy("title")
            .addPartitionBy("rating")
            .addPartitionSort(ascending("number_of_pages"))
            .addPartitionSort(descending("is_checked_out"));

    Table<Row> table = database.createTable("example_table", tableDefinition);
  }
}

Instead of using the default type Row.class, you can define your own working object, which will be serialized as a Row.

This working object can be annotated when the field names do not exactly match the column names or when you want to fully describe your table to enable its creation solely from the entity definition.

The following example defines a Book class and then uses it to create the table.

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.core.query.SortOrder;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.columns.TableColumnTypes;
import com.datastax.astra.client.tables.mapping.Column;
import com.datastax.astra.client.tables.mapping.EntityTable;
import com.datastax.astra.client.tables.mapping.PartitionBy;
import com.datastax.astra.client.tables.mapping.PartitionSort;
import java.util.Date;
import java.util.Map;
import java.util.Set;
import lombok.Data;

public class Example {
  @EntityTable("example_table")
  @Data
  public class Book {
    @PartitionBy(0)
    @Column(name = "title", type = TableColumnTypes.TEXT)
    private String title;

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

    @PartitionBy(1)
    @Column(name = "rating", type = TableColumnTypes.FLOAT)
    private Float rating;

    @Column(name = "genres", type = TableColumnTypes.SET, valueType = TableColumnTypes.TEXT)
    private Set<String> genres;

    @Column(
        name = "metadata",
        type = TableColumnTypes.MAP,
        keyType = TableColumnTypes.TEXT,
        valueType = TableColumnTypes.TEXT)
    private Map<String, String> metadata;

    @PartitionSort(position = 1, order = SortOrder.DESCENDING)
    @Column(name = "is_checked_out", type = TableColumnTypes.BOOLEAN)
    private Boolean is_checked_out;

    @Column(name = "due_date", type = TableColumnTypes.DATE)
    private Date due_date;
  }

  public static void main(String[] args) {
    // Get an existing database
    Database database =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME");

    Table<Book> table = database.createTable(Book.class);
  }
}

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 Java client supports multiple ways to create a table. In all cases, you must define the table schema.

Use a generic type
Define the row type

If you don’t specify the Class parameter when creating an instance of the generic class Table, the client defaults Table as the type. In this case, the working object type T is Row.class.

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.TableDefinition;
import com.datastax.astra.client.tables.definition.columns.TableColumnDefinitionVector;
import com.datastax.astra.client.tables.definition.rows.Row;

public class Example {
  public static void main(String[] args) {
    // Get an existing database
    Database database =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME");

    TableDefinition tableDefinition =
        new TableDefinition()
            // Define all of the columns in the table
            .addColumnVector("example_vector", new TableColumnDefinitionVector().dimension(1024))
            .addColumnText("example_non_vector")
            // Define the primary key for the table.
            // In this case, the table uses a single-column primary key.
            .addPartitionBy("example_non_vector");

    Table<Row> table = database.createTable("example_table", tableDefinition);
  }
}

Instead of using the default type Row.class, you can define your own working object, which will be serialized as a Row.

This working object can be annotated when the field names do not exactly match the column names or when you want to fully describe your table to enable its creation solely from the entity definition.

The following example defines a Book class and then uses it to create the table.

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.core.vector.DataAPIVector;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.columns.TableColumnTypes;
import com.datastax.astra.client.tables.mapping.Column;
import com.datastax.astra.client.tables.mapping.ColumnVector;
import com.datastax.astra.client.tables.mapping.EntityTable;
import com.datastax.astra.client.tables.mapping.PartitionBy;
import lombok.Data;

public class Example {
  @EntityTable("example_table")
  @Data
  public class Book {
    @ColumnVector(name = "example_vector", dimension = 1024)
    private DataAPIVector vector;

    @PartitionBy(0)
    @Column(name = "example_non_vector", type = TableColumnTypes.TEXT)
    private String exampleNonVector;
  }

  public static void main(String[] args) {
    // Get an existing database
    Database database =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME");

    Table<Book> table = database.createTable(Book.class);
  }
}

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 Java client supports multiple ways to create a table. In all cases, you must define the table schema.

Use a generic type
Define the row type

If you don’t specify the Class parameter when creating an instance of the generic class Table, the client defaults Table as the type. In this case, the working object type T is Row.class.

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.TableDefinition;
import com.datastax.astra.client.tables.definition.columns.TableColumnTypes;
import com.datastax.astra.client.tables.definition.rows.Row;

public class Example {
  public static void main(String[] args) {
    // Get an existing database
    Database database =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME");

    TableDefinition tableDefinition =
        new TableDefinition()
            // Define all of the columns in the table
            .addColumnUuid("id")
            .addColumnUserDefinedType("group_leader", "person")
            .addColumnSetUserDefinedType("group_members", "person")
            .addColumnMapUserDefinedType("group_roles", "person", TableColumnTypes.TEXT)
            // Define the primary key for the table.
            .addPartitionBy("id");
    Table<Row> table = database.createTable("example_table", tableDefinition);
  }
}

Instead of using the default type Row.class, you can define your own working object, which will be serialized as a Row.

This working object can be annotated when the field names do not exactly match the column names or when you want to fully describe your table to enable its creation solely from the entity definition.

The following example defines a Book class and then uses it to create the table.

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.columns.TableColumnTypes;
import com.datastax.astra.client.tables.definition.types.TableUserDefinedType;
import com.datastax.astra.client.tables.mapping.Column;
import com.datastax.astra.client.tables.mapping.EntityTable;
import com.datastax.astra.client.tables.mapping.PartitionBy;
import java.util.Map;
import java.util.Set;
import java.util.UUID;
import lombok.Data;

public class Example {
  // Define the user-defined type "person"
  @TableUserDefinedType("person")
  public class Person {
    @Column(name = "user_name", type = TableColumnTypes.TEXT)
    private String userName;

    @Column(name = "age", type = TableColumnTypes.INT)
    private Integer age;
  }

  // Define the table
  @EntityTable("example_table")
  @Data
  class Group {
    @PartitionBy(0)
    @Column(name = "id", type = TableColumnTypes.UUID)
    private UUID id;

    @Column(name = "group_leader", type = TableColumnTypes.USERDEFINED, udtName = "person")
    private Person groupLeader;

    @Column(
        name = "group_members",
        type = TableColumnTypes.SET,
        valueType = TableColumnTypes.USERDEFINED,
        udtName = "person")
    private Set<Person> groupMembers;

    @Column(
        name = "group_roles",
        type = TableColumnTypes.MAP,
        keyType = TableColumnTypes.TEXT,
        valueType = TableColumnTypes.USERDEFINED,
        udtName = "person")
    private Map<String, Person> groupRoles;
  }

  public static void main(String[] args) {
    Database database =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME");

    Table<Group> table = database.createTable(Group.class);
  }
}

Client reference

For more information, see the client reference.

Create a table (Java)

Result

Parameters

Examples

Create a table with a single-column primary key

Create a table with a composite primary key

Create a table with a compound primary key

Create a table with a column to store vector embeddings

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

Client reference

Was this helpful?

Give Feedback