A `count_documents()` operation failed because the resulting number of documents
exceeded either the upper bound set by the caller or the hard limit imposed
by the Data API.

TooManyDocumentsToCountException

text

a text message about the exception.

True if the count limit imposed by the API
is reached. In that case, increasing the upper bound in the method
invocation is of no help.


server_max_count_exceeded: bool = server_max_count_exceeded


The Data API response is malformed in that it does not have
expected field(s), or they are of the wrong type.

DataAPIFaultyResponseException

text

a text message about the exception.

the response returned by the API in the form of a dict.


raw_response: dict[str, Any] | None = raw_response


The Data API returned an HTTP 200 success response, which however
reports about API-specific error(s), possibly alongside partial successes.

This exception is related to an operation that can have spanned several
HTTP requests in sequence (e.g. a chunked insert_many). For this
reason, it should be not thought as being in a 1:1 relation with
actual API requests, rather with operations invoked by the user,
such as the methods of the Collection object.

DataAPIResponseException

text

a text message about the exception.

a list of all DataAPIErrorDescriptor objects
found across all requests involved in this exception, which are
possibly more than one.

a list of DataAPIDetailedErrorDescriptor
objects, one for each of the requests performed during this operation.
For single-request methods, such as insert_one, this list always
has a single element.


error_descriptors: list[DataAPIErrorDescriptor] = error_descriptors


detailed_error_descriptors: list[DataAPIDetailedErrorDescriptor] = detailed_error_descriptors


Parse a raw response from the API into this exception.


Parse a list of raw responses from the API into this exception.


Cast the exception, whatever the subclass, into this parent superclass.


An exception of type DataAPIResponseException (see) occurred
during an operation that in general spans several requests.
As such, besides information on the error, it may have accumulated
a partial result from past successful Data API requests.

CumulativeOperationException

text

a text message about the exception.

an OperationResult object, just like the one that would
be the return value of the operation, had it succeeded completely.


An exception of type DataAPIResponseException (see) occurred
during an insert_many (that in general spans several requests).
As such, besides information on the error, it may have accumulated
a partial result from past successful Data API requests.

InsertManyException

text

a text message about the exception.

an InsertManyResult object, just like the one that would
be the return value of the operation, had it succeeded completely.


partial_result: InsertManyResult = partial_result


An exception of type DataAPIResponseException (see) occurred
during a delete_many (that in general spans several requests).
As such, besides information on the error, it may have accumulated
a partial result from past successful Data API requests.

DeleteManyException

text

a text message about the exception.

a DeleteResult object, just like the one that would
be the return value of the operation, had it succeeded completely.


partial_result: DeleteResult = partial_result


An exception of type DataAPIResponseException (see) occurred
during an update_many (that in general spans several requests).
As such, besides information on the error, it may have accumulated
a partial result from past successful Data API requests.

UpdateManyException

text

a text message about the exception.

an UpdateResult object, just like the one that would
be the return value of the operation, had it succeeded completely.


partial_result: UpdateResult = partial_result


An exception of type DataAPIResponseException (see) occurred
during a bulk_write of a list of operations.
As such, besides information on the error, it may have accumulated
a partial result from past successful operations.

BulkWriteException

text

a text message about the exception.

a list of all DataAPIErrorDescriptor objects
found across all requests involved in the first
operation that has failed.

a list of DataAPIDetailedErrorDescriptor
objects, one for each of the requests performed during the first operation
that has failed.

a BulkWriteResult object, just like the one that would
be the return value of the operation, had it succeeded completely.

exceptions

a list of DataAPIResponseException objects, one for each
operation in the bulk that has failed. This information is made
available here since the top-level fields of this error
only surface the first such failure that is detected across the bulk.
In case of bulk_writes with ordered=True, this trivially contains
a single element, the same described by the top-level fields
text, error_descriptors and detailed_error_descriptors.


partial_result: BulkWriteResult = partial_result


exceptions

exceptions: list[DataAPIResponseException] = exceptions


A helper class to keep track of timing and timeouts
in a multi-call method context.

MultiCallTimeoutManager

an optional max duration to track (milliseconds)

timestamp of the instance construction (milliseconds)

optional deadline in milliseconds (computed by the class).


overall_max_time_ms: int | None = overall_max_time_ms


started_ms: int = int(time.time() * 1000)


Ensure the deadline, if any, is not yet in the past.
If it is, raise an appropriate timeout error.
If not, return either None (if no timeout) or the remaining milliseconds.
For use within the multi-call method.


Ensure the deadline, if any, is not yet in the past.
If it is, raise an appropriate timeout error.
It it is not, or there is no deadline, return a suitable TimeoutInfo
for use within the multi-call method.


API_PATH_ENV_MAP = {DATA_API_ENVIRONMENT_PROD: '/api/json', DATA_API_ENVIRONMENT_DEV: '/api/json', DATA_API_ENVIRONMENT_TEST: '/api/json', DATA_API_ENVIRONMENT_DSE: '', DATA_API_ENVIRONMENT_HCD: '', DATA_API_ENVIRONMENT_CASSANDRA: '', DATA_API_ENVIRONMENT_OTHER: ''}


