Count documents

Counts documents in a collection using filter and sort clauses.

Exact counting of the number of documents is a slow, expensive operation. If the document count exceeds the upper limit set by you or by the API, an indication of this limit will be returned instead of the full count.

If you need to count large numbers of documents, consider using the method to estimate count or the DataStax Bulk Loader instead.

Result

Python
TypeScript
Java
curl

Returns an integer indicating the exact number of documents that match the specified filter.

If the count exceeds the caller-provided or API-set upper bound, the client raises TooManyDocumentsToCountException.

Returns a promise that resolves to an integer indicating the exact number of documents that match the specified filter.

If the count exceeds the caller-provided or API-set upper bound, the client raises TooManyDocumentsToCountError.

Returns an integer indicating the exact number of documents that match the specified filter.

If the count exceeds the caller-provided or API-set upper bound, the client raises TooManyDocumentsToCountException.

The response includes a status.count property, which is an integer indicating the exact number of documents that match the specified filter.

If the count exceeds the upper bound set by the API, then the status.count value will be the upper bound, and the status.moreData value is true.

Example response:

{
  "status": {
    "count": 105
  }
}

Example response if the number of documents exceeds the upper bound.

{
  "status": {
    "moreData": true,
    "count": 1000
  }
}

Parameters

Python
TypeScript
Java
curl

Name Type Summary

Name	Type	Summary
`filter`	`Optional[Dict[str, Any]]`	A predicate expressed as a dictionary according to the Data API filter syntax. For example: `{}`, `{"name": "John"}`, `{"price": {"$lt": 100}}`, `{"$and": [{"name": "John"}, {"price": {"$lt": 100}}]}`. If not provided, all documents are counted. For a list of available operators and examples, see Data API operators. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in sort or filter queries.
`upper_bound`	`int`	A required ceiling on the result of the count operation. If the actual number of documents exceeds this value, an exception is raised. An exception is also raised if the actual number of documents exceeds the maximum count that the Data API can reach, regardless of `upper_bound`.
`max_time_ms`	`Optional[int]`	A timeout, in milliseconds, for the underlying HTTP request. This method uses the collection-level timeout by default.

filter

Optional[Dict[str, Any]]

A predicate expressed as a dictionary according to the Data API filter syntax. For example: {}, {"name": "John"}, {"price": {"$lt": 100}}, {"$and": [{"name": "John"}, {"price": {"$lt": 100}}]}. If not provided, all documents are counted. For a list of available operators and examples, see Data API operators. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in sort or filter queries.

upper_bound

int

A required ceiling on the result of the count operation. If the actual number of documents exceeds this value, an exception is raised. An exception is also raised if the actual number of documents exceeds the maximum count that the Data API can reach, regardless of upper_bound.

max_time_ms

Optional[int]

A timeout, in milliseconds, for the underlying HTTP request. This method uses the collection-level timeout by default.

Name Type Summary

Name	Type	Summary
`filter`	`Filter<Schema>`	A filter to select the documents to count. If not provided, all documents are counted. For a list of available operators and examples, see Data API operators. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in sort or filter queries.
`upperBound`	`number`	A required ceiling on the result of the count operation. If the actual number of documents exceeds this value, an exception is raised. An exception is also raised if the actual number of documents exceeds the maximum count that the Data API can reach, regardless of `upperBound`.
`options?`	`WithTimeout`	The options (the timeout) for this operation.

filter

Filter<Schema>

A filter to select the documents to count. If not provided, all documents are counted. For a list of available operators and examples, see Data API operators. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in sort or filter queries.

upperBound

number

options?

WithTimeout

The options (the timeout) for this operation.

Name Type Summary

Name	Type	Summary
`filter` (optional)	`Filter`	A filter to select documents to count. For example: `{}`, `{"name": "John"}`, `{"price": {"$lt": 100}}`, `{"$and": [{"name": "John"}, {"price": {"$lt": 100}}]}`. If not provided, all documents are counted. For a list of available operators and examples, see Data API operators. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in sort or filter queries.
`upperBound`	`int`	A required ceiling on the result of the count operation. If the actual number of documents exceeds this value, an exception is raised. An exception is also raised if the actual number of documents exceeds the maximum count that the Data API can reach, regardless of `upperBound`.

filter (optional)

Filter

