Get a table

Tables with the Data API are currently in public preview. Development is ongoing, and the features and functionality are subject to change. Astra DB Serverless, and the use of such, is subject to the DataStax Preview Terms.

Gets a reference to a table for use with the Data API clients.

Method signature

Python
TypeScript
Java
curl

The following method belongs to the astrapy.Database class.

get_table(
  name: str,
  *,
  row_type: type[Any],
  keyspace: str,
  embedding_api_key: str | EmbeddingHeadersProvider,
  spawn_api_options: APIOptions,
) -> Table[ROW]

The following method belongs to the Db class.

table(
  name: string,
  options?: {
    embeddingApiKey?: string | EmbeddingHeadersProvider,
    logging?: DataAPILoggingConfig,
    serdes?: TableSerDesConfig,
    timeoutDefaults?: Partial<TimeoutDescriptor>,
    keyspace?: string,
  },
): Table<Schema, PKeys>

The following methods belong to the com.datastax.astra.client.databases.Database class.

Table<Row> getTable(String tableName)

Table<Row> getTable(
  String tableName,
  TableOptions tableOptions
)

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

<T> Table<T> getTable(
  String tableName,
  Class<T> rowClass
)

<T> Table<T> getTable(
  String tableName,
  Class<T> rowClass,
  TableOptions tableOptions
)

This method has no literal equivalent in HTTP. Instead, you specify the table in the path, if required.

To get information about tables in a database, see List table metadata.

Result

Python
TypeScript
Java
curl

Returns a Table object that corresponds to the specified table name.

Unless you specify the row_type parameter, the table is typed as Table[dict].

This method returns a Table object even for tables that don’t exist.

Returns a Table<Schema> object that corresponds to the specified table name.

Unless you specify the Schema, the table is typed as Table<Record<string, any>>.

This method returns a Table object even for tables that don’t exist.

Returns a Table<T> object that corresponds to the specified table name.

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

This method returns a Table object even for tables that don’t exist.

This method has no literal equivalent in HTTP. Instead, you specify the table in the path, if required.

To get information about tables in a database, see List table metadata.

Parameters

Python
TypeScript
Java
curl

Name Type Summary

Name	Type	Summary
`name`	`str`	The name of the table.
`row_type`	`type`	This parameter acts a formal specifier for the type checker. If omitted, the resulting `Table` is implicitly a `Table[dict]`. If provided, `row_type` must match the type hint specified in the assignment. For more information, see Typing support.
`keyspace`	`str \| None`	The keyspace containing the target table. If not specified, the general keyspace setting for the database is used.
`embedding_api_key`	`str \| EmbeddingHeadersProvider`	Optional parameter for tables that have a `vector` column with a vectorize embedding provider integration. For more information, see Define a column to automatically generate vector embeddings. As an alternative to Astra DB KMS authentication, use `embedding_api_key` to store one or more embedding provider API keys on the `Table` instance for vectorize header authentication. The client automatically passes the key as an `X-embedding-api-key` header with all table operations. Most embedding provider integrations accept a plain `string` for header authentication. However, some vectorize providers and models require specialized subclasses of `EmbeddingHeadersProvider`, such as `AWSEmbeddingHeadersProvider`, for header authentication.
`spawn_api_options`	`APIOptions`	A complete or partial specification of the APIOptions to override the defaults inherited from the `Database`. This allows for nuanced table configuration. For example, if `APIOptions` is passed together with named timeout parameters, the latter take precedence in their respective settings.

name

str

The name of the table.

row_type

type

This parameter acts a formal specifier for the type checker. If omitted, the resulting Table is implicitly a Table[dict]. If provided, row_type must match the type hint specified in the assignment. For more information, see Typing support.

keyspace

str | None

The keyspace containing the target table. If not specified, the general keyspace setting for the database is used.

embedding_api_key

str | EmbeddingHeadersProvider

Optional parameter for tables that have a vector column with a vectorize embedding provider integration. For more information, see Define a column to automatically generate vector embeddings.

As an alternative to Astra DB KMS authentication, use embedding_api_key to store one or more embedding provider API keys on the Table instance for vectorize header authentication. The client automatically passes the key as an X-embedding-api-key header with all table operations.

Most embedding provider integrations accept a plain string for header authentication. However, some vectorize providers and models require specialized subclasses of EmbeddingHeadersProvider, such as AWSEmbeddingHeadersProvider, for header authentication.

spawn_api_options

APIOptions

A complete or partial specification of the APIOptions to override the defaults inherited from the Database. This allows for nuanced table configuration. For example, if APIOptions is passed together with named timeout parameters, the latter take precedence in their respective settings.

Name Type Summary

Name	Type	Summary
`name`	`string`	The name of the table.
`option?`	`TableOptions`	The options for spawning the `Table` instance.

name

string

The name of the table.

option?

TableOptions

The options for spawning the Table instance.

Options (TableOptions<Schema>):