API_VERSION_ENV_MAP = {DATA_API_ENVIRONMENT_PROD: '/v1', DATA_API_ENVIRONMENT_DEV: '/v1', DATA_API_ENVIRONMENT_TEST: '/v1', DATA_API_ENVIRONMENT_DSE: 'v1', DATA_API_ENVIRONMENT_HCD: 'v1', DATA_API_ENVIRONMENT_CASSANDRA: 'v1', DATA_API_ENVIRONMENT_OTHER: 'v1'}


DEV_OPS_URL_ENV_MAP = {DATA_API_ENVIRONMENT_PROD: 'https://api.astra.datastax.com', DATA_API_ENVIRONMENT_DEV: 'https://api.dev.cloud.datastax.com', DATA_API_ENVIRONMENT_TEST: 'https://api.test.cloud.datastax.com'}


DEV_OPS_VERSION_ENV_MAP = {DATA_API_ENVIRONMENT_PROD: 'v2', DATA_API_ENVIRONMENT_DEV: 'v2', DATA_API_ENVIRONMENT_TEST: 'v2'}


DEFAULT_REDACTED_HEADER_NAMES = {DEFAULT_DATA_API_AUTH_HEADER, DEFAULT_DEV_OPS_AUTH_HEADER, EMBEDDING_HEADER_AWS_ACCESS_ID, EMBEDDING_HEADER_AWS_SECRET_ID, EMBEDDING_HEADER_API_KEY}


NAMESPACE_DEPRECATION_NOTICE_METHOD = "The term 'namespace' is being replaced by 'keyspace' throughout the Data API and the clients. Please adapt method and parameter names consistently (examples: `db_admin.findNamespaces` => `db_admin.findKeyspaces`; `collection.namespace` => `collection.keyspace`; `database.list_collections(namespace=...)` => `database.list_collections(keyspace=...)`). See https://docs.datastax.com/en/astra-db-serverless/api-reference/client-versions.html#version-1-5 for more information."


NAMESPACE_DEPRECATION_NOTICE_UPDATEDBNS_SUBJECT = 'Parameter `update_db_namespace`'


NAMESPACE_DEPRECATION_NOTICE_UPDATEDBNS_DETAILS = 'Please replace the parameter with `update_db_keyspace`. See https://docs.datastax.com/en/astra-db-serverless/api-reference/client-versions.html#version-1-5 for more information.'


NAMESPACE_DEPRECATION_NOTICE_NS_SUBJECT = 'Parameter `namespace`'


NAMESPACE_DEPRECATION_NOTICE_NS_DETAILS = 'Please replace the parameter with `keyspace`. See https://docs.datastax.com/en/astra-db-serverless/api-reference/client-versions.html#version-1-5 for more information.'


SET_CALLER_DEPRECATION_NOTICE = 'Please provide the caller(s) at constructor time through the `callers` list parameter.'


CALLER_NAME_VERSION_DEPRECATION_NOTICE_DETAILS = "Please pass any caller identities as the `callers` constructor parameter: `callers=[('cname1', 'cversion1'), ('cname2', 'cversion2'), ...]`."


caller_header: dict[str, str] = {'User-Agent': full_user_agent_string} if full_user_agent_string else {}


full_headers: dict[str, str] = {None: {k: vfor (k, v) in self.headers.items() if v is not None}, None: self.caller_header, None: {'Content-Type': 'application/json'}}


full_path = '/'.join([self.api_endpoint, self.path]).rstrip('/')


Represents the identifying information for a database,
including the region the connection is established to.

DatabaseInfo

id

the database ID.

region

the ID of the region through which the connection to DB is done.

keyspace

the namespace this DB is set to work with. None if not set.

namespace

an alias for 'keyspace'. *DEPRECATED*, removal in 2.0

name

the database name. Not necessarily unique: there can be multiple
databases with the same name.

environment

a label, whose value can be `Environment.PROD`,
or another value in `Environment.*`.

the full response from the DevOPS API call to get this info.

The `raw_info` dictionary usually has a `region` key describing
the default region as configured in the database, which does not
necessarily (for multi-region databases) match the region through
which the connection is established: the latter is the one specified
by the "api endpoint" used for connecting. In other words, for multi-region
databases it is possible that
    database_info.region != database_info.raw_info["region"]
Conversely, in case of a DatabaseInfo not obtained through a
connected database, such as when calling `Admin.list_databases()`,
all fields except `environment` (e.g. keyspace, region, etc)
are set as found on the DevOps API response directly.


Represents the full response from the DevOps API about a database info.

Most attributes just contain the corresponding part of the raw response:
for this reason, please consult the DevOps API documentation for details.

AdminDatabaseInfo

info

a DatabaseInfo instance for the underlying database.
The DatabaseInfo is a subset of the information described by
AdminDatabaseInfo - in terms of the DevOps API response,
it corresponds to just its "info" subdictionary.

the "availableActions" value in the full API response.

cost

the "cost" value in the full API response.

the "cqlshUrl" value in the full API response.

the "creationTime" value in the full API response.

the "dataEndpointUrl" value in the full API response.

the "grafanaUrl" value in the full API response.

the "graphqlUrl" value in the full API response.

id

the "id" value in the full API response.

the "lastUsageTime" value in the full API response.

metrics

the "metrics" value in the full API response.

the "observedStatus" value in the full API response.

the "orgId" value in the full API response.

