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 |
---|---|---|
|
|
The name of the collection. |
|
|
This parameter acts a formal specifier for the type checker.
If omitted, the resulting |
|
|
The keyspace containing the collection. If no keyspace is specified, the general setting for this database is used. |
|
|
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. |
|
|
A complete or partial specification of the APIOptions to override the defaults inherited from the |
Name | Type | Summary |
---|---|---|
|
|
The name of the collection to create. |
|
The options for spawning the pre-existing collection. |
Options (CollectionOptions
):
Name | Type | Summary |
---|---|---|
|
An alternative to Provides the API key directly via headers instead of using an API key in the Astra DB KMS.
|
|
|
Overrides the |
|
|
The configuration for logging events emitted by the DataAPIClient. |
|
|
The configuration for logging events emitted 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
|
For details about each parameter, see the client reference.
Name | Type | Summary |
---|---|---|
|
|
The name of the collection to create. |
|
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 |
---|---|---|
|
|
Overrides the |
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 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.
For more information, see the client reference.
For more information, see the client reference.
Client reference documentation is not applicable for HTTP.