Get a collection

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

Python
TypeScript
Java
C#
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.

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.

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

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

By default, the Collection object is typed as Collection<Document>, where Document is Dictionary<string, object>. You can enable stronger typing by specifying a type when you get the collection. For more information and examples, see Custom typing for collections.

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
C#
curl

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.
`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. Most vectorize integrations accept a plain string for header authentication. However, some vectorize integrations and models require specialized subclasses of `EmbeddingHeadersProvider`, such as `AWSEmbeddingHeadersProvider`, for header authentication.
`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.

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.

Most vectorize integrations accept a plain string for header authentication. However, some vectorize integrations and models require specialized subclasses of EmbeddingHeadersProvider, such as AWSEmbeddingHeadersProvider, for header authentication.

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.

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

Method signature

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

Name Type Summary

Name	Type	Summary
`name`	`string`	The name of the collection.
`options`	`CollectionOptions`	Optional. The options for this operation. See Properties of `options` for more details.

name

string

The name of the collection.

options

CollectionOptions

Optional. The options for this operation. See Properties of options for more details.

Properties of `options`
Name	Type	Summary
`embeddingApiKey`	`string`	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.
`keyspace`	`string`	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.
`logging`	`string`	Optional. The configuration for logging events emitted by the DataAPIClient.
`serdes`	`string`	Optional. The configuration for serialization/deserialization 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 might 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.

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

Method signature

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,
)

Name Type Summary

Name	Type	Summary
`name`	`string`	The name of the collection.
`options`	`CollectionOptions`	Optional. The options for this operation. See Selected methods of `CollectionOptions` for more details.

name

string

The name of the collection.

options

CollectionOptions

Optional. The options for this operation. See Selected methods of CollectionOptions for more details.

