Get a collection

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

Method signature

Python
TypeScript
Java
curl

The following method belongs to the astrapy.Database class.

get_collection(
  name: str,
  *,
  document_type: type[Any],
  keyspace: str,
  embedding_api_key: str | EmbeddingHeadersProvider,
  spawn_api_options: APIOptions,
) -> Collection

The following method belongs to the Db class.

collection <Schema extends SomeDoc = SomeDoc>(
  name: string,
  options?: {
    keyspace?: string,
    logging?: DataAPILoggingConfig,
    serdes?: CollectionSerDesConfig,
    embeddingApiKey?: string | EmbeddingHeadersProvider,
    timeoutDefaults?: TimeoutDescriptor,
  }
): Collection<Schema>

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

Collection<Document> getCollection(String collectionName)

Collection<Document> getCollection(
  String collectionName,
  CollectionOptions options
)

<T> Collection<T> getCollection(
  String collectionName,
  Class<T> documentClass
)

<T> Collection<T> getCollection(
  String collectionName,
  Class<T> documentClass
  CollectionOptions options,
)

This method has no literal equivalent in HTTP. Instead, you specify the collection in the path, if required.

To get information about collections in a database, see List collection metadata.

Result

Python
TypeScript
Java
curl

Returns a Collection object that corresponds to the specified collection name.

This method returns a Collection object even for collections that don’t exist.

Unless you specify the document_type parameter, the collection is typed as Collection[dict].

For more information, see Typing support.

Example response:

Collection(name="COLLECTION_NAME", keyspace="default_keyspace", database.api_endpoint="ASTRA_DB_API_ENDPOINT", api_options=FullAPIOptions(token=StaticTokenProvider("APPLICATION_TOKEN"...), ...))

Returns a Collection<Schema> object that corresponds to the specified collection name.

This method returns a Collection object even for collections that don’t exist.

A Collection is typed as Collection<Schema>, where Schema defaults to SomeDoc (Record<string, any>). Providing the specific Schema type enables stronger typing for collection operations. For more information, see Typing Collections and Tables.

Returns a Collection<T> object that corresponds to the specified collection name.

This method returns a Collection<T> object even for collections that don’t exist.

A Collection is typed as Collection<T>, where T defaults to Document which can be seen as a generic map of String to Object.

Providing the specific T type enables stronger typing for collection operations. (eg: Collecion<MyBean>) For more information see the client reference.

This method has no literal equivalent in HTTP. Instead, you specify the collection in the path, if required.

To get information about collections in a database, see List collection metadata.

Parameters

Python
TypeScript
Java
curl

Name Type Summary

Name	Type	Summary
`name`	`str`	The name of the collection.
`document_type`	`type`	This parameter acts a formal specifier for the type checker. If omitted, the resulting `Collection` is implicitly a `Collection[dict]`. If provided, `document_type` must match the type hint specified in the assignment. For more information, see Typing support.
`keyspace`	`str`	The keyspace containing the collection. If no keyspace is specified, the general setting for this database is used.
`embedding_api_key`	`str \| EmbeddingHeadersProvider`	Optional parameter for collections with a vectorize embedding provider integration. If passed, this secret is sent to the Data API with each operation on the collection: as such, it is useful when a vectorize service is configured but no credentials are stored with it (or when one wants to override the stored credentials). For more information, see Embedding generation methods.
`spawn_api_options`	`APIOptions`	A complete or partial specification of the APIOptions to override the defaults inherited from the `Database`. This allows customizing the client interaction with the collection: for example, changing the serdes options. If `APIOptions` is passed together with a named parameter (such as an embedding API key), the latter takes precedence over the corresponding `spawn_api_options` setting.

name

str

The name of the collection.

document_type

type

This parameter acts a formal specifier for the type checker. If omitted, the resulting Collection is implicitly a Collection[dict]. If provided, document_type must match the type hint specified in the assignment. For more information, see Typing support.

keyspace

str

The keyspace containing the collection. If no keyspace is specified, the general setting for this database is used.

embedding_api_key

str | EmbeddingHeadersProvider

Optional parameter for collections with a vectorize embedding provider integration. If passed, this secret is sent to the Data API with each operation on the collection: as such, it is useful when a vectorize service is configured but no credentials are stored with it (or when one wants to override the stored credentials). For more information, see Embedding generation methods.

spawn_api_options

APIOptions

A complete or partial specification of the APIOptions to override the defaults inherited from the Database. This allows customizing the client interaction with the collection: for example, changing the serdes options. If APIOptions is passed together with a named parameter (such as an embedding API key), the latter takes precedence over the corresponding spawn_api_options setting.

Name Type Summary

Name	Type	Summary
`name`	`string`	The name of the collection to create.
`options?`	`CollectionOptions`	The options for spawning the pre-existing collection.

name

string

The name of the collection to create.

options?

CollectionOptions

The options for spawning the pre-existing collection.

Options (CollectionOptions):

Name Type Summary

