Get a table

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

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

Python
TypeScript
Java
curl

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

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

Unless you specify the row_type parameter, the table is typed as Table[dict]. For more information, see Typing support.

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

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

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

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

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

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

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

Use the get_table method, which belongs to the astrapy.Database class.

Method signature

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

Name Type Summary

Name	Type	Summary
`name`	`str`	The name of the table.
`row_type`	`type`	Optional. A formal specifier for the type checker. If provided, `row_type` must match the type hint specified in the assignment. For more information, see Typing support. See Get a table and specify typing for an example. Default: `Table[dict]`
`keyspace`	`str`	Optional. The keyspace containing the table. See Get a table and specify the keyspace for an example. Default: The working keyspace for the database.
`embedding_api_key`	`str` \| `EmbeddingHeadersProvider`	Optional. This only applies to tables that have a vector column with a vectorize embedding provider integration. Use this option to provide the embedding provider API key directly with headers instead of using the API key in the Astra DB KMS. The API key is sent to the Data API for every operation on the collection. It is useful when a vectorize integration is configured but no credentials are stored, or when you want to override the stored credentials. For more information, see Auto-generate embeddings with vectorize. Most vectorize integrations accept a plain string for header authentication. However, some vectorize integrations and models require specialized subclasses of `EmbeddingHeadersProvider`, such as `AWSEmbeddingHeadersProvider`, for header authentication. You can use this authentication method only if all affected columns use the same embedding provider.
`spawn_api_options`	`APIOptions`	Optional. A complete or partial specification of the APIOptions to override the defaults inherited from the `Database`. Use this to customize the interaction of the Python client with the collection. For example, you can change the serialization/deserialization options or default timeouts. If `APIOptions` is passed together with a named parameter such as a timeout, the latter takes precedence over the corresponding `spawn_api_options` setting.

name

str

The name of the table.

row_type

type

Optional. A formal specifier for the type checker. If provided, row_type must match the type hint specified in the assignment. For more information, see Typing support.

See Get a table and specify typing for an example.

Default: Table[dict]

keyspace

str

Optional. The keyspace containing the table.

See Get a table and specify the keyspace for an example.

Default: The working keyspace for the database.

embedding_api_key

str | EmbeddingHeadersProvider

Optional. This only applies to tables that have a vector column with a vectorize embedding provider integration.

Use this option to provide the embedding provider API key directly with headers instead of using the API key in the Astra DB KMS.

The API key is sent to the Data API for every operation on the collection. It is useful when a vectorize integration is configured but no credentials are stored, or when you want to override the stored credentials. For more information, see Auto-generate embeddings with vectorize.

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

You can use this authentication method only if all affected columns use the same embedding provider.

spawn_api_options

APIOptions

Optional. A complete or partial specification of the APIOptions to override the defaults inherited from the Database. Use this to customize the interaction of the Python client with the collection. For example, you can change the serialization/deserialization options or default timeouts. If APIOptions is passed together with a named parameter such as a timeout, the latter takes precedence over the corresponding spawn_api_options setting.

Use the table method, which belongs to the Db class.

Method signature

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

Name Type Summary

Name	Type	Summary
`name`	`string`	The name of the table.
`options`	`TableOptions`	The options for this operation. See Properties of `options` for more details.

name

string

The name of the table.

options

TableOptions

The options for this operation. See Properties of options for more details.

