List collection metadata

Gets information about the collections in a keyspace.

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
CLI

Returns a list of CollectionDescriptor objects that describe each collection.

Example response:

[
  CollectionDescriptor(
    name='my_collection',
    definition=CollectionDefinition(
      indexing={'allow': ['country', 'city']}
    ),
    raw_descriptor=...
  ),
  CollectionDescriptor(
    name='my_vector_collection',
    definition=CollectionDefinition(
      vector=CollectionVectorOptions(
        dimension=3,
        metric='dot_product',
        source_model='other',
        service=None
      ),
    ),
    raw_descriptor=...
  )
]

Returns a promise that resolves to an array of CollectionDescriptor objects that describe each collection.

Returns a List<CollectionDescriptor>, where each CollectionDescriptor object describes a collection.

The status.collections field in the response describes each collection.

Example response:

{
  "status" : {
    "collections" : [
      {
        "name" : "student_collection",
        "options" : {
          "defaultId": {
            "type": "objectId"
          },
          "vector" : {
            "dimension" : 5,
            "metric" : "cosine"
          }
        }
      },
      {
        "name" : "book_collection",
        "options" : {
          "defaultId": {
            "type": "objectId"
          },
          "vector" : {
            "dimension" : 5,
            "metric" : "cosine"
          }
        }
      }
    ]
  }
}

Prints details about each collection.

Example response:

+---------------------+-----------+-------------+
| Name                | Dimension | Metric      |
+---------------------+-----------+-------------+
| collection_simple   |           |             |
| collection_vector   | 14        | cosine      |
| msp                 | 1536      | dot_product |
+---------------------+-----------+-------------+

Parameters

Python
TypeScript
Java
curl
CLI

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

Method signature

list_collections(
  *,
  keyspace: str,
  collection_admin_timeout_ms: int,
  request_timeout_ms: int,
  timeout_ms: int,
) -> list[CollectionDescriptor]

Name Type Summary

