package table

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

Package table provides types and utilities for working with Astra DB tables.

Index

Constants

const (
	SortAscending  = 1
	SortDescending = -1
)

Sort order constants 

const (
	TypeText      = "text"
	TypeInt       = "int"
	TypeBigInt    = "bigint"
	TypeSmallInt  = "smallint"
	TypeTinyInt   = "tinyint"
	TypeFloat     = "float"
	TypeDouble    = "double"
	TypeDecimal   = "decimal"
	TypeBoolean   = "boolean"
	TypeDate      = "date"
	TypeTime      = "time"
	TypeTimestamp = "timestamp"
	TypeUUID      = "uuid"
	TypeTimeUUID  = "timeuuid"
	TypeBlob      = "blob"
	TypeVarint    = "varint"
	TypeInet      = "inet"
	TypeAscii     = "ascii"
	TypeVector    = "vector"
	TypeSet       = "set"
	TypeList      = "list"
	TypeMap       = "map"
	TypeUDT       = "userDefined"
	TypeDuration  = "duration"
)

Column type constants

Types

type AddColumns

type AddColumns struct {
	Columns Columns `json:"columns"`
}

AddColumns is the payload for the alterTable "add" operation.

func (AddColumns) MarshalAstraRaw
func (a AddColumns) MarshalAstraRaw(ctx serdes.EncodeCtx, dst []byte) ([]byte, error)

type AddReranking

type AddReranking struct {
	Service RerankService `json:"service"`
}

AddReranking is the payload for the alterTable "addReranking" operation.

func (AddReranking) MarshalAstraRaw
func (r AddReranking) MarshalAstraRaw(ctx serdes.EncodeCtx, dst []byte) ([]byte, error)

type AddTypeFields

type AddTypeFields struct {
	Fields Columns `json:"fields"`
}

AddTypeFields is the payload for the alterType "add" operation.

func (AddTypeFields) MarshalAstraRaw
func (a AddTypeFields) MarshalAstraRaw(ctx serdes.EncodeCtx, dst []byte) ([]byte, error)

type AddVectorize

type AddVectorize struct {
	Columns map[string]VectorService `json:"columns"`
}

AddVectorize is the payload for the alterTable "addVectorize" operation.

func (AddVectorize) MarshalAstraRaw
func (v AddVectorize) MarshalAstraRaw(ctx serdes.EncodeCtx, dst []byte) ([]byte, error)

type AlterOperation

type AlterOperation interface {
	serdes.AstraRawMarshaler
	// contains filtered or unexported methods
}

AlterOperation represents a single operation to perform on a table via table.Alter.

Implementations include:

Example — Add columns: 

tbl.Alter(ctx, table.AddColumns{
   Columns: table.Columns{
      "is_summer_reading": table.Boolean(),
      "library_branch":    table.Text(),
   },
})

Example — Drop columns: 

tbl.Alter(ctx, table.DropColumns{
   Columns: []string{"is_summer_reading", "library_branch"},
})

type AlterTypeOperation

type AlterTypeOperation interface {
	serdes.AstraRawMarshaler
	// contains filtered or unexported methods
}

AlterTypeOperation represents an operation to alter a user-defined type (UDT).

type Column

type Column struct {
	// Type is the column type (text, int, float, boolean, uuid, date, vector, set, list, map, userDefined, etc.)
	Type string `json:"type"`

	// Dimension is used for vector columns to specify the vector dimension
	Dimension *int `json:"dimension,omitempty"`

	// Service is used for vector columns with vectorize embedding provider integration
	Service *VectorService `json:"service,omitempty"`

	// KeyType is used for map columns
	KeyType *string `json:"keyType,omitempty"`

	// ValueType is used for set, list, and map columns
	ValueType *Column `json:"valueType,omitempty"`

	// UDTName is used for userDefined columns to specify the UDT name
	UDTName *string `json:"udtName,omitempty"`

	// UDTDefinition is the definition of the UDT if this column is a user defined type.
	// This is returned by the server; users should not set this themselves when defining a table schema.
	UDTDefinition *UDTDefinition `json:"definition,omitempty"`
}

