Get a collection (Python)

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

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

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.

Parameters

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

Method signature

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

Alternatively, use the database["COLLECTION_NAME"] or database.COLLECTION_NAME syntax.

Name Type Summary

Name	Type	Summary
`name`	`str`	The name of the collection.
`document_type`	`type`	Optional. A formal specifier for the type checker. If provided, `document_type` must match the type hint specified in the assignment. For more information, see Typing support. Default: `Collection[dict]`
`keyspace`	`str`	Optional. The keyspace that contains the collection. For an example, see Get a collection and specify the keyspace. Default: The working keyspace for the database. This is `default_keyspace` unless you set a different working keyspace when you created the `Database` object.
`embedding_api_key`	`str \| EmbeddingHeadersProvider`	Optional. This only applies to collections with a vectorize embedding provider integration. Use this option to provide the embedding provider API key directly with headers instead of using an API key in the Astra DB KMS. The API key is sent to the Data API for every operation on the collection. It is useful when a vectorize integration is configured but no credentials are stored, or when you want to override the stored credentials. For more information, see Manage embedding provider integrations for vectorize. If you use an AWS embedding provider, the `embedding_api_key` argument must instead use the `AWSEmbeddingHeadersProvider` class to pass your access ID and secret ID.
`spawn_api_options`	`APIOptions`	Optional. A complete or partial specification of the APIOptions to override the defaults inherited from the `Database`. Use this to customize the Python client interaction with the collection. For example, you can change the serdes options or default timeouts. If `APIOptions` is passed along with a named parameter such as a timeout, the latter takes precedence over the corresponding `spawn_api_options` setting.

name

str

The name of the collection.

document_type

type

Optional. A formal specifier for the type checker. If provided, document_type must match the type hint specified in the assignment. For more information, see Typing support.

Default: Collection[dict]

keyspace

str

Optional. The keyspace that contains the collection.

For an example, see Get a collection and specify the keyspace.

Default: The working keyspace for the database. This is default_keyspace unless you set a different working keyspace when you created the Database object.

embedding_api_key

str | EmbeddingHeadersProvider

Optional. This only applies to collections with a vectorize embedding provider integration.

Use this option to provide the embedding provider API key directly with headers instead of using an API key in the Astra DB KMS.

The API key is sent to the Data API for every operation on the collection. It is useful when a vectorize integration is configured but no credentials are stored, or when you want to override the stored credentials. For more information, see Manage embedding provider integrations for vectorize.

If you use an AWS embedding provider, the embedding_api_key argument must instead use the AWSEmbeddingHeadersProvider class to pass your access ID and secret ID.

spawn_api_options

APIOptions

Optional. A complete or partial specification of the APIOptions to override the defaults inherited from the Database. Use this to customize the Python client interaction with the collection. For example, you can change the serdes options or default timeouts. If APIOptions is passed along with a named parameter such as a timeout, the latter takes precedence over the corresponding spawn_api_options setting.

Examples

The following examples demonstrate how to get a collection.

Get a collection

The following example uses untyped documents or rows, but you can define a client-side type for your collection to help statically catch errors. For examples, see Typing support.

from astrapy import DataAPIClient

# Get a database
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Get a collection
collection = database.get_collection("COLLECTION_NAME")

Get a collection and specify the keyspace

The following example uses untyped documents or rows, but you can define a client-side type for your collection to help statically catch errors. For examples, see Typing support.

from astrapy import DataAPIClient

# Get a database
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)

# Get a collection
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

Client reference

For more information, see the client reference.

Get a collection (Python)

Result

Parameters

Examples

Get a collection

Get a collection and specify the keyspace

Client reference

Was this helpful?

Give Feedback