1MONGOC_COLLECTION_UPDATE_ONE(3) libmongoc MONGOC_COLLECTION_UPDATE_ONE(3)
2
6 mongoc_collection_update_one - mongoc_collection_update_one()
7
9 bool
10 mongoc_collection_update_one (mongoc_collection_t *collection,
11 const bson_t *selector,
12 const bson_t *update,
13 const bson_t *opts,
14 bson_t *reply,
15 bson_error_t *error);
16
18 • collection: A mongoc_collection_t.
19 • selector: A bson_t containing the query to match the document for up‐
21 dating.
22 • update: A bson_t containing the update to perform. If updating with a
24 pipeline, a bson_t array.
25 • reply: Optional. An uninitialized bson_t populated with the update
27 result, or NULL.
28 • error: An optional location for a bson_error_t or NULL.
30 opts may be NULL or a BSON document with additional command options:
32 • writeConcern: Construct a mongoc_write_concern_t and use mon‐
34 goc_write_concern_append to add the write concern to opts. See the
35 example code for mongoc_client_write_command_with_opts.
36 • sessionId: First, construct a mongoc_client_session_t with mon‐
38 goc_client_start_session. You can begin a transaction with mon‐
39 goc_client_session_start_transaction, optionally with a mongoc_trans‐
40 action_opt_t that overrides the options inherited from collection,
41 and use mongoc_client_session_append to add the session to opts. See
42 the example code for mongoc_client_session_t.
43 • validate: Construct a bitwise-or of all desired
45 bson_validate_flags_t. Set to false to skip client-side validation of
46 the provided BSON documents.
47 • bypassDocumentValidation: Set to true to skip server-side schema val‐
49 idation of the provided BSON documents.
50 • collation: Configure textual comparisons. See Setting Collation Or‐
52 der, and the MongoDB Manual entry on Collation. Collation requires
53 MongoDB 3.2 or later, otherwise an error is returned.
54 • hint: A document or string that specifies the index to use to support
56 the query predicate.
57 • upsert: When true, creates a new document if no document matches the
59 query.
60 • arrayFilters: An array of filters specifying to which array elements
62 an update should apply.
63
65 This function updates at most one document in collection that matches
66 selector.
67 To update multiple documents see mongoc_collection_update_many.
69 If you pass a non-NULL reply, it is filled out with fields matched‐
71 Count, modifiedCount, and optionally upsertedId if applicable. If there
72 is a server error then reply contains either a "writeErrors" array with
73 one subdocument or a "writeConcernErrors" array. The reply must be
74 freed with bson_destroy().
75
77 Errors are propagated via the error parameter.
78
80 Returns true if successful. Returns false and sets error if there are
81 invalid arguments or a server or network error.
82 A write concern timeout or write concern error is considered a failure.
84
86 example-update.c
87 #include "mongoc/mongoc.h"
89 int
91 main (int argc, char **argv)
92 {
93 bson_t *to_insert = BCON_NEW ("_id", BCON_INT32 (1));
94 bson_t *selector = BCON_NEW ("_id", "{", "$gt", BCON_INT32 (0), "}");
95 bson_t *update = BCON_NEW ("$set", "{", "x", BCON_INT32 (1), "}");
96 const bson_t *next_doc;
97 char *to_str;
98 bson_error_t error = {0};
99 mongoc_cursor_t *cursor;
100 mongoc_client_t *client;
101 mongoc_collection_t *coll;
102 const char *uri_string = "mongodb://localhost:27017/?appname=example-update";
103 mongoc_uri_t *uri = mongoc_uri_new_with_error (uri_string, &error);
104 if (!uri) {
106 fprintf (stderr,
107 "failed to parse URI: %s\n"
108 "error message: %s\n",
109 uri_string,
110 error.message);
111 return EXIT_FAILURE;
112 }
113 client = mongoc_client_new_from_uri (uri);
115 if (!client) {
116 return EXIT_FAILURE;
117 }
118 coll = mongoc_client_get_collection (client, "db", "example_coll");
120 mongoc_client_set_error_api (client, 2);
122 /* insert a document */
123 if (!mongoc_collection_insert_one (coll, to_insert, NULL, NULL, &error)) {
124 fprintf (stderr, "insert failed: %s\n", error.message);
125 return EXIT_FAILURE;
126 }
127 if (!mongoc_collection_update_one (
129 coll, selector, update, NULL, NULL, &error)) {
130 fprintf (stderr, "update failed: %s\n", error.message);
131 return EXIT_FAILURE;
132 }
133 to_str = bson_as_relaxed_extended_json (to_insert, NULL);
135 printf ("inserted: %s\n", to_str);
136 bson_free (to_str);
137 cursor = mongoc_collection_find_with_opts (coll, selector, NULL, NULL);
139 BSON_ASSERT (mongoc_cursor_next (cursor, &next_doc));
140 printf ("after update, collection has the following document:\n");
141 to_str = bson_as_relaxed_extended_json (next_doc, NULL);
143 printf ("%s\n", to_str);
144 bson_free (to_str);
145 BSON_ASSERT (mongoc_collection_drop (coll, NULL));
147 bson_destroy (to_insert);
149 bson_destroy (update);
150 bson_destroy (selector);
151 mongoc_collection_destroy (coll);
152 mongoc_uri_destroy (uri);
153 mongoc_client_destroy (client);
154 return EXIT_SUCCESS;
156 }
157 SEE ALSO:
160 MongoDB update command documentation for more information on the update options.
161 mongoc_collection_update_many
163 mongoc_collection_replace_one
165
168 MongoDB, Inc
169
171 2017-present, MongoDB, Inc
1721.20.0 Nov 18, 2021 MONGOC_COLLECTION_UPDATE_ONE(3)