Column represents a column's type definition. It can be a simple scalar type, a collection type (set, list, map), a vector type, or a user-defined type.

func Ascii
func Ascii() Column

Ascii creates an ascii column

func BigInt
func BigInt() Column

BigInt creates a bigint column

func Blob
func Blob() Column

Blob creates a blob column

func Boolean
func Boolean() Column

Boolean creates a boolean column

func Date
func Date() Column

Date creates a date column

func Decimal
func Decimal() Column

Decimal creates a decimal column

func Double
func Double() Column

Double creates a double column

func Duration
func Duration() Column

Duration creates a duration column

func Float
func Float() Column

Float creates a float column

func Inet
func Inet() Column

Inet creates an inet column

func Int
func Int() Column

Int creates an int column

func List
func List(valueType Column) Column

List creates a list column with the specified value type

func Map
func Map(keyType string, valueType Column) Column

Map creates a map column with the specified key and value types

func Set
func Set(valueType Column) Column

Set creates a set column with the specified value type

func SmallInt
func SmallInt() Column

SmallInt creates a smallint column

func Text
func Text() Column

Text creates a text column

func Time
func Time() Column

Time creates a time column

func TimeUUID
func TimeUUID() Column

TimeUUID creates a TimeUUID column

func Timestamp
func Timestamp() Column

Timestamp creates a timestamp column

func TinyInt
func TinyInt() Column

TinyInt creates a tinyint column

func UDT
func UDT(udtName string) Column

UDT creates a user-defined type column

func UUID
func UUID() Column

UUID creates a UUID column

func Varint
func Varint() Column

Varint creates a varint column

func Vector
func Vector(dimension int) Column

Vector creates a vector column with the specified dimension

func VectorWithService
func VectorWithService(dimension int, service *VectorService) Column

VectorWithService creates a vector column with vectorize embedding provider

func (*Column) UnmarshalAstraRaw
func (c *Column) UnmarshalAstraRaw(ctx serdes.DecodeCtx, value []byte) error

type Columns

type Columns []NamedColumn

Columns is an ordered collection of named columns. It marshals as a JSON object, preserving insertion order on output and input order on parse.

Construct with a literal: 

table.Columns{
    {"title",  table.Text()},
    {"author", table.Text()},
}
func (Columns) Get
func (c Columns) Get(name string) (Column, bool)

Get returns the column with the given name and whether it was found.

func (Columns) MarshalAstra
func (c Columns) MarshalAstra(_ serdes.EncodeCtx) (any, error)
func (*Columns) UnmarshalAstraRaw
func (c *Columns) UnmarshalAstraRaw(ctx serdes.DecodeCtx, value []byte) error

type Definition

type Definition struct {
	// Columns defines all columns in the table with their types.
	// Order is preserved on marshal and captured on unmarshal.
	Columns Columns `json:"columns"`

	// PrimaryKey defines the primary key for the table
	PrimaryKey PrimaryKey `json:"primaryKey"`
}

Definition represents the full Schema for a table, including column names, column data types, and the primary key.

Example: 

def := table.Definition{
	Columns: table.Columns{
		{"title", table.Text()},
		{"author", table.Text()},
		{"rating", table.Float()},
	},
	PrimaryKey: table.PrimaryKey{
		PartitionBy: []string{"title"},
	},
}
func Infer
func Infer[T any]() (Definition, error)

Infer generates a table Definition from a Go struct's type information.

Column names are taken from json tags (falling back to field names). Primary key configuration and type overrides come from astra tags.

See the astra tag grammar:

The <T> in type= supports:

Composed example: astra:"type=map[uuid]set[ascii]"

Example: 

type Book struct {
    Title  string  `json:"title"  astra:"pk"`
    Author string  `json:"author"`
    Rating float32 `json:"rating"`
}

def, err := table.Infer[Book]()
tbl, err := db.CreateTable(ctx, "books", def)

type DefinitionBuilder