Name Type Summary

Name	Type	Summary
`keyspace?`	`string`	The keyspace where the target table exists. If not specified, the working keyspace of the `Db` is used. For example: `const table = db.table<Schema>('games', { keyspace: 'KEYSPACE', });`
`embeddingApiKey?`	`string \| EmbeddingHeadersProvider`	Optional parameter for tables that have a `vector` column with a vectorize embedding provider integration. For more information, see Define a column to automatically generate vector embeddings. As an alternative to Astra DB KMS authentication, use `embeddingApiKey` to store an embedding provider API key on the `Table` instance for vectorize header authentication. The client automatically passes the key as an `X-embedding-api-key` header with operations that use vectorize. Most embedding provider integrations accept a plain `string` for header authentication. However, some vectorize providers and models require specialized subclasses of `EmbeddingHeadersProvider` for header authentication.
`logging?`	`DataAPILoggingConfig`	The configuration for logging events emitted by the `DataAPIClient`.
`timeoutDefaults?`	`Partial<TimeoutDescriptor>`	The default timeout options for any operation performed on this `Table` instance. For more information, see TimeoutDescriptor.
`serdes?`	`TableSerDesConfig`	Lower-level serialization/deserialization configuration for this table. For more information, see Custom Ser/Des.

keyspace?

string

The keyspace where the target table exists. If not specified, the working keyspace of the Db is used. For example:

const table = db.table<Schema>('games', {
  keyspace: 'KEYSPACE',
});

embeddingApiKey?

string | EmbeddingHeadersProvider

Optional parameter for tables that have a vector column with a vectorize embedding provider integration. For more information, see Define a column to automatically generate vector embeddings.

As an alternative to Astra DB KMS authentication, use embeddingApiKey to store an embedding provider API key on the Table instance for vectorize header authentication. The client automatically passes the key as an X-embedding-api-key header with operations that use vectorize.

logging?

DataAPILoggingConfig

The configuration for logging events emitted by the DataAPIClient.

timeoutDefaults?

Partial<TimeoutDescriptor>

The default timeout options for any operation performed on this Table instance. For more information, see TimeoutDescriptor.

serdes?

TableSerDesConfig

Lower-level serialization/deserialization configuration for this table. For more information, see Custom Ser/Des.

Name Type Summary

Name	Type	Summary
`name`	`String`	The name of the table.
`rowClass`	`Class<?>`	An optional specification of the class of the table’s row object. If not provided, the default is `Row`, which is close to a `Map` object.
`tableOptions`	`TableOptions`	Specialization of the `Table` object overriding default configuration (`DataAPIOptions`).

name

String

The name of the table.

rowClass

Class<?>

An optional specification of the class of the table’s row object. If not provided, the default is Row, which is close to a Map object.

tableOptions

TableOptions

Specialization of the Table object overriding default configuration (DataAPIOptions).

Options:

Name Type Summary

Name	Type	Summary
`keyspace`	`String`	The keyspace containing the target table. If not specified, the working keyspace of the `Database` is used.
`timeout`	`long` or `Duration`	Optional configuration for default timeouts for table operations using this `Table` object. This is a general method for all operations.
`databaseAdditionalHeaders`	`Map<String, String>`	Optional specialized headers for this table, if needed, that are added to the database headers.
`embeddingApiKey`	`String`	Optional parameter for tables that have a `vector` column with a vectorize embedding provider integration. For more information, see Define a column to automatically generate vector embeddings. As an alternative to Astra DB KMS authentication, use `embeddingApiKey` to store an embedding provider API key on the `Table` instance for vectorize header authentication. The client automatically passes the key as an `X-embedding-api-key` header with operations that use vectorize. Most embedding provider integrations accept a plain `string` for header authentication. However, some vectorize providers and models require specialized subclasses of `EmbeddingHeadersProvider` for header authentication.
`EmbeddingHeadersProvider`	`EmbeddingHeadersProvider`	An optional specialization associated with `embeddingApiKey`.
`httpClientOptions`	`HttpClientOptions`	Optional HTTP configuration overrides for this `Table` instance.
`serializer`	`DataAPISerializer`	Optional specialized serializer for this `Table` instance. If not provided `RowSerializer` is used.

keyspace

String

The keyspace containing the target table. If not specified, the working keyspace of the Database is used.

timeout

long or Duration

Optional configuration for default timeouts for table operations using this Table object. This is a general method for all operations.

databaseAdditionalHeaders

Map<String, String>

Optional specialized headers for this table, if needed, that are added to the database headers.

embeddingApiKey

String

Optional parameter for tables that have a vector column with a vectorize embedding provider integration. For more information, see Define a column to automatically generate vector embeddings.

EmbeddingHeadersProvider

An optional specialization associated with embeddingApiKey.

httpClientOptions

HttpClientOptions

Optional HTTP configuration overrides for this Table instance.

serializer

DataAPISerializer

