Insert Documents

Overview

In this guide, you can learn how to use the C driver to add documents to a MongoDB collection by performing insert operations.

An insert operation inserts one or more documents into a MongoDB collection. You can perform an insert operation by using the following functions:

• mongoc_collection_insert_one() function to insert a single document

• mongoc_collection_insert_many() function to insert one or more documents

The _id Field

In a MongoDB collection, each document must contain an _id field with a unique field value.

MongoDB allows you to manage this field in two ways:

• Set the _id field for each document yourself, ensuring each value is unique.

• Let the driver automatically generate unique bson_oid_t values for each document _id field.

Unless you can guarantee uniqueness, we recommend letting the driver automatically generate _id values.

To learn more about the _id field, see the Unique Indexes guide in the MongoDB Server manual.

To learn more about document structure and rules, see the Documents guide in the MongoDB Server manual.

Insert One Document

To add a single document to a MongoDB collection, call the mongoc_collection_insert_one() function and pass the following parameters:

• Collection into which you're inserting documents

• Document to insert

• Options to customize the operation, or NULL

• Pointer to overwritable storage that will contain operation results, or NULL

• Location for an error value, or NULL

Use the following syntax to insert a document:

bson_t *document = BCON_NEW("<field name>", BCON_UTF8("<value>"));
bson_error_t error;
if (!mongoc_collection_insert_one(
    collection, document, NULL, NULL, &error)) {
    fprintf(stderr, "Insert one operation failed: %s\n", error.message);
}
bson_destroy(document);

The following example inserts a document into the restaurants collection:

bson_t *document = BCON_NEW("name", BCON_UTF8("Mongo's Burgers"));
bson_error_t error;
if (!mongoc_collection_insert_one(collection, document, NULL, NULL, &error)) {
    fprintf(stderr, "Insert one operation failed: %s\n", error.message);
}
bson_destroy(document);

Insert Multiple Documents

To add multiple documents to a MongoDB collection, call the mongoc_collection_insert_many() function and pass the following parameters:

• Collection into which you're inserting documents

• Array of pointers to the documents you want to insert

• Number of documents to insert

• Options to customize the operation, or NULL

• Pointer to overwritable storage that will contain operation results, or NULL

• Location for an error value, or NULL

Use the following syntax to insert multiple documents:

size_t num_docs = 2;
bson_t *docs[num_docs];
docs[0] = BCON_NEW("<field name>", BCON_UTF8("<value>"));
docs[1] = BCON_NEW("<field name>", BCON_UTF8("<value>"));
bson_error_t error;
if (!mongoc_collection_insert_many(collection, (const bson_t **) docs, num_docs, NULL, NULL, &error)) {
    fprintf(stderr, "Insert many operation failed: %s\n", error.message);
}
bson_destroy(docs[0]);
bson_destroy(docs[1]);

The following example inserts two documents into the restaurants collection:

size_t num_docs = 2;
bson_t *docs[num_docs];
docs[0] = BCON_NEW("name", BCON_UTF8("Mongo's Burgers"));
docs[1] = BCON_NEW("name", BCON_UTF8("Mongo's Pizza"));
bson_error_t error;
if (!mongoc_collection_insert_many(collection, (const bson_t **) docs, num_docs, NULL, NULL, &error)) {
    fprintf(stderr, "Insert many operation failed: %s\n", error.message);
}
bson_destroy(docs[0]);
bson_destroy(docs[1]);

Modify Insert Behavior

You can modify the behavior of the mongoc_collection_insert_one() and mongoc_collection_insert_many() functions by passing a BSON document that specifies option values. The following table describes some options you can set in the document:

size_t num_docs = 3;
bson_t *docs[num_docs];
docs[0] = BCON_NEW("name", BCON_UTF8("Mongo's Burgers"));
docs[1] = BCON_NEW("name", BCON_UTF8("Mongo's Pizza"));
docs[2] = BCON_NEW("name", BCON_UTF8("Mongo's Tacos"));
bson_t opts;
bson_init(&opts);
bson_append_bool(&opts, "bypassDocumentValidation", -1, true);
bson_error_t error;
if (!mongoc_collection_insert_many(collection, (const bson_t **) docs, num_docs, &opts, NULL, &error)) {
    fprintf(stderr, "Insert many operation failed: %s\n", error.message);
}
bson_destroy(docs[0]);
bson_destroy(docs[1]);
bson_destroy(docs[2]);
bson_destroy(&opts);

Additional Information