Properties of `options`
Name	Type	Summary
`keyspace`	`string`	Optional. The keyspace in which to create the table. See Get a table and specify the keyspace for an example. Default: The working keyspace for the database.
`embeddingApiKey`	`string` \| `EmbeddingHeadersProvider`	Optional. This only applies to tables that have a vector column with a vectorize embedding provider integration. Use this option to provide the embedding provider API key directly with headers instead of using the API key in the Astra DB KMS. The API key is sent to the Data API for every operation on the collection. It is useful when a vectorize integration is configured but no credentials are stored, or when you want to override the stored credentials. For more information, see Auto-generate embeddings with vectorize. You can use this authentication method only if all affected columns use the same embedding provider.
`logging`	`DataAPILoggingConfig`	Optional. The configuration for logging events emitted by the `DataAPIClient`. For more information, see Logging.
`timeoutDefaults`	`Partial<TimeoutDescriptor>`	Optional. The default timeout options for any operation performed on this `Table` instance. For more information, see TimeoutDescriptor.
`serdes`	`TableSerDesConfig`	Optional. Lower-level serialization/deserialization configuration for this table. For more information, see Custom Ser/Des.

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

Method signature

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
)

Name Type Summary

Name	Type	Summary
`name`	`String`	The name of the table.
`rowClass`	`Class<?>`	Optional. A specification of the class of the table’s row object. See Get a table and specify typing for an example. Default: `Row`, which is close to a `Map` object
`tableOptions`	`TableOptions`	Optional. The options for this operation. See Methods of `TableOptions` for more details.

name

String

The name of the table.

rowClass

Class<?>

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

See Get a table and specify typing for an example.

Default: Row, which is close to a Map object

tableOptions

TableOptions

Optional. The options for this operation. See Methods of TableOptions for more details.

Methods of `TableOptions`
Method	Parameters	Summary
`keyspace()`	`String`	Optional. The keyspace containing the table. See Get a table and specify the keyspace for an example. Default: The working keyspace for the database.
`timeout()`	`long` \| `Duration`	Optional. A timeout, in milliseconds, for the underlying HTTP requests originating from this `Table` object. If not provided, the `Database` setting is used.
`databaseAdditionalHeaders()`	`Map<String, String>`	Optional. Specialized headers for this table, if needed, that are added to the database headers.
`embeddingAuthProvider()` \| `embeddingApiKey()`	`EmbeddingHeadersProvider` \| `String`	Optional. This only applies to tables that have a vector column with a vectorize embedding provider integration. Use this option to provide the embedding provider API key directly with headers instead of using the API key in the Astra DB KMS. The API key is sent to the Data API for every operation on the collection. It is useful when a vectorize integration is configured but no credentials are stored, or when you want to override the stored credentials. For more information, see Auto-generate embeddings with vectorize. Most vectorize integrations accept a plain string for header authentication. However, some vectorize integrations and models require specialized subclasses of `EmbeddingHeadersProvider` for header authentication. You can use this authentication method only if all affected columns use the same embedding provider.
`httpClientOptions()`	`HttpClientOptions`	Optional. HTTP configuration overrides for this `Table` object.
`serializer()`	`DataAPISerializer`	Optional. A 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("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
table = database.get_table("TABLE_NAME")

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

// Get an existing table
const client = new DataAPIClient("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
const table = database.table("TABLE_NAME");

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

public class Example {

  public static void main(String[] args) {

    // Get an existing table
    Table<Row> table =
        new DataAPIClient("APPLICATION_TOKEN")
            .getDatabase("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("APPLICATION_TOKEN")
database = client.get_database("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("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
const table = database.table("TABLE_NAME", {
  keyspace: "KEYSPACE_NAME",
});

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

public class Example {

  public static void main(String[] args) {

    // Get an existing table
    TableOptions options = new TableOptions().keyspace("KEYSPACE_NAME");
    Table<Row> table =
        new DataAPIClient("APPLICATION_TOKEN")
            .getDatabase("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("APPLICATION_TOKEN")
database = client.get_database("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("APPLICATION_TOKEN");
const database = client.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.

import com.datastax.astra.client.DataAPIClient;
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 java.util.Date;
import java.util.Map;
import java.util.Set;
import lombok.Data;
import lombok.NoArgsConstructor;

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

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

    @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 table
    Table<Book> table =
        new DataAPIClient("APPLICATION_TOKEN")
            .getDatabase("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

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