type DefinitionBuilder struct {
	// contains filtered or unexported fields
}

DefinitionBuilder provides a fluent API for constructing table definitions.

Example using the builder pattern: 

definition := table.NewDefinition().
	AddColumn("id", table.UUID()).
	AddTextColumn("title").
	AddFloatColumn("rating").
	AddListColumn("genres", table.Text()).
	AddVectorColumn("embeddings", 1536).
	SetPartitionBy("id").
	Build()
func NewDefinition
func NewDefinition() *DefinitionBuilder

NewDefinition creates a new DefinitionBuilder for fluent table definition construction.

func (DefinitionBuilder) AddAsciiColumn
func (s DefinitionBuilder) AddAsciiColumn(name string) B

AddAsciiColumn adds an ascii column or field.

func (DefinitionBuilder) AddBigIntColumn
func (s DefinitionBuilder) AddBigIntColumn(name string) B

AddBigIntColumn adds a bigint column or field.

func (DefinitionBuilder) AddBlobColumn
func (s DefinitionBuilder) AddBlobColumn(name string) B

AddBlobColumn adds a blob column or field.

func (DefinitionBuilder) AddBooleanColumn
func (s DefinitionBuilder) AddBooleanColumn(name string) B

AddBooleanColumn adds a boolean column or field.

func (*DefinitionBuilder) AddClusteringColumn
func (b *DefinitionBuilder) AddClusteringColumn(column string, sortOrder int) *DefinitionBuilder

AddClusteringColumn adds a clustering column with the specified sort order. Use table.SortAscending (1) or table.SortDescending (-1) for the sort order. If the column was already added, its sort order is updated in place.

func (*DefinitionBuilder) AddClusteringColumnAsc
func (b *DefinitionBuilder) AddClusteringColumnAsc(column string) *DefinitionBuilder

AddClusteringColumnAsc adds a clustering column with ascending sort order.

func (*DefinitionBuilder) AddClusteringColumnDesc
func (b *DefinitionBuilder) AddClusteringColumnDesc(column string) *DefinitionBuilder

AddClusteringColumnDesc adds a clustering column with descending sort order.

func (*DefinitionBuilder) AddColumn
func (b *DefinitionBuilder) AddColumn(name string, columnType Column) *DefinitionBuilder

AddColumn adds a column with the specified name and type. If a column with the same name already exists, its type is replaced but its position is kept.

func (DefinitionBuilder) AddDateColumn
func (s DefinitionBuilder) AddDateColumn(name string) B

AddDateColumn adds a date column or field.

func (DefinitionBuilder) AddDecimalColumn
func (s DefinitionBuilder) AddDecimalColumn(name string) B

AddDecimalColumn adds a decimal column or field.

func (DefinitionBuilder) AddDoubleColumn
func (s DefinitionBuilder) AddDoubleColumn(name string) B

AddDoubleColumn adds a double column or field.

func (DefinitionBuilder) AddDurationColumn
func (s DefinitionBuilder) AddDurationColumn(name string) B

AddDurationColumn adds a duration column or field.

func (DefinitionBuilder) AddFloatColumn
func (s DefinitionBuilder) AddFloatColumn(name string) B

AddFloatColumn adds a float column or field.

func (DefinitionBuilder) AddInetColumn
func (s DefinitionBuilder) AddInetColumn(name string) B

AddInetColumn adds an inet column or field.

func (DefinitionBuilder) AddIntColumn
func (s DefinitionBuilder) AddIntColumn(name string) B

AddIntColumn adds an int column or field.

func (*DefinitionBuilder) AddListColumn
func (b *DefinitionBuilder) AddListColumn(name string, valueType Column) *DefinitionBuilder

AddListColumn adds a list column with the specified value type.

func (*DefinitionBuilder) AddMapColumn
func (b *DefinitionBuilder) AddMapColumn(name string, keyType string, valueType Column) *DefinitionBuilder

AddMapColumn adds a map column with the specified key and value types.

