Count Documents

Count documents matching a filter query with RBAC enforcement

POST /{collection}/count

Count Documents

cURL

curl --request POST \
  --url https://api.example.com/{collection}/count \
  --header 'Content-Type: application/json' \
  --data '{
  "filter": {}
}'

200

{
  "data": {
    "count": 123
  },
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

Overview

The count endpoint returns the number of documents in a collection that match a given filter query. The count respects RBAC permissions and only includes documents the authenticated user has permission to read.

Request

collection · string · required

The name of the collection to count documents in

filter · object

MongoDB-style filter query to match documents. If omitted, counts all documents the user has permission to read.

Count All Documents Example

POST /users/count

No request body needed to count all accessible documents.

Count with Filter Example

{
  "filter": {
    "status": "active",
    "department": "Engineering"
  }
}

Complex Filter Example

{
  "filter": {
    "created_at": {
      "$gte": "2024-01-01T00:00:00Z",
      "$lt": "2024-12-31T23:59:59Z"
    },
    "age": { "$gte": 18 },
    "role": { "$in": ["developer", "designer", "manager"] },
    "email_verified": true
  }
}

Response

data · object

count · integer

The number of documents matching the filter criteria that the user has permission to read

Response Example

{
  "data": {
    "count": 142
  }
}

Filter Query Syntax

The filter parameter supports MongoDB query operators:

Comparison Operators

{
  "filter": {
    "age": { "$gte": 18, "$lt": 65 },
    "salary": { "$gt": 50000 },
    "status": { "$ne": "deleted" }
  }
}

• $eq: Equal to
• $ne: Not equal to
• $gt: Greater than
• $gte: Greater than or equal to
• $lt: Less than
• $lte: Less than or equal to

Array Operators

{
  "filter": {
    "role": { "$in": ["admin", "moderator"] },
    "status": { "$nin": ["banned", "suspended"] }
  }
}

• $in: Value is in array
• $nin: Value is not in array

Logical Operators

{
  "filter": {
    "$or": [
      { "status": "active" },
      { "last_login": { "$gte": "2024-01-01T00:00:00Z" } }
    ],
    "department": { "$exists": true }
  }
}

• $and: All conditions must match
• $or: At least one condition must match
• $not: Inverts the condition
• $exists: Field exists/doesn’t exist

Pattern Matching

{
  "filter": {
    "email": { "$regex": "@company\\.com$" }
  }
}

RBAC Enforcement

From handlers_query.go:470-477:

The count operation automatically combines the provided filter with RBAC query filters. This ensures users only count documents they have permission to read.

rbacFilter := h.getRBACQueryFilter(authCtx, collection, schema.ActionRead)
combinedFilter := h.combineFilters(request.Filter, rbacFilter)

For example:

• A manager might only count documents in their department
• A user might only count their own documents
• An admin might count all documents

Use Cases

Pre-validation Before Batch Operations

// Count documents before batch delete
POST /products/count
{
  "filter": {
    "status": "discontinued",
    "stock": 0
  }
}

// Response: { "data": { "count": 47 } }
// Now you know 47 documents will be deleted

Analytics and Reporting

// Count active users by department
POST /users/count
{
  "filter": {
    "status": "active",
    "department": "Engineering"
  }
}

Validation Before Updates

// Verify how many documents will be affected
POST /orders/count
{
  "filter": {
    "status": "pending",
    "created_at": { "$lt": "2024-01-01T00:00:00Z" }
  }
}

Performance Considerations

Count operations use MongoDB’s native count functionality, which is optimized for indexed fields. Ensure your filter uses indexed fields for best performance on large collections.

Optimization Tips

1. Use indexed fields in your filter criteria
2. Avoid complex regex patterns on non-indexed fields
3. Consider collection size: Counts on very large collections may take time
4. Cache results if the data doesn’t change frequently

Error Responses

error · object

code · string

Error code:

• collection_not_found: Collection does not exist
• forbidden: User lacks read permission
• bad_request: Invalid filter syntax
• internal_error: Database operation failed

message · string

Human-readable error message

details · object

Additional error context

Error Example

{
  "error": {
    "code": "bad_request",
    "message": "Invalid JSON body",
    "details": {
      "error": "unexpected end of JSON input"
    }
  }
}

Audit Logging

All count operations are logged to the audit trail with:

• User ID and roles
• Collection name
• Filter criteria
• Success/failure status
• Timestamp

From handlers_query.go:492-493

Code Reference

Implementation: pkg/api/handlers_query.go:422-502

Related Endpoints

• List Documents - Query and retrieve documents
• Aggregate - Complex aggregations with grouping
• Batch Delete - Delete multiple documents