Name	Type	Summary
`embeddingApiKey?`	`string`	An alternative to `service.authentication.providerKey` for the embedding provider. Provides the API key directly via headers instead of using an API key in the Astra DB KMS. `embeddingApiKey` overrides the Astra DB KMS API key if you set both.
`keyspace?`	`string`	Overrides the `keyspace` where the collection is created. If not set, the database’s working `keyspace` is used.
`logging?`	`string`	The configuration for logging events emitted by the DataAPIClient.
`serdes?`	`string`	The configuration for logging events emitted by the DataAPIClient. For more information, see Custom Ser/Des
`timeoutDefaults`	`TimeoutDescriptor`	Optional. The default timeout(s) to apply to operations performed on this Collection instance. You can specify `requestTimeoutMs`, `generalMethodTimeoutMs`, and `collectionAdminTimeoutMs`. Details about the `timeoutDefaults` parameter The default timeout options for any operation performed on this Collection instance. 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: 10 seconds. `generalMethodTimeoutMs` (`number`): The maximum time, in milliseconds, that the whole operation, which may involve multiple HTTP requests, can take. Default: 30 seconds. `collectionAdminTimeoutMs` (`number`): The maximum time, in milliseconds, for collection admin operations like creating, dropping, and listing collections. Default: 60 seconds.

embeddingApiKey?

string

An alternative to service.authentication.providerKey for the embedding provider.

Provides the API key directly via headers instead of using an API key in the Astra DB KMS.

embeddingApiKey overrides the Astra DB KMS API key if you set both.

keyspace?

string

Overrides the keyspace where the collection is created. If not set, the database’s working keyspace is used.

logging?

string

The configuration for logging events emitted by the DataAPIClient.

serdes?

string

The configuration for logging events emitted by the DataAPIClient.

For more information, see Custom Ser/Des

timeoutDefaults

TimeoutDescriptor

Optional.

The default timeout(s) to apply to operations performed on this Collection instance. You can specify requestTimeoutMs, generalMethodTimeoutMs, and collectionAdminTimeoutMs.

Details about the timeoutDefaults parameter

The default timeout options for any operation performed on this Collection instance.

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: 10 seconds.
generalMethodTimeoutMs (number): The maximum time, in milliseconds, that the whole operation, which may involve multiple HTTP requests, can take. Default: 30 seconds.
collectionAdminTimeoutMs (number): The maximum time, in milliseconds, for collection admin operations like creating, dropping, and listing collections. Default: 60 seconds.

For details about each parameter, see the client reference.

Name Type Summary

Name	Type	Summary
`name`	`string`	The name of the collection to create.
`options?`	`CollectionOptions`	The options for spawning the pre-existing collection.

name

string

The name of the collection to create.

options?

CollectionOptions

The options for spawning the pre-existing collection.

Options (CollectionOptions) will inherit all properties from the base class BaseOptions` plus the following:

Name Type Summary

Name	Type	Summary
`keyspace`	`string`	Overrides the `keyspace` where the collection is created. If not set, the database’s working `keyspace` is used.

keyspace

string

Overrides the keyspace where the collection is created. If not set, the database’s working keyspace is used.

This method has no literal equivalent in HTTP. Instead, you specify the collection in the path, if required.

To get information about collections in a database, see List collection metadata.

Examples

The following examples demonstrate how to get a collection.

Python
TypeScript
Java
curl

collection = database.get_collection("COLLECTION_NAME")

The example above is equivalent to these two alternate notations:

collection1 = database["COLLECTION_NAME"]
collection2 = database.COLLECTION_NAME

Most astrapy objects have an asynchronous counterpart, for use within the asyncio framework. To get an AsyncCollection, use the get_collection method of instances of AsyncDatabase, or alternatively the to_async method of the synchronous Collection class.

See the AsyncCollection Client reference for details about the async API.

Example:

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

collection = database.get_collection("COLLECTION_NAME")
collection.count_documents({}, upper_bound=100)  # will print e.g.: 41

const collection = db.collection('COLLECTION_NAME');

Example:

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

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

// Define the type for the collection
interface User {
  name: string,
  age?: number,
}

(async function () {
  // Basic untyped collection
  const users1 = db.collection('users');
  await users1.insertOne({ name: 'John' });

  // Typed collection from different keyspace with basic logging options
  const users2 = db.collection<User>('users', {
    keyspace: 'KEYSPACE_NAME',
    logging: 'all',
  });
  await users2.insertOne({ name: 'John' });
})();

Example:

package com.datastax.astra.client.database;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.CollectionDefinition;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.databases.Database;

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

    // Find a collection
    Collection<Document> collection = db.getCollection("collection_vector1");

    // Gather collection information
    CollectionDefinition options = collection.getDefinition();

    // Check if a collection exists
    boolean collectionExists = db.getCollection("collection_vector2").exists();
  }
}

This method has no literal equivalent in HTTP. Instead, you specify the collection in the path, if required.

To get information about collections in a database, see List collection metadata.

Client reference

Python
TypeScript
Java
curl

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

Get a collection

Method signature

Result

Parameters

Examples

Client reference

Was this helpful?

Give Feedback