func (*DefinitionBuilder) AddPartitionBy
func (b *DefinitionBuilder) AddPartitionBy(column string) *DefinitionBuilder

AddPartitionBy appends a column to the partition key.

func (*DefinitionBuilder) AddSetColumn
func (b *DefinitionBuilder) AddSetColumn(name string, valueType Column) *DefinitionBuilder

AddSetColumn adds a set column with the specified value type.

func (DefinitionBuilder) AddSmallIntColumn
func (s DefinitionBuilder) AddSmallIntColumn(name string) B

AddSmallIntColumn adds a smallint column or field.

func (DefinitionBuilder) AddTextColumn
func (s DefinitionBuilder) AddTextColumn(name string) B

AddTextColumn adds a text column or field.

func (DefinitionBuilder) AddTimeColumn
func (s DefinitionBuilder) AddTimeColumn(name string) B

AddTimeColumn adds a time column or field.

func (DefinitionBuilder) AddTimeUUIDColumn
func (s DefinitionBuilder) AddTimeUUIDColumn(name string) B

AddTimeUUIDColumn adds a TimeUUID column or field.

func (DefinitionBuilder) AddTimestampColumn
func (s DefinitionBuilder) AddTimestampColumn(name string) B

AddTimestampColumn adds a timestamp column or field.

func (DefinitionBuilder) AddTinyIntColumn
func (s DefinitionBuilder) AddTinyIntColumn(name string) B

AddTinyIntColumn adds a tinyint column or field.

func (*DefinitionBuilder) AddUDTColumn
func (s *DefinitionBuilder) AddUDTColumn(name string, udtName string) *DefinitionBuilder

AddUDTColumn adds a user-defined type column or field.

func (DefinitionBuilder) AddUUIDColumn
func (s DefinitionBuilder) AddUUIDColumn(name string) B

AddUUIDColumn adds a UUID column or field.

func (DefinitionBuilder) AddVarintColumn
func (s DefinitionBuilder) AddVarintColumn(name string) B

AddVarintColumn adds a varint column or field.

func (*DefinitionBuilder) AddVectorColumn
func (b *DefinitionBuilder) AddVectorColumn(name string, dimension int) *DefinitionBuilder

AddVectorColumn adds a vector column with the specified dimension.

func (*DefinitionBuilder) AddVectorColumnWithService
func (b *DefinitionBuilder) AddVectorColumnWithService(name string, dimension int, service *VectorService) *DefinitionBuilder

AddVectorColumnWithService adds a vector column with vectorize embedding provider.

func (*DefinitionBuilder) Build
func (b *DefinitionBuilder) Build() Definition

Build constructs the final Definition from the builder.

func (*DefinitionBuilder) SetPartitionBy
func (b *DefinitionBuilder) SetPartitionBy(columns ...string) *DefinitionBuilder

SetPartitionBy sets the partition key columns. For a single partition key, pass one column name. For a composite partition key, pass multiple column names.

type DropColumns

type DropColumns struct {
	Columns []string `json:"columns"`
}

DropColumns is the payload for the alterTable "drop" operation.

func (DropColumns) MarshalAstraRaw
func (d DropColumns) MarshalAstraRaw(ctx serdes.EncodeCtx, dst []byte) ([]byte, error)

type DropReranking

type DropReranking struct{}

DropReranking is the payload for the alterTable "dropReranking" operation.

func (DropReranking) MarshalAstraRaw
func (r DropReranking) MarshalAstraRaw(ctx serdes.EncodeCtx, dst []byte) ([]byte, error)

type DropVectorize

type DropVectorize struct {
	Columns []string `json:"columns"`
}

DropVectorize is the payload for the alterTable "dropVectorize" operation.

func (DropVectorize) MarshalAstraRaw
func (v DropVectorize) MarshalAstraRaw(ctx serdes.EncodeCtx, dst []byte) ([]byte, error)

type NamedColumn

type NamedColumn struct {
	Name   string
	Column Column
}

NamedColumn pairs a column name with its type definition.

type NamedSort

type NamedSort struct {
	Name  string
	Order int
}