Selected methods of `CollectionOptions`
Method	Parameters	Summary 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.
`embeddingAuthProvider()`	`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. Most vectorize integrations accept a plain string for header authentication. However, some vectorize integrations and models require specialized subclasses of `EmbeddingHeadersProvider` for header authentication.
`timeout()`	`long` \| `Duration`	Optional. A timeout, in milliseconds, for the underlying HTTP request. If not provided, the `Database` setting is used.

Use the GetCollection method, which belongs to the Database class.

Method signature

public Collection<Document> GetCollection(
  string collectionName, GetCollectionOptions options = null
);

public Collection<T> GetCollection<T>(
  string collectionName, GetCollectionOptions options = null
) where T : class;

public Collection<T> GetCollection<T>(
  GetCollectionOptions options = null
) where T : class;

public Collection<T, TId> GetCollection<T, TId>(
  GetCollectionOptions options = null
) where T : class;

public Collection<T, TId> GetCollection<T, TId>(
  string collectionName, GetCollectionOptions options = null
) where T : class;

Name Type Summary

Name	Type	Summary
`collectionName`	`string`	The name of the collection. If not specified, the client attempts to extract it from the `CollectionName` attribute on the custom document class if one is used. For more information and examples, see Custom typing for collections.
`options`	`GetCollectionOptions`	Optional. Options for this operation. For more information and examples for general options such as timeout and keyspace, see Customize API interaction. For options specific to this method, see Method-specific properties of the `GetCollectionOptions` class.

collectionName

string

The name of the collection.

If not specified, the client attempts to extract it from the CollectionName attribute on the custom document class if one is used. For more information and examples, see Custom typing for collections.

options

GetCollectionOptions

Optional. Options for this operation. For more information and examples for general options such as timeout and keyspace, see Customize API interaction. For options specific to this method, see Method-specific properties of the GetCollectionOptions class.

Method-specific properties of the `GetCollectionOptions` class
Name	Type	Summary
`EmbeddingAPIKey`	`string`	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.

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.

Get a collection

Python
TypeScript
Java
C#
curl

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")

Typed collections
Untyped collections

You can manually define a client-side type for your collection to help statically catch errors.

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

// Get a database
const client = new DataAPIClient();
const database = client.db("API_ENDPOINT", {
  token: "APPLICATION_TOKEN",
});

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

// Get a collection
(async function () {
  const collection = await database.collection<User>("COLLECTION_NAME");
})();

If you don’t pass a type parameter, the collection remains untyped. This is a more flexible but less type-safe option.

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

// Get a database
const client = new DataAPIClient();
const database = client.db("API_ENDPOINT", {
  token: "APPLICATION_TOKEN",
});

// Get a collection
(async function () {
  const collection = await database.collection("COLLECTION_NAME");
})();

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

public class Example {

  public static void main(String[] args) {
    // Get a database
    Database database = new DataAPIClient("APPLICATION_TOKEN").getDatabase("API_ENDPOINT");

    // Get a collection
    Collection<Document> collection = database.getCollection("COLLECTION_NAME");
  }
}

Typed collections
Untyped collections

You can manually define a client-side type for your collection to help statically catch errors. For more information and examples, see Custom typing for collections.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.SerDes;

namespace Examples;

// Define the type for the collection
[CollectionName("COLLECTION_NAME")]
public class User
{
  [DocumentId]
  public Guid? Id { get; set; }

  public string Name { get; set; } = null!;

  public int? Age { get; set; }

  [DocumentMapping(DocumentMappingField.Vectorize)]
  public string StringToVectorize => Name;
}

public class Program
{
  static void Main()
  {
    // Get a database
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );

    // Get a collection
    var collection = database.GetCollection<User>();
  }
}

If you don’t pass a type parameter, the collection or table remains untyped. This is a more flexible but less type-safe option.

using DataStax.AstraDB.DataApi;

namespace Examples;

public class Program
{
  static void Main()
  {
    // Get a database
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );

    // Get a collection
    var collection = database.GetCollection("COLLECTION_NAME");
  }
}

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.

Get a collection and specify the keyspace

Python
TypeScript
Java
C#
curl

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"
)

Typed collections
Untyped collections

You can manually define a client-side type for your collection to help statically catch errors.

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

// Get a database
const client = new DataAPIClient();
const database = client.db("API_ENDPOINT", {
  token: "APPLICATION_TOKEN",
});

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

// Get a collection
(async function () {
  const collection = await database.collection<User>("COLLECTION_NAME", {
    keyspace: "KEYSPACE_NAME",
  });
})();

If you don’t pass a type parameter, the collection remains untyped. This is a more flexible but less type-safe option.

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

// Get a database
const client = new DataAPIClient();
const database = client.db("API_ENDPOINT", {
  token: "APPLICATION_TOKEN",
});

// Get a collection
(async function () {
  const collection = await database.collection("COLLECTION_NAME", {
    keyspace: "KEYSPACE_NAME",
  });
})();

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

public class Example {

  public static void main(String[] args) {
    // Get a database
    Database database = new DataAPIClient("APPLICATION_TOKEN").getDatabase("API_ENDPOINT");

    // Get a collection
    CollectionOptions options = new CollectionOptions().keyspace("KEYSPACE_NAME");
    Collection<Document> collection = database.getCollection("COLLECTION_NAME", options);
  }
}

Typed collections
Untyped collections

You can manually define a client-side type for your collection to help statically catch errors. For more information and examples, see Custom typing for collections.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Collections;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.SerDes;

namespace Examples;

// Define the type for the collection
[CollectionName("COLLECTION_NAME")]
public class User
{
  [DocumentId]
  public Guid? Id { get; set; }

  public string Name { get; set; } = null!;

  public int? Age { get; set; }

  [DocumentMapping(DocumentMappingField.Vectorize)]
  public string StringToVectorize => Name;
}

public class Program
{
  static void Main()
  {
    // Get a database
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );

    // Get a collection
    var collection = database.GetCollection<User>(
      new GetCollectionOptions() { Keyspace = "KEYSPACE_NAME" }
    );
  }
}

If you don’t pass a type parameter, the collection or table remains untyped. This is a more flexible but less type-safe option.

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;

namespace Examples;

public class Program
{
  static void Main()
  {
    // Get a database
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );

    // Get a collection
    var collection = database.GetCollection(
      "COLLECTION_NAME",
      new GetCollectionOptions() { Keyspace = "KEYSPACE_NAME" }
    );
  }
}

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
C#
curl

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

Get a collection

Result

Parameters

Examples

Get a collection

Get a collection and specify the keyspace

Client reference

Was this helpful?

Give Feedback