List table names

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 the names of the tables in a keyspace.

Method signature

Python
TypeScript
Java
curl

The following method belongs to the astrapy.Database class.

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

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<String> listTableNames()

List<String> listTableNames(ListTablesOptions listTablesOptions)

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": false
    }
  }
}'

Result

Python
TypeScript
Java
curl

Returns the table names as an unordered list of strings.

Example response:

["quickstart_table", "another_table"]

Returns a promise that resolves to the table names as an unordered list of strings.

Example resolved response:

["quickstart_table", "another_table"]

Returns the table names as an unordered list of strings.

Returns the table names as an unordered list of strings in the status.tables field of the response.

Example response:

{
  "status": {
    "tables":[
      "quickstart_table",
      "another_table"
    ]
  }
}

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`	If true, the response includes table names and metadata. If false or unset, the response includes only 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

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

Examples

The following examples demonstrate how to get table names.

Python
TypeScript
Java
curl

Get the names of tables in the database’s working keyspace:

database.list_table_names()

Get the names of tables in a specific keyspace in the database:

database.list_table_names(keyspace="KEYSPACE_NAME")

List[str] - A list of the table names in no particular order.

Example:

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

database.list_table_names()
# ['fighters', 'games']

Get the names of tables in the database’s working keyspace:

await db.listTables({ nameOnly: true });

Get the names of tables in a specific keyspace in the database:

await db.listTables({ nameOnly: true, 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 the name of tables in the database’s working keyspace:

List<String> tableNames = db.listTableNames();

Get the names of tables in a specific keyspace in the database and pass a custom timeout:

ListTablesOptions options = new ListTablesOptions()
  .keyspace("ks2")
  .timeout(Duration.ofSeconds(5));
List<String> tableList2 = database
  .listTableNames(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.Table;
import com.datastax.astra.client.tables.TableOptions;
import com.datastax.astra.client.tables.commands.options.ListTablesOptions;
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;

public class ListTablesNames {

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

  // Default
  List<String> tableNames = db.listTableNames();

  // Options
  db.getDatabaseAdmin().createKeyspace("ks2");
  ListTablesOptions options = new ListTablesOptions()
          .keyspace("ks2")
          .timeout(Duration.ofSeconds(5));
  List<String> tableList2 = db.listTableNames(options);

 }
}

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": false
    }
  }
}' | jq

Client reference

Python
TypeScript
Java
curl

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

List table names

Method signature

Result

Parameters

Examples

Client reference

Was this helpful?

Give Feedback