Docs Menu
Docs Home
/
Languages
/
C Driver
/
C Driver

Configure Operations on Replica Sets

On this page

  • Overview
  • Write Concern
  • Read Concern
  • Read Preference
  • API Documentation

Overview

In this guide, you can learn how to use the write concern, read concern, and read preference configurations to modify the way that MongoDB runs create, read, update, and delete (CRUD) operations on replica sets.

You can set these configurations at the following levels:

  1. Client, which sets the default for all operation executions unless overridden

  2. Transaction

  3. Database

  4. Collection

The preceding list is in increasing order of precedence. For example, if you set read concerns at both the client and the database levels, the read concern specified at the database level overrides the read concern at the client level.

Write Concern

Write concern specifies the level of acknowledgement requested from MongoDB for write operations before the operation successfully returns. Operations that don't specify an explicit write concern inherit the global default write concern setting.

You can set the write concern by calling the following functions:

  • mongoc_client_set_write_concern() sets the write concern on a client.

  • mongoc_transaction_opts_set_write_concern() sets the write concern on a transaction.

  • mongoc_database_set_write_concern() sets the write concern on a databse.

  • mongoc_collection_set_write_concern() sets the write concern on a collection.

To specify the level of your write concern, call the mongoc_write_concern_set_w() function, and pass in your write concern and one of the following values:

  • MONGOC_WRITE_CONCERN_W_DEFAULT: The write operation returns after the operation is written to memory.

  • 0: The write operation returns after the primary node processes the write operation.

  • 1: The write operation returns after only the primary node acknowledges the write operation, without waiting for acknowledgement from secondary nodes.

  • MONGOC_WRITE_CONCERN_W_MAJORITY: The write operation returns after a majority of the replica set members acknowledge the write operation.

  • MONGOC_WRITE_CONCERN_W_TAG: The write operation returns after the replica set member with the specified tag acknowledges the write operation.

The following example sets the write concern to MONGOC_WRITE_CONCERN_W_MAJORITY for an instance of mongoc_client_t:

// Create a new client instance
mongoc_client_t *client = mongoc_client_new ("<connection string>");
// Create a new write concern
mongoc_write_concern_t *write_concern = mongoc_write_concern_new ();
mongoc_write_concern_set_w (write_concern, MONGOC_WRITE_CONCERN_W_MAJORITY);
// Set the write concern on the client
mongoc_client_set_write_concern (client, write_concern);

The following example sets the write concern to MONGOC_WRITE_CONCERN_W_MAJORITY for a collection:

mongoc_collection_t *collection = mongoc_client_get_collection (client, "<database name>", "<collection name>");
// Create a new write concern
mongoc_write_concern_t *write_concern = mongoc_write_concern_new ();
mongoc_write_concern_set_w (write_concern, MONGOC_WRITE_CONCERN_W_MAJORITY);
// Set the write concern on the collection
mongoc_collection_set_write_concern (collection, write_concern);

Note

Collections and Databases are Immutable

mongoc_database_t and mongoc_collection_t instances are immutable. When you set the write concern on a database or collection, the method returns a new instance and does not affect the original instance.

For more information about write concern, see Write Concern in the MongoDB Server manual.

Read Concern

Read concern specifies the following behaviors:

You can specify the read concern by calling the following functions:

  • mongoc_client_set_read_concern() sets the read concern on a client.

  • mongoc_transaction_opts_set_read_concern() sets the read concern on a transaction.

  • mongoc_database_set_read_concern() sets the read concern on a database.

  • mongoc_collection_set_read_concern() sets the read concern on a collection.