NamedSort pairs a clustering-column name with its sort direction (SortAscending or SortDescending).

type PartitionSort

type PartitionSort []NamedSort

PartitionSort is an ordered collection of clustering columns with their sort direction. It marshals as a JSON object, preserving declared order on output and input order on parse.

Construct with a literal: 

table.PartitionSort{
    {"event_time", table.SortDescending},
    {"priority",   table.SortAscending},
}
func (PartitionSort) Get
func (s PartitionSort) Get(name string) (int, bool)

Get returns the sort order for the given column and whether it was found.

func (PartitionSort) MarshalAstra
func (s PartitionSort) MarshalAstra(_ serdes.EncodeCtx) (any, error)
func (*PartitionSort) UnmarshalAstraRaw
func (s *PartitionSort) UnmarshalAstraRaw(ctx serdes.DecodeCtx, value []byte) error

type PrimaryKey

type PrimaryKey struct {
	// PartitionBy lists the partition key columns
	PartitionBy []string `json:"partitionBy"`

	// PartitionSort defines clustering columns and their sort order (1 for ASC, -1 for DESC).
	// Order is significant — it defines the physical sort order of rows within a partition —
	// and is preserved through JSON marshaling.
	PartitionSort PartitionSort `json:"partitionSort,omitempty"`
}

PrimaryKey defines the primary key structure for a table. It can be a single column name or a compound/composite key definition.

func (PrimaryKey) MarshalAstraRaw
func (p PrimaryKey) MarshalAstraRaw(ctx serdes.EncodeCtx, dst []byte) ([]byte, error)
func (*PrimaryKey) UnmarshalAstraRaw
func (p *PrimaryKey) UnmarshalAstraRaw(ctx serdes.DecodeCtx, data []byte) error

type RenameTypeFields

type RenameTypeFields struct {
	Fields map[string]string `json:"fields"`
}

RenameTypeFields is the payload for the alterType "rename" operation.

func (RenameTypeFields) MarshalAstraRaw
func (r RenameTypeFields) MarshalAstraRaw(ctx serdes.EncodeCtx, dst []byte) ([]byte, error)

type RerankService

type RerankService struct {
	// Provider is the reranking provider name (e.g., "nvidia")
	Provider string `json:"provider"`

	// ModelName is the model to use for reranking
	ModelName string `json:"modelName"`

	// Authentication contains authentication configuration
	Authentication map[string]string `json:"authentication,omitempty"`

	// Parameters contains provider-specific parameters
	Parameters map[string]string `json:"parameters,omitempty"`
}

RerankService defines the configuration for reranking.

type UDTDefinition

type UDTDefinition struct {
	Fields Columns `json:"fields"`
}
func InferUDT
func InferUDT[T any]() (UDTDefinition, error)

InferUDT generates a UDTDefinition from a Go struct's type information.

Field names are taken from json tags (falling back to field names). Type overrides come from astra tags.

See Infer for details on the astra tag grammar.

Example: 

type Address struct {
    Street string `json:"street"`
    City   string `json:"city"`
}

def, err := table.InferUDT[Address]()
err := db.CreateType(ctx, "address", def)

type UDTDefinitionBuilder

type UDTDefinitionBuilder struct {
	// contains filtered or unexported fields
}

UDTDefinitionBuilder provides a fluent API for constructing UDT definitions.

func NewUDTDefinition
func NewUDTDefinition() *UDTDefinitionBuilder

NewUDTDefinition creates a new UDTDefinitionBuilder for fluent UDT definition construction.

func (UDTDefinitionBuilder) AddAsciiColumn
func (s UDTDefinitionBuilder) AddAsciiColumn(name string) B

AddAsciiColumn adds an ascii column or field.

func (UDTDefinitionBuilder) AddBigIntColumn
func (s UDTDefinitionBuilder) AddBigIntColumn(name string) B

AddBigIntColumn adds a bigint column or field.

func (UDTDefinitionBuilder) AddBlobColumn
func (s UDTDefinitionBuilder) AddBlobColumn(name string) B