the "ownerId" value in the full API response.

status

the "status" value in the full API response.

storage

the "storage" value in the full API response.

the "terminationTime" value in the full API response.

the full raw response from the DevOps API.


Represents the identifying information for a collection,
including the information about the database the collection belongs to.

CollectionInfo

a DatabaseInfo instance for the underlying database.

keyspace

the keyspace where the collection is located.

namespace

an alias for 'keyspace'. *DEPRECATED*, removal in 2.0

name

collection name. Unique within a keyspace.

identifier for the collection within the database,
in the form "keyspace.collection_name".


The "defaultId" component of the collection options.
See the Data API specifications for allowed values.

CollectionDefaultIDOptions

string such as `objectId`, `uuid6` and so on.


Recast this object into a dictionary.


Create an instance of CollectionDefaultIDOptions from a dictionary
such as one from the Data API.


The "vector.service" component of the collection options.
See the Data API specifications for allowed values.

CollectionVectorServiceOptions

provider

the name of a service provider for embedding calculation.

the name of a specific model for use by the service.

authentication

a key-value dictionary for the "authentication" specification,
if any, in the vector service options.

parameters

a key-value dictionary for the "parameters" specification, if any,
in the vector service options.


authentication

authentication: dict[str, Any] | None = None


parameters

parameters: dict[str, Any] | None = None


Create an instance of CollectionVectorServiceOptions from a dictionary
such as one from the Data API.


The "vector" component of the collection options.
See the Data API specifications for allowed values.

CollectionVectorOptions

dimension

an optional positive integer, the dimensionality of the vector space.

metric

an optional metric among `VectorMetric.DOT_PRODUCT`,
`VectorMetric.EUCLIDEAN` and `VectorMetric.COSINE`.

service

an optional CollectionVectorServiceOptions object in case a
service is configured for the collection.


service

service: CollectionVectorServiceOptions | None


Create an instance of CollectionVectorOptions from a dictionary
such as one from the Data API.


A structure expressing the options of a collection.
See the Data API specifications for detailed specification and allowed values.

CollectionOptions

vector

an optional CollectionVectorOptions object.

indexing

an optional dictionary with the "indexing" collection properties.

an optional CollectionDefaultIDOptions object.

the raw response from the Data API for the collection configuration.


default_id: CollectionDefaultIDOptions | None


Recast this object as a flat key-value pair suitable for
use as kwargs in a create_collection method call (including recasts).


Create an instance of CollectionOptions from a dictionary
such as one from the Data API.


A structure expressing full description of a collection as the Data API
returns it, i.e. its name and its `options` sub-structure.

CollectionDescriptor

name

the name of the collection.

options

a CollectionOptions instance.

the raw response from the Data API.


Recast this object into a dictionary.
Empty `options` will not be returned at all.


Create an instance of CollectionDescriptor from a dictionary
such as one from the Data API.


A representation of a parameter as returned by the 'findEmbeddingProviders'
Data API endpoint.

EmbeddingProviderParameter

the default value for the parameter.

help

a textual description of the parameter.

name

the name to use when passing the parameter for vectorize operations.

required

whether the parameter is required or not.

a textual description of the data type for the parameter.

validation

a dictionary describing a parameter-specific validation policy.


Recast this object into a dictionary.


Create an instance of EmbeddingProviderParameter from a dictionary
such as one from the Data API.


A representation of an embedding model as returned by the 'findEmbeddingProviders'
Data API endpoint.

EmbeddingProviderModel

name

the model name as must be passed when issuing
vectorize operations to the API.

parameters

a list of the `EmbeddingProviderParameter` objects the model admits.

an integer for the dimensionality of the embedding model.
if this is None, the dimension can assume multiple values as specified
by a corresponding parameter listed with the model.


Create an instance of EmbeddingProviderModel from a dictionary
such as one from the Data API.


A representation of a "token", that is a specific secret string, needed by
an embedding model; this models a part of the response from the
'findEmbeddingProviders' Data API endpoint.

EmbeddingProviderToken

accepted

the name of this "token" as seen by the Data API. This is the
name that should be used in the clients when supplying the secret,
whether as header or by shared-secret.

forwarded

the name used by the API when issuing the embedding request
to the embedding provider. This is of no direct interest for the Data API user.


Create an instance of EmbeddingProviderToken from a dictionary
such as one from the Data API.


A representation of an authentication mode for using an embedding model,
modeling the corresponding part of the response returned by the
'findEmbeddingProviders' Data API endpoint (namely "supportedAuthentication").

EmbeddingProviderAuthentication

enabled

whether this authentication mode is available for a given model.

tokens

a list of `EmbeddingProviderToken` objects,
detailing the secrets required for the authentication mode.


Create an instance of EmbeddingProviderAuthentication from a dictionary
such as one from the Data API.


A representation of an embedding provider, as returned by the 'findEmbeddingProviders'
Data API endpoint.

EmbeddingProvider

a version of the provider name for display and pretty printing.
Not to be used when issuing vectorize API requests (for the latter, it is
the key in the providers dictionary that is required).

models

a list of `EmbeddingProviderModel` objects pertaining to the provider.

parameters

a list of `EmbeddingProviderParameter` objects common to all models
for this provider.

a dictionary of the authentication modes for
this provider. Note that disabled modes may still appear in this map,
albeit with the `enabled` property set to False.

