List table metadata

This Astra DB Serverless feature is 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.

The Data API tables commands are available through HTTP and the clients.

If you use a client, tables commands are available only in client versions 2.0-preview or later. For more information, see Data API client upgrade guide.

Gets information about the tables in a keyspace.

Method signature

Python
TypeScript
Java
curl

The following method belongs to the astrapy.Database class.

list_tables(
  *,
  keyspace: str,
  table_admin_timeout_ms: int,
  request_timeout_ms: int,
  timeout_ms: int,
) -> list[ListTableDescriptor]

The following method belongs to the Db class.

async listTables(
  options?: {
    nameOnly?: boolean,
    keyspace?: string,
    timeout?: number | TimeoutDescriptor,
  },
): TableDescriptor[]

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

List<TableDescriptor> listTables()

List<TableDescriptor> listTables(ListTablesOptions listTableOptions)

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "listTables": {
    "options": {
      "explain": true
    }
  }
}'

Result

Python
TypeScript
Java
curl

Returns an unordered list of ListTableDescriptor objects that describe each table.

Example response:

[
  BaseTableDescriptor(
    name='fighters',
    definition=BaseTableDefinition(
      columns=[fighter_id,age,name,nationality,skill_levels],
      primary_key=TablePrimaryKeyDescriptor[(fighter_id)]
    ),
    raw_descriptor=...
  ),
  BaseTableDescriptor(
    name='games',
    definition=BaseTableDefinition(
      columns=[match_id,round,fighters,m_vector,score,when,winner],
      primary_key=TablePrimaryKeyDescriptor[(match_id)round:a]
    ),
    raw_descriptor=...
  )
]

Returns a promise that resolves to an unordered list of FullTableInfo objects that describe each table.

Example resolved response:

[
  {
    name: 'games',
    definition: {
      columns: {
        matchId: { type: 'text' },
        round: { type: 'tinyint' },
        fighters: { type: 'set', valueType: 'uuid' },
        mVector: { type: 'vector', dimension: 3 },
        score: { type: 'int' },
        when: { type: 'timestamp' },
        winner: { type: 'text' }
      },
      primaryKey: {
        partitionBy: [ 'matchId' ],
        partitionSort: { round: 1 }
      }
    }
  }
]

Returns an unordered list of TableDescriptor objects that describe each table.

The status.tables field in the response describes each table.

Example response:

{
  "status": {
    "tables": [
      {
        "name": "customers",
        "definition": {
          "columns": {
            "order_date": {
              "type": "timestamp"
            },
            "preferences": {
              "type": "map",
              "keyType": "text",
              "valueType": "text"
            },
            "is_active": {
              "type": "boolean"
            },
            "user_id": {
              "type": "uuid"
            },
            "name": {
              "type": "text"
            },
            "login_attempts": {
              "type": "set",
              "valueType": "int"
            },
            "photo": {
              "type": "blob"
            },
            "salary": {
              "type": "decimal"
            },
            "order_id": {
              "type": "uuid"
            },
            "age": {
              "type": "int"
            },
            "tags": {
              "type": "list",
              "valueType": "text"
            }
          },
          "primaryKey": {
            "partitionBy": [
              "user_id"
            ],
            "partitionSort": {
              "order_id": 1,
              "order_date": -1
            }
          }
        }
      }
    ]
  }
}

Parameters

Python
TypeScript
Java
curl

Name Type Summary

Name	Type	Summary
`keyspace`	`Optional[str]`	The keyspace to be inspected. If not specified, the database’s working keyspace is used.
`table_admin_timeout_ms`	`Optional[int]`	A timeout, in milliseconds, for the underlying HTTP request. If not provided, the `Database` setting is used. This parameter is aliased as `request_timeout_ms` and `timeout_ms` for convenience.

keyspace

Optional[str]

The keyspace to be inspected. If not specified, the database’s working keyspace is used.

table_admin_timeout_ms

Optional[int]

A timeout, in milliseconds, for the underlying HTTP request. If not provided, the Database setting is used. This parameter is aliased as request_timeout_ms and timeout_ms for convenience.

Name Type Summary

Name	Type	Summary
`options?`	`ListTablesOptions`	The options for this operation.

options?

ListTablesOptions

The options for this operation.

Options (ListTablesOptions):

Name Type Summary

Name	Type	Summary
`nameOnly?`	`boolean`	If false or undefined, the response includes table names and metadata. If true, the response includes only table names.
`keyspace?`	`string`	The keyspace to be inspected. If not specified, the database’s working keyspace is used.
`timeout?`	`number \| TimeoutDescriptor`	The client-side timeout for this operation.

nameOnly?

boolean

If false or undefined, the response includes table names and metadata. If true, the response includes only table names.

keyspace?

string

The keyspace to be inspected. If not specified, the database’s working keyspace is used.