To specify the level of your read concern, call the mongoc_read_concern_set_level() function, and pass in your read concern and one of the following values:

  • MONGOC_READ_CONCERN_LEVEL_LOCAL: The query returns the instance's most recent data. Provides no guarantee that the data has been written to a majority of the replica set members.

  • MONGOC_READ_CONCERN_LEVEL_AVAILABLE: The query returns the instance's most recent data. Provides no guarantee that the data has been written to a majority of the replica set members. ReadConcern.AVAILABLE is not available for use with causally consistent sessions and transactions.

  • MONGOC_READ_CONCERN_LEVEL_MAJORITY: The query returns data that has been acknowledged by a majority of the replica set members.

  • MONGOC_READ_CONCERN_LEVEL_LINEARIZABLE: The query returns data that reflects all successful writes that completed prior to the start of the read operation. MONGOC_READ_CONCERN_LEVEL_LINEARIZABLE is not available for use with causally consistent sessions and transactions.

  • MONGOC_READ_CONCERN_LEVEL_SNAPSHOT: The query returns majority-committed data as it appears across shards, from a specific single point in the recent past.

For more information about the read concern levels, see Read Concern Levels in the MongoDB Server manual.

The following example sets the read concern to MONGOC_READ_CONCERN_LEVEL_MAJORITY for an instance of mongoc_client_t:

mongoc_client_t *client = mongoc_client_new ("<connection string>");
// Create a new read concern
mongoc_read_concern_t *read_concern = mongoc_read_concern_new ();
// Set the read concern level
mongoc_read_concern_set_level (read_concern, MONGOC_READ_CONCERN_LEVEL_MAJORITY);
// Set the read concern on the client
mongoc_client_set_read_concern (client, read_concern);

The following example sets the read concern to MONGOC_READ_CONCERN_LEVEL_MAJORITY for a collection:

mongoc_collection_t *collection = mongoc_client_get_collection (client, "<database name>", "<collection name>");
// Create a new read concern
mongoc_read_concern_t *read_concern = mongoc_read_concern_new ();
// Set the read concern level
mongoc_read_concern_set_level (read_concern, MONGOC_READ_CONCERN_LEVEL_MAJORITY);
// Set the read concern on the collection
mongoc_collection_set_read_concern (collection, read_concern);

To learn more about read concern, see Read Concern in the MongoDB Server manual.

Read Preference

Read preference determines which member of a replica set MongoDB reads when running a query. You can set the read preference by calling the following functions:

  • mongoc_client_set_read_prefs() sets the read preference on a client.

  • mongoc_transaction_opts_set_read_prefs() sets the read preference on a transaction.

  • mongoc_database_set_read_prefs() sets the read preference on a database.

  • mongoc_collection_set_read_prefs() sets the read preference on a collection.

To specify the level of your read preference, call the mongoc_read_prefs_new() function, and pass in one of the following values:

  • MONGOC_READ_PRIMARY: The query returns data from the primary node.

  • MONGOC_READ_PRIMARY_PREFERRED: The query returns data from the primary node if available. Otherwise, the query returns data from a secondary node.

  • MONGOC_READ_SECONDARY: The query returns data from a secondary node.

  • MONGOC_READ_SECONDARY_PREFERRED: The query returns data from a secondary node if available, Otherwise, the query returns data from the primary node.

  • MONGOC_READ_NEAREST: The query returns data from the node with the lowest network latency.

The following example sets the read preference to MONGOC_READ_SECONDARY for an instance of mongoc_client_t:

mongoc_client_t *client = mongoc_client_new ("<connection string>");
// Create a new read preference
mongoc_read_prefs_t *read_prefs = mongoc_read_prefs_new (MONGOC_READ_SECONDARY);
// Set the read preference on the client
mongoc_client_set_read_prefs (client, read_prefs);

The following example sets the read preference to MONGOC_READ_SECONDARY for a collection:

mongoc_collection_t *collection = mongoc_client_get_collection (client, "<database name>", "<collection name>");
// Create a new read preference
mongoc_read_prefs_t *read_prefs = mongoc_read_prefs_new (MONGOC_READ_SECONDARY);
// Set the read preference on the collection
mongoc_collection_set_read_prefs (collection, read_prefs);

For more information about read preference, see Read Preference in the MongoDB Server manual.

API Documentation

To learn more about any of the functions or types discussed in this guide, see the following API documentation:

Back

Build the Driver

Next

What's New