url

a string template for the URL used by the Data API when issuing the request
toward the embedding provider. This is of no direct concern to the Data API user.


Create an instance of EmbeddingProvider from a dictionary
such as one from the Data API.


A representation of the whole response from the 'findEmbeddingProviders'
Data API endpoint.

FindEmbeddingProvidersResult

a dictionary of provider names to EmbeddingProvider objects.

a (nested) dictionary containing the original full response from the endpoint.


Create an instance of FindEmbeddingProvidersResult from a dictionary
such as one from the Data API.


Log the details of an HTTP request for debugging purposes.

the HTTP verb of the request (e.g. "POST").

the URL of the request (e.g. "https://domain.com/full/path").

parameters of the request.

caution, as these will be logged as they are.

payload

The payload sent with the request, if any.


Log the details of an httpx.Response.

response

the httpx.Response object to log.


TimeoutInfoWideType

TimeoutInfoWideType = Union[TimeoutInfo, float, None]


DEPRECATED_MODULE_PATHS = {'astrapy.api', 'astrapy.core', 'astrapy.db', 'astrapy.ops'}


Issue a DeprecatedWarning (subclass of DeprecationWarning).

In order to correctly refer to user code, this function needs to
dynamically adjust the `stacklevel` parameter.


queue

queue: queue.Queue[API_DOC | None] = queue.Queue(prefetched)


thread

thread = threading.Thread(target=_PrefetchIterator.queued_paginate, args=(weakref.proxy(self),))


caller_name: str | None = self.astra_db.caller_name


caller_version: str | None = self.astra_db.caller_version


base_path: str = f'{self.astra_db.base_path}/{self.collection_name}'


Retrieve a document from the collection by its path.

get

path

The path of the document to retrieve.

a float, or a TimeoutInfo dict, for the HTTP request.
Note that a 'read' timeout event will not block the action taken
by the API server if it has received the request already.

dict

The retrieved document.


Find documents in the collection that match the given filter.

find

filter

Criteria to filter documents.

projection

Specifies the fields to return.

sort

Specifies the order in which to return matching documents.

options

Additional options for the query.

dict

The query response containing matched documents.


Perform a vector-based search in the collection.

vector

The vector to search with.

limit

The maximum number of documents to return.

filter

Criteria to filter documents.

fields

Specifies the fields to return.

Whether to include similarity score in the result.

list

A list of documents matching the vector search criteria.


Generate paginated results for a given database query method.

paginate

The database query method to paginate.

options

Options for the database query.

prefetched

Number of pre-fetched documents.

an optional callback invoked at each new
response coming from the API. The only argument is the raw
API response and the callback must return None.

dict

The next document in the paginated result set.


Perform a paginated search in the collection.

filter

Criteria to filter documents.

projection

Specifies the fields to return.

options

Additional options for the query.

prefetched

Number of pre-fetched documents.

a float, or a TimeoutInfo dict, for each
single HTTP request.
This is a paginated method, that issues several requests as it
needs more data. This parameter controls a single request.
Note that a 'read' timeout event will not block the action taken
by the API server if it has received the request already.

generator

A generator yielding documents in the paginated result set.


Pop the last data in the tags array

pop

filter

Criteria to identify the document to update.

pop

The pop to apply to the tags.

options

Additional options for the update operation.

dict

The original document before the update.


Push new data to the tags array

push

push

The push to apply to the tags.

dict

The result of the update operation.


Find a single document and replace it.

replacement

The new document to replace the existing one.

filter

Criteria to filter documents.

sort

Specifies the order in which to find the document.

options

Additional options for the operation.

dict

The result of the find and replace operation.


Perform a vector-based search and replace the first matched document.

vector

The vector to search with.

filter

Criteria to filter documents.

fields

Specifies the fields to return in the result.

a float, or a TimeoutInfo dict, for the HTTP request.
Note that a 'read' timeout event will not block the action taken
by the API server if it has received the request already.

dict or None: either the matched document or None if nothing found


Find a single document and update it.

update

The update to apply to the document.

filter

Criteria to filter documents.

options

Additional options for the operation.

dict

The result of the find and update operation.


Perform a vector-based search and update the first matched document.

vector

The vector to search with.

update

The update to apply to the matched document.

filter

Criteria to filter documents before applying the vector search.

fields

Specifies the fields to return in the updated document.

dict or None: The result of the vector-based find and
update operation, or None if nothing found


Find a single document and delete it.

filter

Criteria to filter documents.

projection

Specifies the fields to return.

dict

The result of the find and delete operation.


Count documents matching a given predicate (expressed as filter).

filter

Criteria to filter documents.

dict

the response, either
{"status": {"count": <NUMBER> }}

or
{"errors": [...]}


Find a single document in the collection.

filter

Criteria to filter documents.

projection

Specifies the fields to return.

sort

Specifies the order in which to return the document.

options

Additional options for the query.

dict

the response, either
{"data": {"document": <DOCUMENT> }}

or
{"data": {"document": None}}

depending on whether a matching document is found or not.


Perform a vector-based search to find a single document in the collection.

vector

The vector to search with.

filter

Additional criteria to filter documents.

Whether to include similarity score in the result.

dict or None: The found document or None if no matching document is found.