Name	Type	Summary
`keyspace`	`str`	the keyspace to be inspected. If not specified, the database’s working keyspace is used.
`collection_admin_timeout_ms`	`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

str

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

collection_admin_timeout_ms

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.

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

Method signature

async listCollections(
  options: {
    nameOnly?: false,
    keyspace?: string,
    timeout?: number | TimeoutDescriptor,
  }
): CollectionDescriptor[]

Name Type Summary

Name	Type	Summary
`options`	`ListCollectionsOptions`	Options regarding listing collections.

options

ListCollectionsOptions

Options regarding listing collections.

Options (ListCollectionsOptions):

Name Type Summary

Name	Type	Summary
`nameOnly?`	`false`	If true, only the name of the collection is returned. Else, the full information for each collection is returned. Defaults to true.
`keyspace?`	`string`	The keyspace to be inspected. If not specified, the database’s working keyspace is used.
`timeout`	`number` \| `TimeoutDescriptor`	Optional. The timeout(s) to apply to this method. You can specify `requestTimeoutMs` and `collectionAdminTimeoutMs`. Details about the `timeout` parameter The `TimeoutDescriptor` object can contain these properties: `requestTimeoutMs` (`number`): The maximum time, in milliseconds, that the client should wait for each underlying HTTP request. Default: The default value for the collection. This default is 10 seconds unless you specified a different default when you initialized the `Collection` or `DataAPIClient` object. `collectionAdminTimeoutMs` (`number`): The maximum time, in milliseconds, for collection admin operations like creating, dropping, and listing collections. Default: The default value for the collection. This default is 60 seconds unless you specified a different default when you initialized the `Collection` or `DataAPIClient` object. If you specify a number instead of a `TimeoutDescriptor` object, that number will be applied to both `requestTimeoutMs` and `collectionAdminTimeoutMs`.

nameOnly?

false

If true, only the name of the collection is returned. Else, the full information for each collection is returned. Defaults to true.

keyspace?

string

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

timeout

number | TimeoutDescriptor

Optional.

The timeout(s) to apply to this method. You can specify requestTimeoutMs and collectionAdminTimeoutMs.

Details about the timeout parameter

The TimeoutDescriptor object can contain these properties:

requestTimeoutMs (number): The maximum time, in milliseconds, that the client should wait for each underlying HTTP request. Default: The default value for the collection. This default is 10 seconds unless you specified a different default when you initialized the Collection or DataAPIClient object.
collectionAdminTimeoutMs (number): The maximum time, in milliseconds, for collection admin operations like creating, dropping, and listing collections. Default: The default value for the collection. This default is 60 seconds unless you specified a different default when you initialized the Collection or DataAPIClient object.

If you specify a number instead of a TimeoutDescriptor object, that number will be applied to both requestTimeoutMs and collectionAdminTimeoutMs.

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

Method signature

List<CollectionDescriptor> listCollections()

For details about each parameter, see the client reference.

Use the findCollections command.

Command signature

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 '{
  "findCollections": {
    "options": {
      "explain": true
    }
  }
}'

Name Type Summary

Name	Type	Summary
`findCollections`	`command`	The Data API command to find all collections in the specified database and keyspace. It acts as a container for all the attributes and settings required to find collections.
`options.explain`	`boolean`	If true, the response includes collection names and a brief explanation of metadata for each collection, such as `vector`, `dimension`, `metric`, `defaultId`, and `indexing`. If false or unset, the response includes only collection names.

findCollections

command

The Data API command to find all collections in the specified database and keyspace. It acts as a container for all the attributes and settings required to find collections.

options.explain

boolean

If true, the response includes collection names and a brief explanation of metadata for each collection, such as vector, dimension, metric, defaultId, and indexing. If false or unset, the response includes only collection names.

Command signature

astra db list-collections DATABASE_ID

Name Type Summary

Name	Type	Summary
`DATABASE_ID`	`String`	To get the `DATABASE_ID`, see Get your database ID.

DATABASE_ID

String

To get the DATABASE_ID, see Get your database ID.

Examples

The following examples demonstrate how to get collection metadata.

Python
TypeScript
Java
curl
CLI

collection_iterable = database.list_collections()

Example:

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

collection_descriptors = database.list_collections()
# this looks like: [CollectionDescriptor(name='my_collection', definition=CollectionDefinition(...)), ...]

for coll_desc in database.list_collections():
    print(coll_desc)
# will print:
#   CollectionDescriptor(name='my_collection', definition=CollectionDefinition(...))
#   ...

const collections = await db.listCollections();

Example:

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

// Get a new Db instance
const db = new DataAPIClient('TOKEN').db('API_ENDPOINT');

(async function () {
  // Gets full info about all collections in db
  const collections = await db.listCollections();

  for (const collection of collections) {
    console.log(`Collection '${collection.name}' has default ID type '${collection.options.defaultId?.type}'`);
  }
})();

Example:

package com.datastax.astra.client.database;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.collections.definition.CollectionDescriptor;
import com.datastax.astra.client.databases.Database;

import java.util.List;

public class ListCollections {
    public static void main(String[] args) {
        Database db = new DataAPIClient("TOKEN")
                .getDatabase("API_ENDPOINT");

        // Get collection Names
        List<String> collectionNames = db.listCollectionNames();

        // Get Collection information (with options)
        List<CollectionDescriptor> collections = db.listCollections();
        collections.stream().map(CollectionDescriptor::getOptions).forEach(System.out::println);
    }
}

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 '{
  "findCollections": {
    "options": {
      "explain": true
    }
  }
}' | jq

astra db list-collections DATABASE_ID

Client reference

Python
TypeScript
Java
curl
CLI

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

For more information, see the Astra CLI documentation.

List collection metadata

Result

Parameters

Examples

Client reference

Was this helpful?

Give Feedback