MONGOC_COLLECTION_INSERT_ONE(3)

📦
version 2.5.6 · 16 versions
, in epel 10

💖 mongoc_collection_insert_one — the libmongoc era 💖

okay so bestie, this is the MONGOC_COLLECTION_INSERT_ONE(3) page from libmongoc, and it's literally the "put one (1) document into a collection" function. one doc. singular. no cap. if you've got a whole array to shove in, she's gonna point you elsewhere (spoiler: mongoc_collection_insert_many()). let's get into it 🫶

✨ SYNOPSIS ✨

bool
mongoc_collection_insert_one (mongoc_collection_t *collection,
                              const bson_t *document,
                              const bson_t *opts,
                              bson_t *reply,
                              bson_error_t *error);

look at her. five args. iconic signature, no notes 💅

🌸 PARAMETERS 🌸

  • collection: a mongoc_collection_t. the collection. the destination. main character energy.
  • document: a bson_t. the one (1) doc going in 💌
  • reply: a maybe-NULL pointer to overwritable storage for a bson_t that's gonna hold the results.
  • error: an optional location for a bson_error_t, or NULL if you're built different and don't want to know.

and then opts… opts may be NULL, or it can be a BSON document with extra command options. here's the whole menu, don't skip a single item, i'm watching 👀:

  • writeConcern — construct a mongoc_write_concern_t and use mongoc_write_concern_append() to add the write concern to opts. there's example code over on mongoc_client_write_command_with_opts() if you need the vibe ✍️
  • 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 collection, and use mongoc_client_session_append() to add the session to opts. again, example code lives at mongoc_client_session_t. go look, i'll wait 🧚
  • validate — construct a bitwise-or of all the bson_validate_flags_t you desire. set it to false to skip client-side validation of the provided BSON documents. bold move but ok 🙈
  • 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. requires MongoDB 4.4 or later ⭐
  • bypassDocumentValidation — set to true to skip server-side schema validation of the provided BSON documents. living dangerously, love that for you 🔥

🦋 DESCRIPTION 🦋

this function shall insert document into collection. that's it. that's the whole job. slay.

to insert an array of documents, see mongoc_collection_insert_many(). she does bulk, this one does one.

if no _id element is found in document, then a bson_oid_t will be generated locally and added to the document. so like, she'll give your doc an id if it forgot its own. so thoughtful 🎀

if you pass a non-NULL reply, it is filled out with an "insertedCount" field. and if the document was successfully inserted, reply will also contain an "insertedId" field containing the inserted document's _id. but if there's a server error, then reply contains either a "writeErrors" array with one subdocument or a "writeConcernErrors" array.

⚠️ bestie the reply must be freed with bson_destroy(). do NOT forget. that's a leak and leaks are not cute 💀

😭 ERRORS 😭

errors are propagated via the error parameter. that's the whole section. short and honest.

👑 RETURNS 👑

returns true if successful. returns false and sets error if there are invalid arguments or a server or network error.

a write concern timeout or write concern error is considered a failure. yes, even the write concern ones. fr fr.

🍓 AUTHOR 🍓

MongoDB, Inc

2009-present, MongoDB, Inc.

and that's the page!! mwah 💋 — brought to you by libmongoc version 2.5.6, dated Oct 09, 2026. go forth and insert exactly one (1) document, bestie. periodt 🌸🫶✨

📦 where this page comes from