Insert a single document into the collection.

document

The document to insert.

Whether to allow failures in the insert operation.

dict

The response from the database after the insert operation.


Insert multiple documents into the collection.

documents

A list of documents to insert.

options

Additional options for the insert operation.

Whether to allow partial
failures through the insertion (i.e. on some documents).

a float, or a TimeoutInfo dict, for the HTTP request.
Note that a 'read' timeout event will not block the action taken
by the API server if it has received the request already.


Insert multiple documents into the collection, handling chunking and
optionally with concurrent insertions.

documents

A list of documents to insert.

Whether to allow partial
failures in the chunk. Should be used combined with
options={"ordered": False} in most cases.

Override the default insertion chunk size.

concurrency

The number of concurrent chunk insertions.
Default is no concurrency.

a float, or a TimeoutInfo dict, for each single HTTP request.
This method runs a number of HTTP requests as it works on chunked
data. The timeout refers to each individual such request.
Note that a 'read' timeout event will not block the action taken
by the API server if it has received the request already.

list

The responses from the database after the chunked insert operation.
This is a list of individual responses from the API: the caller
will need to inspect them all, e.g. to collate the inserted IDs.


Update a single document in the collection.

filter

Criteria to identify the document to update.

update

The update to apply to the document.

options

Additional options for the operation.

dict

The response from the database after the update operation.


Updates multiple documents in the collection.

update

The update to apply to the document.


Replace a document in the collection.

replace

path

The path to the document to replace.

document

The new document to replace the existing one.

dict

The response from the database after the replace operation.


Delete a single document from the collection based on its ID.

id

The ID of the document to delete.

dict

The response from the database after the delete operation.


Delete a single document from the collection based on a filter clause

filter

any filter dictionary


Delete many documents from the collection based on a filter condition

Criteria to identify the documents to delete.

whether to ignore the check for API error
and return the response untouched. Default is False.


Delete many documents from the collection based on a filter condition,
chaining several API calls until exhaustion of the documents to delete.

a float, or a TimeoutInfo dict, for each single HTTP request.
This method runs a number of HTTP requests as it works on a
pagination basis. The timeout refers to each individual such request.
Note that a 'read' timeout event will not block the action taken
by the API server if it has received the request already.

List[dict]: The responses from the database from all the calls


Clear the collection, deleting all documents

clear

dict

The response from the database.


Delete a subdocument or field from a document in the collection.

id

The ID of the document containing the subdocument.

subdoc

The key of the subdocument or field to remove.

a float, or a TimeoutInfo dict, for the HTTP request.
Note that a 'read' timeout event will not block the action taken
by the API server if it has received the request already.


Emulate an upsert operation for a single document in the collection.

This method attempts to insert the document.
If a document with the same _id exists, it updates the existing document.

document

The document to insert or update.

a float, or a TimeoutInfo dict, for the HTTP requests.
This method may issue one or two requests, depending on what
is detected on DB. This timeout controls each HTTP request individually.
Note that a 'read' timeout event will not block the action taken
by the API server if it has received the request already.

str

The _id of the inserted or updated document.


Emulate an upsert operation for multiple documents in the collection.

This method attempts to insert the documents.
If a document with the same _id exists, it updates the existing document.

documents

The documents to insert or update.

concurrency

The number of concurrent upserts.

Whether to allow partial
failures in the batch.

a float, or a TimeoutInfo dict, for each HTTP request.
This method issues a separate HTTP request for each document to
insert: the timeout controls each such request individually.
Note that a 'read' timeout event will not block the action taken
by the API server if it has received the request already.

List[Union[str, Exception]]: A list of "_id"s of the inserted or updated documents.


Retrieve a document from the collection by its path.

get

path

The path of the document to retrieve.

dict

The retrieved document.


Find documents in the collection that match the given filter.

find

filter

Criteria to filter documents.

projection

Specifies the fields to return.

sort

Specifies the order in which to return matching documents.

options

Additional options for the query.

dict

The query response containing matched documents.


Perform a vector-based search in the collection.

vector

The vector to search with.

limit

The maximum number of documents to return.

filter

Criteria to filter documents.

fields

Specifies the fields to return.

Whether to include similarity score in the result.

list

A list of documents matching the vector search criteria.


Generate paginated results for a given database query method.

paginate

The database query method to paginate.

options

Options for the database query.

prefetched

Number of pre-fetched documents.

an optional callback invoked at each new
response coming from the API. The only argument is the raw
API response and the callback must return None.

dict

The next document in the paginated result set.


Perform a paginated search in the collection.

filter

Criteria to filter documents.

projection

Specifies the fields to return.

options

Additional options for the query.

prefetched

Number of pre-fetched documents

a float, or a TimeoutInfo dict, for each
single HTTP request.
This is a paginated method, that issues several requests as it
needs more data. This parameter controls a single request.
Note that a 'read' timeout event will not block the action taken
by the API server if it has received the request already.

generator

A generator yielding documents in the paginated result set.


Pop the last data in the tags array

pop

filter

Criteria to identify the document to update.

pop

The pop to apply to the tags.

options

Additional options for the update operation.

a float, or a TimeoutInfo dict, for the HTTP request.
Note that a 'read' timeout event will not block the action taken
by the API server if it has received the request already.

dict

