Get a collection

This documentation reflects client version 1.5.x. For 2.x documentation, refer to the client reference for Python, TypeScript, or Java.

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,
  *,
  keyspace: str,
  embedding_api_key: str | EmbeddingHeadersProvider,
  collection_max_time_ms: int,
) -> Collection

The following method belongs to the Db class.

collection<Schema extends SomeDoc = SomeDoc>(
  name: string,
  options?: {
    keyspace?: string,
    embeddingApiKey?: string | EmbeddingHeadersProvider | null,
    defaultMaxTimeMS?: number | null,
  }
): Collection<Schema>

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

Collection<Document> getCollection(String collectionName)

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

<T> Collection<T> getCollection(
  String collectionName,
  CommandOptions<?> commandOptions,
  @NonNull Class<T>
  documentClass
)

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.

Example response:

Collection(name="COLLECTION_NAME", keyspace="default_keyspace", database=Database(api_endpoint="ASTRA_DB_API_ENDPOINT", token="APPLICATION_TOKEN", keyspace="default_keyspace"))

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 is the user-defined type of the documents in the collection. If you provide a specific schema, operations on the collection are strongly typed. Otherwise, they are weakly typed.

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

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

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.
`keyspace`	`Optional[str]`	The keyspace containing the collection. If no keyspace is specified, the general setting for this database is used.
`embedding_api_key`	`Optional[str]`	An optional API key that is passed to the Data API with each request in the form of an `x-embedding-api-key` HTTP header. If you instantiated the collection with `embedding_api_key` or specified `authentication` in the service configuration, then the client uses that key. You can use this optional parameter to pass a different key, if needed.
`collection_max_time_ms`	`Optional[int]`	A default timeout, in milliseconds, for the duration of each operation on the collection. Individual timeouts can be provided to each collection method call and will take precedence, with this value being an overall default. Note that for some methods involving multiple API calls (such as `delete_many` and `insert_many`), you should provide a timeout with sufficient duration for the operation you’re performing.

name

str

The name of the collection.

keyspace

Optional[str]

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

embedding_api_key

Optional[str]

An optional API key that is passed to the Data API with each request in the form of an x-embedding-api-key HTTP header.

If you instantiated the collection with embedding_api_key or specified authentication in the service configuration, then the client uses that key. You can use this optional parameter to pass a different key, if needed.

collection_max_time_ms

Optional[int]

A default timeout, in milliseconds, for the duration of each operation on the collection. Individual timeouts can be provided to each collection method call and will take precedence, with this value being an overall default. Note that for some methods involving multiple API calls (such as delete_many and insert_many), you should provide a timeout with sufficient duration for the operation you’re performing.

Name Type Summary

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

collectionName

string

The name of the collection to create.

options?

CollectionSpawnOptions

The options for spawning the pre-existing collection.

Options (CollectionSpawnOptions):

Name Type Summary

Name	Type	Summary
`embeddingApiKey?`	`string`	An alternative to `service.authentication.providerKey` for the embedding provider. Provide the API key directly instead of using an API key in the Astra DB KMS. `embeddingApiKey` overrides the Astra DB KMS API key if you set both.
`defaultMaxTimeMS?`	`number`	The default `maxTimeMS` for each operation on the `Collection`.
`keyspace?`	`string`	Overrides the `keyspace` where the collection is created. If not set, the database’s working `keyspace?` is used.

embeddingApiKey?

string

An alternative to service.authentication.providerKey for the embedding provider. Provide the API key directly instead of using an API key in the Astra DB KMS. embeddingApiKey overrides the Astra DB KMS API key if you set both.

defaultMaxTimeMS?

number

The default maxTimeMS for each operation on the Collection.

keyspace?

string

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

For details about each parameter, 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.

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

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 schema 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 a specific embedding API key
  const users2 = db.collection<User>('users', {
    keyspace: 'KEYSPACE_NAME',
    embeddingApiKey: 'EMBEDDINGS_API_KEY',
  });
  await users2.insertOne({ name: 'John' });
})();

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