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
34 mongoc_write_concern_append() to add the write concern to opts. See
35 the example code for mongoc_client_write_command_with_opts().
36 • sessionId: First, construct a mongoc_client_session_t with
38 mongoc_client_start_session(). You can begin a transaction with
39 mongoc_client_session_start_transaction(), optionally with a
40 mongoc_transaction_opt_t that overrides the options inherited from
41 collection, and use mongoc_client_session_append() to add the session
42 to opts. See 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 • comment: A bson_value_t specifying the comment to attach to this com‐
49 mand. The comment will appear in log messages, profiler output, and
50 currentOp output. Requires MongoDB 4.4 or later.
51 • bypassDocumentValidation: Set to true to skip server-side schema val‐
53 idation of the provided BSON documents.
54 • collation: Configure textual comparisons. See Setting Collation Or‐
56 der, and the MongoDB Manual entry on Collation. Collation requires
57 MongoDB 3.2 or later, otherwise an error is returned.
58 • hint: A document or string that specifies the index to use to support
60 the query predicate.
61 • upsert: When true, creates a new document if no document matches the
63 query.
64 • let: A BSON document consisting of any number of parameter names,
66 each followed by definitions of constants in the MQL Aggregate Ex‐
67 pression language.
68 • arrayFilters: An array of filters specifying to which array elements
70 an update should apply.
71
73 This function updates at most one document in collection that matches
74 selector.
75 To update multiple documents see mongoc_collection_update_many().
77 If you pass a non-NULL reply, it is filled out with fields matched‐
79 Count, modifiedCount, and optionally upsertedId if applicable. If there
80 is a server error then reply contains either a "writeErrors" array with
81 one subdocument or a "writeConcernErrors" array. The reply must be
82 freed with bson_destroy().
83
85 Errors are propagated via the error parameter.
86
88 Returns true if successful. Returns false and sets error if there are
89 invalid arguments or a server or network error.
90 A write concern timeout or write concern error is considered a failure.
92
94 example-update.c
95 #include "mongoc/mongoc.h"
97 int
99 main (void)
100 {
101 bson_t *to_insert = BCON_NEW ("_id", BCON_INT32 (1));
102 bson_t *selector = BCON_NEW ("_id", "{", "$gt", BCON_INT32 (0), "}");
103 bson_t *update = BCON_NEW ("$set", "{", "x", BCON_INT32 (1), "}");
104 const bson_t *next_doc;
105 char *to_str;
106 bson_error_t error = {0};
107 mongoc_cursor_t *cursor;
108 mongoc_client_t *client;
109 mongoc_collection_t *coll;
110 const char *uri_string = "mongodb://localhost:27017/?appname=example-update";
111 mongoc_uri_t *uri = mongoc_uri_new_with_error (uri_string, &error);
112 if (!uri) {
114 fprintf (stderr,
115 "failed to parse URI: %s\n"
116 "error message: %s\n",
117 uri_string,
118 error.message);
119 return EXIT_FAILURE;
120 }
121 client = mongoc_client_new_from_uri (uri);
123 if (!client) {
124 return EXIT_FAILURE;
125 }
126 coll = mongoc_client_get_collection (client, "db", "example_coll");
128 mongoc_client_set_error_api (client, 2);
130 /* insert a document */
131 if (!mongoc_collection_insert_one (coll, to_insert, NULL, NULL, &error)) {
132 fprintf (stderr, "insert failed: %s\n", error.message);
133 return EXIT_FAILURE;
134 }
135 if (!mongoc_collection_update_one (
137 coll, selector, update, NULL, NULL, &error)) {
138 fprintf (stderr, "update failed: %s\n", error.message);
139 return EXIT_FAILURE;
140 }
141 to_str = bson_as_relaxed_extended_json (to_insert, NULL);
143 printf ("inserted: %s\n", to_str);
144 bson_free (to_str);
145 cursor = mongoc_collection_find_with_opts (coll, selector, NULL, NULL);
147 BSON_ASSERT (mongoc_cursor_next (cursor, &next_doc));
148 printf ("after update, collection has the following document:\n");
149 to_str = bson_as_relaxed_extended_json (next_doc, NULL);
151 printf ("%s\n", to_str);
152 bson_free (to_str);
153 BSON_ASSERT (mongoc_collection_drop (coll, NULL));
155 bson_destroy (to_insert);
157 bson_destroy (update);
158 bson_destroy (selector);
159 mongoc_collection_destroy (coll);
160 mongoc_uri_destroy (uri);
161 mongoc_client_destroy (client);
162 return EXIT_SUCCESS;
164 }
165 SEE ALSO:
168 MongoDB update command documentation for more information on the update options.
169 mongoc_collection_update_many()
171 mongoc_collection_replace_one()
173
176 MongoDB, Inc
177
179 2017-present, MongoDB, Inc
1801.24.3 Aug 17, 2023 MONGOC_COLLECTION_UPDATE_ONE(3)