The original document before the update.


Push new data to the tags array

push

push

The push to apply to the tags.

dict

The result of the update operation.


Find a single document and replace it.

replacement

The new document to replace the existing one.

filter

Criteria to filter documents.

sort

Specifies the order in which to find the document.

options

Additional options for the operation.

dict

The result of the find and replace operation.


Perform a vector-based search and replace the first matched document.

vector

The vector to search with.

filter

Criteria to filter documents.

fields

Specifies the fields to return in the result.

dict or None: either the matched document or None if nothing found


Find a single document and update it.

update

The update to apply to the document.

filter

Criteria to filter documents.

options

Additional options for the operation.

dict

The result of the find and update operation.


Perform a vector-based search and update the first matched document.

vector

The vector to search with.

update

The update to apply to the matched document.

filter

Criteria to filter documents before applying the vector search.

fields

Specifies the fields to return in the updated document.

dict or None: The result of the vector-based find and
update operation, or None if nothing found


Find a single document and delete it.

filter

Criteria to filter documents.

projection

Specifies the fields to return.

dict

The result of the find and delete operation.


Count documents matching a given predicate (expressed as filter).

filter

Criteria to filter documents.

dict

the response, either
{"status": {"count": <NUMBER> }}

or
{"errors": [...]}


Find a single document in the collection.

filter

Criteria to filter documents.

projection

Specifies the fields to return.

sort

Specifies the order in which to return the document.

options

Additional options for the query.

dict

the response, either
{"data": {"document": <DOCUMENT> }}

or
{"data": {"document": None}}

depending on whether a matching document is found or not.


Perform a vector-based search to find a single document in the collection.

vector

The vector to search with.

filter

Additional criteria to filter documents.

Whether to include similarity score in the result.

a float, or a TimeoutInfo dict, for the HTTP request.
Note that a 'read' timeout event will not block the action taken
by the API server if it has received the request already.

dict or None: The found document or None if no matching document is found.


Insert a single document into the collection.

document

The document to insert.

Whether to allow failures in the insert operation.

dict

The response from the database after the insert operation.


Insert multiple documents into the collection.

documents

A list of documents to insert.

options

Additional options for the insert operation.

Whether to allow partial
failures through the insertion (i.e. on some documents).


Insert multiple documents into the collection, handling chunking and
optionally with concurrent insertions.

documents

A list of documents to insert.

Whether to allow partial
failures in the chunk. Should be used combined with
options={"ordered": False} in most cases.

Override the default insertion chunk size.

concurrency

The number of concurrent chunk insertions.
Default is no concurrency.

a float, or a TimeoutInfo dict, for each single HTTP request.
This method runs a number of HTTP requests as it works on chunked
data. The timeout refers to each individual such request.
Note that a 'read' timeout event will not block the action taken
by the API server if it has received the request already.

list

The responses from the database after the chunked insert operation.
This is a list of individual responses from the API: the caller
will need to inspect them all, e.g. to collate the inserted IDs.


Update a single document in the collection.

filter

Criteria to identify the document to update.

update

The update to apply to the document.

options

Additional options for the operation.

dict

The response from the database after the update operation.


Updates multiple documents in the collection.

update

The update to apply to the document.


Replace a document in the collection.

replace

path

The path to the document to replace.

document

The new document to replace the existing one.

dict

The response from the database after the replace operation.


Delete a single document from the collection based on its ID.

id

The ID of the document to delete.

dict

The response from the database after the delete operation.


Delete a single document from the collection based on a filter clause

filter

any filter dictionary


Delete many documents from the collection based on a filter condition

Criteria to identify the documents to delete.

whether to ignore the check for API error
and return the response untouched. Default is False.

a float, or a TimeoutInfo dict, for the HTTP request.
Note that a 'read' timeout event will not block the action taken
by the API server if it has received the request already.


Delete many documents from the collection based on a filter condition,
chaining several API calls until exhaustion of the documents to delete.

a float, or a TimeoutInfo dict, for each single HTTP request.
This method runs a number of HTTP requests as it works on a
pagination basis. The timeout refers to each individual such request.
Note that a 'read' timeout event will not block the action taken
by the API server if it has received the request already.

List[dict]: The responses from the database from all the calls


Clear the collection, deleting all documents

clear

dict

The response from the database.


Delete a subdocument or field from a document in the collection.

id

The ID of the document containing the subdocument.

subdoc

The key of the subdocument or field to remove.


Emulate an upsert operation for a single document in the collection.

This method attempts to insert the document.
If a document with the same _id exists, it updates the existing document.

document

The document to insert or update.

a float, or a TimeoutInfo dict, for the HTTP requests.
This method may issue one or two requests, depending on what
is detected on DB. This timeout controls each HTTP request individually.
Note that a 'read' timeout event will not block the action taken
by the API server if it has received the request already.

str

The _id of the inserted or updated document.


Emulate an upsert operation for multiple documents in the collection.
This method attempts to insert the documents.
If a document with the same _id exists, it updates the existing document.

documents

The documents to insert or update.

concurrency

The number of concurrent upserts.

Whether to allow partial
failures in the batch.

a float, or a TimeoutInfo dict, for each HTTP request.
This method issues a separate HTTP request for each document to
insert: the timeout controls each such request individually.
Note that a 'read' timeout event will not block the action taken
by the API server if it has received the request already.

