MONGOC_DATABASE_AGGREGATE(3)

📦
version 2.5.6 · 16 versions
, in epel 10

🌸 MONGOC_DATABASE_AGGREGATE 🌸

ok so bestie, this is a page from libmongoc — the mongoc_database_aggregate(3) manual, and no cap it's actually kind of a big deal. it's giving "database-wide aggregation era" 💅 so let's get into it.

✨ SYNOPSIS ✨

like, here's the whole vibe of the function signature, exactly as it is:

mongoc_cursor_t *
mongoc_database_aggregate (mongoc_database_t *database,
                           const bson_t *pipeline,
                           const bson_t *opts,
                           const mongoc_read_prefs_t *read_prefs);

🎀 PARAMETERS 🎀

okay so here's who's who in this little group chat 💖

  • database — a mongoc_database_t. that's the database you're aggregating on, periodt.
  • pipeline — a bson_t, and it's either a BSON array or a BSON document containing an array field named "pipeline". both are valid, pick your fighter ✨
  • opts — a bson_t holding options for the command, or NULL. no pressure.
  • read_prefs — a mongoc_read_prefs_t, or NULL. also no pressure.

ngl, opts can be NULL or a BSON document with extra command options, and these are them 👇

  • readConcern — build a mongoc_read_concern_t and use mongoc_read_concern_append() to add the read concern to opts. see the example code for mongoc_client_read_command_with_opts(). btw read concern needs MongoDB 3.2 or later — otherwise an error is returned. 💀
  • writeConcern — build a mongoc_write_concern_t and use mongoc_write_concern_append() to add the write concern to opts. see the example code for mongoc_client_write_command_with_opts().
  • sessionId — first, construct a mongoc_client_session_t with mongoc_client_start_session(). you can begin a transaction with mongoc_client_session_start_transaction(), optionally with a mongoc_transaction_opt_t that overrides the options inherited from database, and use mongoc_client_session_append() to add the session to opts. see the example code for mongoc_client_session_t. iykyk 🫶
  • bypassDocumentValidation — set to true to skip server-side schema validation of the provided BSON documents. living dangerously, love that for you.
  • collation — configure textual comparisons. see Setting Collation Order, and the MongoDB Manual entry on Collation. collation requires MongoDB 3.2 or later, otherwise an error is returned. same energy as read concern fr fr.
  • serverId — to target a specific server, include an int32 "serverId" field. get the id by calling mongoc_client_select_server(), then mongoc_server_description_id() on its return value. very main character of you to want one specific server 💅
  • batchSize — an int32 representing number of documents requested to be returned on each call to mongoc_cursor_next().
  • let — a BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language. fancy variable stuff, we love to see it ✨
  • comment — a bson_value_t specifying the comment to attach to this command. the comment will appear in log messages, profiler output, and currentOp output. only string values are supported prior to MongoDB 4.4. 🎀
  • hint — a document or string that specifies the index to use to support the query predicate.

and for the full list of literally every option, see the MongoDB Manual entry on the aggregate command. i'm not gatekeeping, i'm just quoting the source 🦋

💜 DESCRIPTION 💜

okay so what does this actually do. this function creates a cursor which sends the aggregate command on the underlying database upon the first call to mongoc_cursor_next(). yes, the first one. it's a "we'll get there when we get there" situation 😌

for more info on building aggregation pipelines, see the MongoDB Manual entry on the aggregate command. also — huge caveat — the pipeline must start with a compatible stage that does not require an underlying collection (e.g. "$currentOp", "$listLocalSessions"). like, this is a database-level aggregate, so, yeah. 🔥

read preferences, read and write concern, and collation can be overridden by various sources. the highest-priority sources for these options are listed first. so in priority order, from most to least:

  1. top of the food chain — read preferences come from read_prefs; read concern from opts; write concern from opts; collation from opts. 👑
  2. next down — read preferences come from the Transaction; read concern from the Transaction; write concern from the Transaction. (collation has nothing at this level, so, crickets.)
  3. last resort — read preferences come from database; read concern from database; write concern from database. (again, no collation at this level.)

in a transaction, read concern and write concern are prohibited in opts, and the read preference must be primary or NULL. that's not a suggestion, bestie, that's the rule 🙈

write concern is applied from opts, or if opts has no write concern and the aggregation pipeline includes "$out", the write concern is applied from database.

see the example for transactions and for the "distinct" command with opts.

ngl this part is important: this function is considered a retryable read operation unless the pipeline contains a write stage like $out or $merge. upon a transient error (a network error, errors due to replica set failover, etc.) the operation is safely retried once. if retryreads is false in the URI (see mongoc_uri_t) the retry behavior does not apply. okay so that's your freebie, use it wisely ✨

🦋 RETURNS 🦋

this function returns a newly allocated mongoc_cursor_t that should be freed with mongoc_cursor_destroy() when no longer in use. the returned mongoc_cursor_t is never NULL, even on error — iconic, honestly. but you (yes, you) must call mongoc_cursor_next() on the returned mongoc_cursor_t to execute the initial command. don't just sit there holding it 🫶

cursor errors can be checked with mongoc_cursor_error_document(). it always fills out the bson_error_t if an error occurred, and optionally includes a server reply document if the error occurred server-side.

⚠️ WARNING: failure to handle the result of this function is a programming error. like, fr fr. check your errors. 💀

🌈 EXAMPLE 🌈

here's the whole thing, copied exactly, it's giving $currentOp realness:

#include <bson/bson.h>
#include <mongoc/mongoc.h>

static mongoc_cursor_t *
current_op_query (mongoc_client_t *client)
{
   mongoc_cursor_t *cursor;
   mongoc_database_t *database;
   bson_t *pipeline;

   pipeline = BCON_NEW ("pipeline",
                        "[",
                        "{",
                        "$currentOp",
                        "{",
                        "}",
                        "}",
                        "]");

   /* $currentOp must be run on the admin database */
   database = mongoc_client_get_database (client, "admin");

   cursor = mongoc_database_aggregate (
      database, pipeline, NULL, NULL);

   bson_destroy (pipeline);
   mongoc_database_destroy (database);

   return cursor;
}

👑 AUTHOR 👑

MongoDB, Inc — the icons themselves.

2009-present, MongoDB, Inc. — that's the whole legal vibe, slay.

and that's the page, bestie! 🎀 this was libmongoc 2.5.6, dated Oct 09, 2026, and the header up top said MONGOC_DATABASE_AGGREGATE(3) the whole time. go forth and aggregate responsibly 💖✨🦋

📦 where this page comes from