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
-
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="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
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 |
---|---|---|
|
|
The name of the collection. |
|
|
Optional.
A formal specifier for the type checker.
If provided, Default: |
|
|
Optional. The keyspace that contains the collection. Default: The working keyspace for the database. |
|
|
Optional. This only applies to collections with a vectorize embedding provider integration. Use this option to provide the 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 service is configured but no credentials are stored, or when you want to override the stored credentials. For more information, see Auto-generate embeddings with vectorize. |
|
|
Optional.
A complete or partial specification of the APIOptions to override the defaults inherited from the |
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 |
---|---|---|
|
|
The name of the collection. |
|
Optional.
The options for this operation.
See Properties of |
Name | Type | Summary |
---|---|---|
|
Optional. This only applies to collections with a vectorize embedding provider integration. Use this option to provide the 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 service is configured but no credentials are stored, or when you want to override the stored credentials. For more information, see Auto-generate embeddings with vectorize. |
|
|
Optional. The keyspace that contains the collection. Default: The working keyspace for the database. |
|
|
Optional. The configuration for logging events emitted by the DataAPIClient. |
|
|
Optional. The configuration for serialization/deserialization by the DataAPIClient. For more information, see Custom Ser/Des. |
|
|
Optional. The default timeout(s) to apply to operations performed on this Collection instance.
You can specify Details about the
|
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 |
---|---|---|
|
|
The name of the collection. |
|
Options for the operation, including the keyspace. |
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
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("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
// 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("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
// 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");
}
}
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.
For more information, see the client reference.
For more information, see the client reference.
Client reference documentation is not applicable for HTTP.