List[Union[str, Exception]]: A list of "_id"s of the inserted or updated documents.


api_path = DEFAULT_JSON_API_PATH if api_path is None else api_path.strip('/')


api_version = DEFAULT_JSON_API_VERSION if api_version is None else api_version.strip('/')


base_path: str = f'/{'/'.join(base_path_components)}'


Retrieve a collection from the database.

collection

The name of the collection to retrieve.

AstraDBCollection

The collection object.


Retrieve a list of collections from the database.

options

Options to get the collection list

dict

An object containing the list of collections in the database:
{"status": {"collections": [...]}}


Create a new collection in the database.

The name of the collection to create.

options

Options for the collection.

dimension

Dimension for vector search.

metric

Metric choice for vector search.

a definition for the $vectorize service

AstraDBCollection

The created collection object.


Delete a collection from the database.

The name of the collection to delete.

dict

The response from the database.


collection

The name of the collection to retrieve.

AstraDBCollection

The collection object.


options

Options to get the collection list


The name of the collection to create.

Options for the collection.

dimension

Dimension for vector search.

metric

Metric choice for vector search.

a definition for the $vectorize service

AsyncAstraDBCollection

The created collection object.


Delete a collection from the database.

The name of the collection to delete.

dict

The response from the database.


constructor_params: AstraDBOpsConstructorParams = {'token': token, 'dev_ops_url': dev_ops_url, 'dev_ops_api_version': dev_ops_api_version, 'caller_name': caller_name, 'caller_version': caller_version}


Retrieve a list of databases.

options

Additional options for the request.

list

a JSON list of dictionaries, one per database.


Retrieve a list of databases - async version of the method.

options

Additional options for the request.


Create a new database.

A dictionary defining the properties of the database to be created.

either a float (seconds) or a TimeoutInfo dict (see)

dict

A dictionary such as: {"id": the ID of the created database}

Raises an error if not successful.


Create a new database - async version of the method.

Raises an error if not successful.


Terminate an existing database.

database

The identifier of the database to terminate.

str

The identifier of the terminated database, or None if termination was unsuccessful.


Terminate an existing database - async version of the method.


Retrieve details of a specific database.

database

The identifier of the database to retrieve.

options

Additional options for the request.

dict

A JSON response containing the details of the specified database.


Retrieve details of a specific database - async version of the method.

options

Additional options for the request.


Create a keyspace in a specified database.

database

The identifier of the database where the keyspace will be created.

keyspace

The name of the keyspace to create.

{"ok": 1} if successful. Raises errors otherwise.


Create a keyspace in a specified database - async version of the method.

The name of the keyspace to create.


Delete a keyspace from a database

The name of the keyspace to create.

str

The identifier of the deleted keyspace. Otherwise raises an error.


Delete a keyspace from a database - async version of the method.

keyspace

The name of the keyspace to create.


Park a specific database, making it inactive.

database

The identifier of the database to park.

dict

The response from the server after parking the database.


Unpark a specific database, making it active again.

database

The identifier of the database to unpark.

dict

The response from the server after unparking the database.


Resize a specific database according to provided options.

database

The identifier of the database to resize.

options

The specifications for the resize operation.

dict

The response from the server after the resize operation.


Reset the password for a specific database.

database

The identifier of the database for which to reset the password.

options

Additional options for the password reset.

dict

The response from the server after resetting the password.


Retrieve a secure bundle URL for a specific database.

database

The identifier of the database for which to get the secure bundle.

dict

The secure bundle URL and related information.


Get a list of datacenters associated with a specific database.

database

The identifier of the database for which to list datacenters.

dict

A list of datacenters and their details.


Create a new datacenter for a specific database.

database

The identifier of the database for which to create the datacenter.

options

Specifications for the new datacenter.

dict

The response from the server after creating the datacenter.


Terminate a specific datacenter in a database.

database

The identifier of the database containing the datacenter.

datacenter

The identifier of the datacenter to terminate.

dict

The response from the server after terminating the datacenter.


Retrieve the access list for a specific database.

database

The identifier of the database for which to get the access list.

dict

The current access list for the database.


Replace the entire access list for a specific database.

database

The identifier of the database for which to replace the access list.

The new access list to be set.

dict

The response from the server after replacing the access list.


Update the access list for a specific database.

database

The identifier of the database for which to update the access list.

The updates to be applied to the access list.

dict

The response from the server after updating the access list.


Add a new address to the access list for a specific database.

database

The identifier of the database for which to add the address.

address

The address details to add to the access list.

dict

The response from the server after adding the address.


Delete the access list for a specific database.

database

The identifier of the database for which to delete the access list.

dict

The response from the server after deleting the access list.


Retrieve the private link information for a specified database.

database

The identifier of the database.

dict

The private link information for the database.


Retrieve the private link information for a specific datacenter in a database.

database

The identifier of the database.

datacenter

The identifier of the datacenter.

dict

The private link information for the specified datacenter.


Create a private link for a specific datacenter in a database.

database

The identifier of the database.

datacenter

The identifier of the datacenter.

The private link configuration details.

dict

The response from the server after creating the private link.


Create an endpoint for a specific datacenter in a database.

database

The identifier of the database.

datacenter

The identifier of the datacenter.

