Create a table (Go)

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.

Parameters

Use the CreateTable method, which belongs to the Db type.

Method signature 
func (d *Db) CreateTable(
  ctx context.Context,
  name string,
  definition table.Definition,
  opts ...options.CreateTableOption
) (*Table, error)
Name Type Summary

ctx

context.Context

The context for the operation.

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

table.Definition

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.

opts

…​options.CreateTableOption

Optional. The options for this method.

See Methods of the CreateTableOption builder for more details.
Methods of the CreateTableOption builder
Method Summary

SetIfNotExists(v 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

SetKeyspace(v string)

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

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

UpdateAPIOptions(v …​APIOption)

Optional. General API options for this operation, including the timeout.

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

package main

import (
	"context"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/table"
)

func main() {
	ctx := context.Background()

	// Get an existing database
	client := astra.NewClient(
		options.API().SetEnvironment(options.EnvironmentHCD),
	)

	database := client.Database(
		"API_ENDPOINT",
		options.API().
			SetUsernamePasswordTokenProvider(
				"USERNAME",
				"PASSWORD",
			).
			SetKeyspace("KEYSPACE_NAME"),
	)

	// Define the columns and primary key for the table
	definition := table.Definition{
		Columns: table.Columns{
			{Name: "title", Column: table.Text()},
			{Name: "number_of_pages", Column: table.Int()},
			{Name: "rating", Column: table.Float()},
			{Name: "genres", Column: table.Set(table.Text())},
			{Name: "metadata", Column: table.Map("text", table.Text())},
			{Name: "is_checked_out", Column: table.Boolean()},
			{Name: "due_date", Column: table.Date()},
		},
		PrimaryKey: table.PrimaryKey{
			PartitionBy: []string{"title"},
		},
	}

	// Create the table
	_, err := database.CreateTable(
		ctx,
		"TABLE_NAME",
		definition,
	)
	if err != nil {
		log.Fatal(err)
	}
}

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

package main

import (
	"context"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/table"
)

func main() {
	ctx := context.Background()

	// Get an existing database
	client := astra.NewClient(
		options.API().SetEnvironment(options.EnvironmentHCD),
	)

	database := client.Database(
		"API_ENDPOINT",
		options.API().
			SetUsernamePasswordTokenProvider(
				"USERNAME",
				"PASSWORD",
			).
			SetKeyspace("KEYSPACE_NAME"),
	)

	// Define the columns and primary key for the table
	definition := table.Definition{
		Columns: table.Columns{
			{Name: "title", Column: table.Text()},
			{Name: "number_of_pages", Column: table.Int()},
			{Name: "rating", Column: table.Float()},
			{Name: "genres", Column: table.Set(table.Text())},
			{Name: "metadata", Column: table.Map("text", table.Text())},
			{Name: "is_checked_out", Column: table.Boolean()},
			{Name: "due_date", Column: table.Date()},
		},
		PrimaryKey: table.PrimaryKey{
			PartitionBy: []string{"title", "author"},
		},
	}

	// Create the table
	_, err := database.CreateTable(
		ctx,
		"TABLE_NAME",
		definition,
	)
	if err != nil {
		log.Fatal(err)
	}
}

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

package main

import (
	"context"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/table"
)

func main() {
	ctx := context.Background()

	// Get an existing database
	client := astra.NewClient(
		options.API().SetEnvironment(options.EnvironmentHCD),
	)

	database := client.Database(
		"API_ENDPOINT",
		options.API().
			SetUsernamePasswordTokenProvider(
				"USERNAME",
				"PASSWORD",
			).
			SetKeyspace("KEYSPACE_NAME"),
	)

	// Define the columns and primary key for the table
	definition := table.Definition{
		Columns: table.Columns{
			{Name: "title", Column: table.Text()},
			{Name: "number_of_pages", Column: table.Int()},
			{Name: "rating", Column: table.Float()},
			{Name: "genres", Column: table.Set(table.Text())},
			{Name: "metadata", Column: table.Map("text", table.Text())},
			{Name: "is_checked_out", Column: table.Boolean()},
			{Name: "due_date", Column: table.Date()},
		},
		PrimaryKey: table.PrimaryKey{
			PartitionBy: []string{"title", "rating"},
			PartitionSort: table.PartitionSort{
				{Name: "number_of_pages", Order: table.SortAscending},
				{Name: "is_checked_out", Order: table.SortDescending},
			},
		},
	}

	// Create the table
	_, err := database.CreateTable(
		ctx,
		"TABLE_NAME",
		definition,
	)
	if err != nil {
		log.Fatal(err)
	}
}

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.

package main

import (
	"context"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/table"
)

func main() {
	ctx := context.Background()

	// Get an existing database
	client := astra.NewClient(
		options.API().SetEnvironment(options.EnvironmentHCD),
	)

	database := client.Database(
		"API_ENDPOINT",
		options.API().
			SetUsernamePasswordTokenProvider(
				"USERNAME",
				"PASSWORD",
			).
			SetKeyspace("KEYSPACE_NAME"),
	)

	// Define the columns and primary key for the table
	definition := table.Definition{
		Columns: table.Columns{
			{Name: "example_vector", Column: table.Vector(1024)},
			{Name: "example_non_vector", Column: table.Text()},
		},
		PrimaryKey: table.PrimaryKey{
			PartitionBy: []string{"example_non_vector"},
		},
	}

	// Create the table
	_, err := database.CreateTable(
		ctx,
		"TABLE_NAME",
		definition,
	)
	if err != nil {
		log.Fatal(err)
	}
}

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.

package main

import (
	"context"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/table"
)

func main() {
	ctx := context.Background()

	// Get an existing database
	client := astra.NewClient(
		options.API().SetEnvironment(options.EnvironmentHCD),
	)

	database := client.Database(
		"API_ENDPOINT",
		options.API().
			SetUsernamePasswordTokenProvider(
				"USERNAME",
				"PASSWORD",
			).
			SetKeyspace("KEYSPACE_NAME"),
	)

	// Define the columns and primary key for the table
	definition := table.Definition{
		Columns: table.Columns{
			{Name: "id", Column: table.UUID()},
			{Name: "group_leader", Column: table.UDT("person")},
			{
				Name:   "group_members",
				Column: table.Set(table.UDT("person")),
			},
			{
				Name:   "group_roles",
				Column: table.Map("text", table.UDT("person")),
			},
		},
		PrimaryKey: table.PrimaryKey{
			PartitionBy: []string{"id"},
		},
	}

	// Create the table
	_, err := database.CreateTable(
		ctx,
		"TABLE_NAME",
		definition,
	)
	if err != nil {
		log.Fatal(err)
	}
}

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