AddBlobColumn adds a blob column or field.

func (UDTDefinitionBuilder) AddBooleanColumn
func (s UDTDefinitionBuilder) AddBooleanColumn(name string) B

AddBooleanColumn adds a boolean column or field.

func (*UDTDefinitionBuilder) AddColumn
func (b *UDTDefinitionBuilder) AddColumn(name string, columnType Column) *UDTDefinitionBuilder

AddColumn adds a field with the specified name and type to the UDT. If a field with the same name already exists, its type is replaced but its position is kept.

func (UDTDefinitionBuilder) AddDateColumn
func (s UDTDefinitionBuilder) AddDateColumn(name string) B

AddDateColumn adds a date column or field.

func (UDTDefinitionBuilder) AddDecimalColumn
func (s UDTDefinitionBuilder) AddDecimalColumn(name string) B

AddDecimalColumn adds a decimal column or field.

func (UDTDefinitionBuilder) AddDoubleColumn
func (s UDTDefinitionBuilder) AddDoubleColumn(name string) B

AddDoubleColumn adds a double column or field.

func (UDTDefinitionBuilder) AddDurationColumn
func (s UDTDefinitionBuilder) AddDurationColumn(name string) B

AddDurationColumn adds a duration column or field.

func (UDTDefinitionBuilder) AddFloatColumn
func (s UDTDefinitionBuilder) AddFloatColumn(name string) B

AddFloatColumn adds a float column or field.

func (UDTDefinitionBuilder) AddInetColumn
func (s UDTDefinitionBuilder) AddInetColumn(name string) B

AddInetColumn adds an inet column or field.

func (UDTDefinitionBuilder) AddIntColumn
func (s UDTDefinitionBuilder) AddIntColumn(name string) B

AddIntColumn adds an int column or field.

func (UDTDefinitionBuilder) AddSmallIntColumn
func (s UDTDefinitionBuilder) AddSmallIntColumn(name string) B

AddSmallIntColumn adds a smallint column or field.

func (UDTDefinitionBuilder) AddTextColumn
func (s UDTDefinitionBuilder) AddTextColumn(name string) B

AddTextColumn adds a text column or field.

func (UDTDefinitionBuilder) AddTimeColumn
func (s UDTDefinitionBuilder) AddTimeColumn(name string) B

AddTimeColumn adds a time column or field.

func (UDTDefinitionBuilder) AddTimeUUIDColumn
func (s UDTDefinitionBuilder) AddTimeUUIDColumn(name string) B

AddTimeUUIDColumn adds a TimeUUID column or field.

func (UDTDefinitionBuilder) AddTimestampColumn
func (s UDTDefinitionBuilder) AddTimestampColumn(name string) B

AddTimestampColumn adds a timestamp column or field.

func (UDTDefinitionBuilder) AddTinyIntColumn
func (s UDTDefinitionBuilder) AddTinyIntColumn(name string) B

AddTinyIntColumn adds a tinyint column or field.

func (UDTDefinitionBuilder) AddUUIDColumn
func (s UDTDefinitionBuilder) AddUUIDColumn(name string) B

AddUUIDColumn adds a UUID column or field.

func (UDTDefinitionBuilder) AddVarintColumn
func (s UDTDefinitionBuilder) AddVarintColumn(name string) B

AddVarintColumn adds a varint column or field.

func (*UDTDefinitionBuilder) Build
func (b *UDTDefinitionBuilder) Build() UDTDefinition

Build constructs the final UDTDefinition from the builder.

type VectorService

type VectorService struct {
	// Provider is the embedding provider name (e.g., "openai", "nvidia", "azureOpenAI")
	Provider string `json:"provider"`

	// ModelName is the model to use for generating embeddings
	ModelName string `json:"modelName"`

	// Authentication contains authentication configuration
	Authentication map[string]string `json:"authentication,omitempty"`

	// Parameters contains provider-specific parameters
	Parameters map[string]string `json:"parameters,omitempty"`
}

VectorService defines the embedding provider configuration for vectorize