List collection metadata

Gets information about the collections in a keyspace.

Method signature

Python
TypeScript
Java
curl
CLI

database.list_collections(
  self,
  *,
  keyspace: str,
  max_time_ms: int,
) -> CommandCursor[CollectionDescriptor]

database.listCollections(
  options: {
    nameOnly?: boolean,
    keyspace?: string,
    maxTimeMS?: number,
  }
): Promise<string[]>

Stream<CollectionInfo> listCollections()

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
    }
  }
}'

astra db list-collections DATABASE_ID

Result

Python
TypeScript
Java
curl
CLI

Returns an iterable of CommandCursor[CollectionDescriptor] objects that describe each collection.

Example response:

[
  CollectionDescriptor(
        name='my_collection',
        options=CollectionOptions(
            vector=CollectionVectorOptions(
                dimension=3,
                metric='dot_product'
            ),
            indexing={'allow': ['field']}
        )
    ),
    CollectionDescriptor(
        name='my_collection_2',
        options=CollectionOptions(
            vector=CollectionVectorOptions(
                dimension=3,
                metric='dot_product'
            ),
            indexing={'allow': ['field']}
        )
    )
]

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

Returns a Stream<CollectionInfo>, where each CollectionInfo 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

Name Type Summary

Name	Type	Summary
`keyspace`	`Optional[str]`	the keyspace to be inspected. If not specified, the database’s working keyspace is used.
`max_time_ms`	`Optional[int]`	A timeout, in milliseconds, for the underlying HTTP request.

keyspace

Optional[str]

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

max_time_ms

Optional[int]

A timeout, in milliseconds, for the underlying HTTP request.

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.
`maxTimeMs?`	`number`	Maximum time in milliseconds the client should wait for the operation to complete.

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.

maxTimeMs?

number

Maximum time in milliseconds the client should wait for the operation to complete.

For details about each parameter, see the client reference.

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.

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("TOKEN")
database = client.get_database("API_ENDPOINT")

coll_cursor = database.list_collections()
coll_cursor  # this looks like: CommandCursor("https://....astra.datastax.com", alive)
list(coll_cursor)  # [CollectionDescriptor(name='my_v_col', ...), ...]
for coll_desc in database.list_collections():
    print(coll_desc)
# will print:
#   CollectionDescriptor(name='my_v_col', options=CollectionOptions(vector=CollectionVectorOptions(dimension=3, metric='dot_product', service=None), raw_options=...), raw_descriptor=...)
#   ...

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}'`);
  }
})();

// Given `db` Database object, list all collections
Stream<CollectionInfo> collection = listCollections();

Example:

package com.datastax.astra.client.database;

import com.datastax.astra.client.Database;
import com.datastax.astra.client.model.CollectionInfo;

import java.util.stream.Stream;

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

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

        // Get Collection information (with options)
        Stream<CollectionInfo> collections = db.listCollections();
        collections.map(CollectionInfo::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

Method signature

Result

Parameters

Examples

Client reference

Was this helpful?

Give Feedback