endpoint

The endpoint configuration details.

dict

The response from the server after creating the endpoint.


Update an existing endpoint for a specific datacenter in a database.

database

The identifier of the database.

datacenter

The identifier of the datacenter.

endpoint

The updated endpoint configuration details.

dict

The response from the server after updating the endpoint.


Retrieve information about a specific endpoint in a datacenter of a database.

database

The identifier of the database.

datacenter

The identifier of the datacenter.

endpoint

The identifier of the endpoint.

dict

The endpoint information for the specified datacenter.


Delete a specific endpoint in a datacenter of a database.

database

The identifier of the database.

datacenter

The identifier of the datacenter.

endpoint

The identifier of the endpoint to delete.

dict

The response from the server after deleting the endpoint.


Retrieve a list of available classic regions.

A list of available classic regions.


Retrieve a list of available regions for serverless deployment.

A list of available regions for serverless deployment.


Retrieve a list of roles within the organization.

A list of roles within the organization.


Create a new role within the organization.

The definition of the role to be created.

The response from the server after creating the role.


Retrieve details of a specific role within the organization.

role

The identifier of the role.

dict

The details of the specified role.


Update the definition of an existing role within the organization.

role

The identifier of the role to update.

The new definition of the role.

dict

The response from the server after updating the role.


Delete a specific role from the organization.

role

The identifier of the role to delete.

dict

The response from the server after deleting the role.


Invite a new user to the organization.

The definition of the user to be invited.

The response from the server after inviting the user.


Retrieve a list of users within the organization.

A list of users within the organization.


Retrieve details of a specific user within the organization.

user

The identifier of the user.

dict

The details of the specified user.


Remove a user from the organization.

user

The identifier of the user to remove.

dict

The response from the server after removing the user.


Update the roles assigned to a specific user within the organization.

user

The identifier of the user.

roles

The list of new roles to assign to the user.

dict

The response from the server after updating the user's roles.


Retrieve a list of client IDs and secrets associated with the organization.

A list of client IDs and their associated secrets.


Create a new token with specific roles.

roles

The roles to associate with the token:
{"roles": ["<roleId>"]}

dict

The response from the server after creating the token.


Delete a specific token.

token

The identifier of the token to delete.

dict

The response from the server after deleting the token.


Retrieve details of the current organization.

The details of the organization.


Retrieve a list of access lists for the organization.

A list of access lists.


Retrieve a template for creating an access list.

An access list template.


Validate the configuration of the access list.

The validation result of the access list configuration.


Retrieve a list of private link connections for the organization.

A list of private link connections.


Retrieve a list of streaming service providers.

A list of available streaming service providers.


Retrieve a list of streaming tenants.

A list of streaming tenants and their details.


Create a new streaming tenant.

tenant

The configuration details for the new streaming tenant.

dict

The response from the server after creating the streaming tenant.


Delete a specific streaming tenant from a cluster.

tenant

The identifier of the tenant to delete.

cluster

The identifier of the cluster from which the tenant is to be deleted.

either a float (seconds) or a TimeoutInfo dict (see)

dict

The response from the server after deleting the streaming tenant.


Retrieve information about the limits and usage of a specific streaming tenant.

tenant

The identifier of the streaming tenant.

dict

Details of the specified streaming tenant, including limits and current usage.


OPS_API_RESPONSE = Union[API_RESPONSE, List[Any]]


Log the details of an HTTP request for debugging purposes.

The JSON payload sent with the request, if any.


Log the details of an HTTP response for debugging purposes.

r

The response object from the HTTP request.


Make an HTTP request to a specified URL.

client

The httpx client for the request.

The base URL for the request.

The authentication header key.

token

The token used for authentication.

method

The HTTP method to use for the request. Default is POST.

path

The specific path to append to the base URL.

JSON payload to be sent with the request.

URL parameters to be sent with the request.

requests.Response: The response from the HTTP request.


client

The httpx client for the request.

The base URL for the request.

The authentication header key.

token

The token used for authentication.


Construct a JSON payload for an HTTP request with a specified top-level key.

The top-level key for the JSON payload.

**kwargs

Arbitrary keyword arguments representing other keys and their values to be included in the payload.

dict

The constructed JSON payload.


Convert a vector of strings to a vector of floats.

vector

A vector of objects.

list

A vector of floats.


Safely determine if it's a list of floats.
Assumption: if list, and first item is float, then all items are.


Normalize a payload for API calls.
This includes e.g. ensuring values for "$vector" key
are made into plain lists of floats.

payload

A dict expressing a payload for an API call

Dict[str, Any]: a "normalized" payload dict


Process a dictionary just returned from the API.
This is the place where e.g. `{"$date": 123}` is
converted back into a datetime object.


DEFAULT_REDACTED_HEADERS = {DEFAULT_DEV_OPS_AUTH_HEADER, DEFAULT_AUTH_HEADER, 'X-Embedding-Api-Key', 'X-Embedding-Access-Id', 'X-Embedding-Secret-Id'}


Core "db" subpackage, exported here to preserve import patterns.

db

AsyncAstraDBCollection AsyncAstraDB logger AstraDBCollection AstraDB


Core "api" subpackage, exported here to preserve import patterns.


Core "ops" subpackage, exported here to preserve import patterns.