A filter to select documents to count. For example: {}, {"name": "John"}, {"price": {"$lt": 100}}, {"$and": [{"name": "John"}, {"price": {"$lt": 100}}]}. If not provided, all documents are counted. For a list of available operators and examples, see Data API operators. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in sort or filter queries.

upperBound

int

Name Type Summary

Name	Type	Summary
`countDocuments`	`command`	A command to return an exact count of documents in a collection.
`filter`	`object`	An optional filter to select the documents to count. If not provided, all documents are counted. For a list of available operators and examples, see Data API operators. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in sort or filter queries.

countDocuments

command

A command to return an exact count of documents in a collection.

filter

object

An optional filter to select the documents to count. If not provided, all documents are counted. For a list of available operators and examples, see Data API operators. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in sort or filter queries.

Examples

The following examples demonstrate how to count documents in a collection.

Count documents that match a filter

You can use a filter to count documents that match specific criteria.

For a list of available filter operators and more examples, see Data API operators.

Filters can use only indexed fields. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in a filter.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient, exceptions

# Get an existing collection
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Count documents
try:
  result = collection.count_documents(
    {
        "$and": [
            {"isCheckedOut": False},
            {"numberOfPages": {"$lt": 300}},
        ]
    },
    upper_bound=500
  )
  print(result)
except(exceptions.TooManyDocumentsToCountException):
    print("Number of documents exceeds upper bound or API limit")

import { DataAPIClient, TooManyDocumentsToCountError } from '@datastax/astra-db-ts';

// Get an existing collection
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const collection = database.collection('COLLECTION_NAME');

(async function () {
  try {
    // Count documents
    const result = await collection.countDocuments(
      {
        $and: [{ isCheckedOut: false }, { numberOfPages: { $lt: 300 } }],
      },
      500,
    );

    console.log(result);
  } catch (TooManyDocumentsToCountError) {
    console.log("Number of documents exceeds upper bound or API limit");
  }
})();

package com.datastax.astra.client.collection;

import com.datastax.astra.client.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.model.Document;
import com.datastax.astra.client.model.Filter;
import com.datastax.astra.client.model.Filters;

public class CountDocuments {

    public static void main(String[] args) {
        // Get an existing collection
        Collection<Document> collection = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
            .getDatabase("ASTRA_DB_API_ENDPOINT")
            .getCollection("COLLECTION_NAME");

        // Count documents
        Filter filter =
            Filters.and(Filters.eq("isCheckedOut", false), Filters.lt("numberOfPages", 300));

        try {
          Integer result = collection.countDocuments(filter, 500);
          System.out.println(result);
        } catch (TooManyDocumentsToCountException error) {
            System.out.println("Number of documents exceeds upper bound or API limit");
        }
    }
}

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_COLLECTION" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "countDocuments": {
    "filter": {"$and": [
      {"isCheckedOut": false},
      {"numberOfPages": {"$lt": 300}}
    ]}
  }
}'

Count all documents

To attempt to count all documents, use an empty filter.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient, exceptions

# Get an existing collection
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Count documents
try:
  result = collection.count_documents(
    {},
    upper_bound=500
  )
  print(result)
except(exceptions.TooManyDocumentsToCountException):
    print("Number of documents exceeds upper bound or API limit")

import { DataAPIClient, TooManyDocumentsToCountError } from '@datastax/astra-db-ts';

// Get an existing collection
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const collection = database.collection('COLLECTION_NAME');

(async function () {
  try {
    // Count documents
    const result = await collection.countDocuments(
      {},
      500,
    );

    console.log(result);
  } catch (TooManyDocumentsToCountError) {
    console.log("Number of documents exceeds upper bound or API limit");
  }
})();

package com.datastax.astra.client.collection;

import com.datastax.astra.client.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.model.Document;

public class CountDocuments {

    public static void main(String[] args) {
        // Get an existing collection
        Collection<Document> collection = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
            .getDatabase("ASTRA_DB_API_ENDPOINT")
            .getCollection("COLLECTION_NAME");

        // Count documents
        try {
          Integer result = collection.countDocuments(500);
          System.out.println(result);
        } catch (TooManyDocumentsToCountException error) {
            System.out.println("Number of documents exceeds upper bound or API limit");
        }
    }
}

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_COLLECTION" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "countDocuments": {
    "filter": {}
  }
}'

Client reference

Python
TypeScript
Java
curl

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

Count documents

Result

Parameters

Examples

Count documents that match a filter

Count all documents

Client reference

Was this helpful?

Give Feedback