timeout?

number | TimeoutDescriptor

The client-side timeout for this operation.

Name Type Summary

Name	Type	Summary
`options`	`ListTablesOptions`	Specialization of the operation, including `timeout` and `keyspace`.

options

ListTablesOptions

Specialization of the operation, including timeout and keyspace.

Name Type Summary

Name	Type	Summary
`listTables`	`command`	The Data API command to get a list of tables in a keyspace in a Serverless (Vector) database.
`options.explain`	`boolean`	Whether the response includes table metadata in addition to table names.

listTables

command

The Data API command to get a list of tables in a keyspace in a Serverless (Vector) database.

options.explain

boolean

Whether the response includes table metadata in addition to table names.

Examples

The following examples demonstrate how to get table metadata.

Python
TypeScript
Java
curl

Get information about the tables in the database’s working keyspace:

database.list_tables()

Get information about tables in a specific keyspace:

database.list_tables(keyspace="KEYSPACE_NAME")

Example:

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")
database = client.get_database("API_ENDPOINT")

tables = my_database.list_tables()
tables
# [BaseTableDescriptor(name='fighters', definition=BaseTableDefinition(...
tables[1].name
# 'games'
tables[1].definition.columns
# {'match_id': TableScalarColumnTypeDescriptor(ColumnType.TEXT),...
tables[1].definition.columns['score']
# TableScalarColumnTypeDescriptor(ColumnType.INT)
tables[1].definition.primary_key.partition_by
# ['match_id']
tables[1].definition.primary_key.partition_sort
# {'round': 1}

Get information about the tables in the database’s working keyspace:

await db.listTables();

Get information about tables in a specified keyspace in the database:

await db.listTables({ keyspace: 'KEYSPACE' });

Example:

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

// Instantiate the client and connect to the database
const client = new DataAPIClient();
const db = client.db(process.env.CLIENT_DB_URL!, { token: process.env.CLIENT_DB_TOKEN! });

// Create table schema using bespoke Data API table definition syntax.
// For information about table definition and data types, see the documentation for createTable.
const TableDefinition = <const>{
  columns: {
    matchId: 'text'
    round: 'tinyint',
    mVector: { type: 'vector', dimension: 3 },
    score: 'int',
    when: 'timestamp',
    winner: 'text',
    fighters: { type: 'set', valueType: 'uuid' },
  },
  primaryKey: {
    partitionBy: ['matchId'],
    partitionSort: { round: 1 },
  },
} satisfies CreateTableDefinition;

(async function () {
  // Create an untyped table if a 'games' table doesn't already exist.
  await db.createTable<SomeRow>('games', { definition: TableDefinition, ifNotExists: true });

  // Get detailed information about the table.
  // Returns information like [{ name: 'games', definition: { ... } }, ...]
  await db.listTables().then(console.log);

  // Get table names only.
  // Returns information like ['games', ...]
  await db.listTables({ nameOnly: true }).then(console.log);

  // Uncomment the following line to drop the table and any related indexes.
  // await table.drop();
})();

Get information about tables in the database’s working keyspace:

List<TableDescriptor> tableList = db.listTables();

Get information about tables in a specific keyspace and apply a custom timeout:

ListTablesOptions options = new ListTablesOptions()
  .keyspace("KEYSPACE_NAME")
  .timeout(Duration.ofSeconds(5));

List<TableDescriptor> tableList2 = database
  .listTables(options);

Example:

package com.datastax.astra.client.database;

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.Game;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.TableOptions;
import com.datastax.astra.client.tables.commands.options.ListTablesOptions;
import com.datastax.astra.client.tables.definition.TableDefinition;
import com.datastax.astra.client.tables.definition.TableDescriptor;
import com.datastax.astra.client.tables.definition.rows.Row;

import java.time.Duration;
import java.util.List;
import java.util.Map;

public class ListTables {

 public static void main(String[] args) {
  // Database astraDb =  new DataAPIClient(token).getDatabase(endpoint);
  Database db =
    DataAPIClients.localDbWithDefaultKeyspace();

  // Default
  List<TableDescriptor> tableList = db.listTables();

  // Options
  db.getDatabaseAdmin().createKeyspace("ks2");
  ListTablesOptions options = new ListTablesOptions()
          .keyspace("ks2")
          .timeout(Duration.ofSeconds(5));
  List<TableDescriptor> tableList2 = db.listTables(options);
  Table<Row> ts = db.getTable("table_simple", new TableOptions().keyspace("ks2"));
  // Expecting an error as table does not exist in ks2
 }
}

To get table metadata, use listTables with "explain": true:

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "listTables": {
    "options": {
      "explain": true
    }
  }
}' | jq

Client reference

Python
TypeScript
Java
curl

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

List table metadata

Method signature

Result

Parameters

Examples

Client reference

Was this helpful?

Give Feedback