Optional specialized serializer for this Table instance. If not provided RowSerializer is used.

This method has no literal equivalent in HTTP. Instead, you specify the table in the path, if required.

To get information about tables in a database, see List table metadata.

Examples

The following examples demonstrate how to get a table.

Get a table

Python
TypeScript
Java
curl

from astrapy import DataAPIClient

# Get an existing table
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
table = database.get_table("TABLE_NAME")

import { DataAPIClient } from '@datastax/astra-db-ts';

// Get an existing table
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const table = database.table('TABLE_NAME');

package com.example;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.definition.rows.Row;
import com.datastax.astra.client.tables.Table;

import java.util.Optional;

public class GetTable {

    public static void main(String[] args) {

        // Get an existing table
        Table<Row> table = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
            .getDatabase("ASTRA_DB_API_ENDPOINT")
            .getTable("TABLE_NAME");
    }
}

This method has no literal equivalent in HTTP. Instead, you specify the table in the path, if required.

To get information about tables in a database, see List table metadata.

Get a table and specify the keyspace

By default, this method uses the working keyspace of your database. If you want to use a different keyspace, you must specify the keyspace.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient

# Get an existing table
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
table = database.get_table(
    "TABLE_NAME",
    keyspace="KEYSPACE_NAME",
)

import { DataAPIClient } from '@datastax/astra-db-ts';

// Get an existing table
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const table = database.table(
  'TABLE_NAME',
  {
    keyspace: "KEYSPACE_NAME",
  },
);

package com.example;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.definition.rows.Row;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.TableOptions;

import java.util.Optional;

public class GetTable {

    public static void main(String[] args) {

        // Get an existing table
        TableOptions options = new TableOptions()
            .keyspace("KEYSPACE_NAME")
        Table<Row> table = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
            .getDatabase("ASTRA_DB_API_ENDPOINT")
            .getTable("TABLE_NAME", options);
    }
}

This method has no literal equivalent in HTTP. Instead, you specify the table in the path, if required.

To get information about tables in a database, see List table metadata.

Get a table and specify typing

Python
TypeScript
Java
curl

Use the row_type parameter to specify typing for the row. The value of row_type should be a subclass of TypedDict.

If you don’t specify the row_type parameter, the table is typed as Table[dict].

from astrapy import DataAPIClient, Table
from typing import TypedDict, Set, Dict, Optional
from datetime import date

# Define the typing
class TableSchema(TypedDict):
    title: str
    author: str
    number_of_pages: int
    rating: float
    genres: Set[str]
    metadata: Dict[str, str]
    is_checked_out: bool
    due_date: Optional[date]

# Get an existing table
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
table: Table[TableSchema] = database.get_table(
  "TABLE_NAME",
  row_type=TableSchema
)

When you get a table, you can specify the table schema type.

If you specify the table schema type, you can also specify the primary key type. The primary key type is only used in the return types of the insertOne and insertMany methods. You don’t need to specify the primary key type if you don’t need to use the returned values from the insertOne and insertMany methods.

If you don’t specify any typing, the table rows are typed as Record<string, any>. This is the most flexible but least type-safe option.

For more information, see Collection and table typing.

import { DataAPIClient, DataAPIDate } from '@datastax/astra-db-ts';

// Manually define the type of the table's schema and primary key
type TableSchema = {
  title: string;
  author: string;
  number_of_pages?: number | null | undefined;
  rating?: number | null | undefined;
  genres?: Set<string> | undefined;
  metadata?: Map<string, string> | undefined;
  is_checked_out?: boolean | null | undefined;
  due_date?: DataAPIDate | null | undefined;
};

type TablePrimaryKey = Pick<TableSchema, "title" | "author">;

// Get an existing table
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const table = database.table<TableSchema, TablePrimaryKey>('TABLE_NAME');

Use the Class parameter to specify typing for the row.

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

package com.example;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.columns.ColumnTypes;
import com.datastax.astra.client.tables.mapping.Column;

import java.util.Date;
import java.util.Map;
import java.util.Set;
import lombok.Data;
import lombok.NoArgsConstructor;

public class GetTable {
    @Data
    @NoArgsConstructor
    public class Book {
      @Column(name = "title", type = ColumnTypes.TEXT)
      private String title;

      @Column(name = "author", type = ColumnTypes.TEXT)
      private String author;

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

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

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

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

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

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

    public static void main(String[] args) {
        // Get an existing table
        Table<Book> table = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
            .getDatabase("ASTRA_DB_API_ENDPOINT")
            .getTable("TABLE_NAME", Book.class);
    }
}

This method has no literal equivalent in HTTP. Instead, you specify the table in the path, if required.

To get information about tables in a database, see List table metadata.

Client reference

Python
TypeScript
Java
curl

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

Get a table

Method signature

Result

Parameters

Examples

Get a table

Get a table and specify the keyspace

Get a table and specify typing

Client reference

Was this helpful?

Give Feedback