1MONGOC_COLLECTION_UPDATE_ONE(3)    libmongoc   MONGOC_COLLECTION_UPDATE_ONE(3)
2
3
4

NAME

6       mongoc_collection_update_one - mongoc_collection_update_one()
7

SYNOPSIS

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

PARAMETERS

18collection: A mongoc_collection_t.
19
20selector: A bson_t containing the query to match the document for up‐
21         dating.
22
23update: A bson_t containing the update to perform. If updating with a
24         pipeline, a bson_t array.
25
26reply:  Optional.  An  uninitialized bson_t populated with the update
27         result, or NULL.
28
29error: An optional location for a bson_error_t or NULL.
30
31       opts may be NULL or a BSON document with additional command options:
32
33writeConcern:  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
37sessionId:  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
44validate:     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
48bypassDocumentValidation: Set to true to skip server-side schema val‐
49         idation of the provided BSON documents.
50
51collation: 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
55hint: A document or string that specifies the index to use to support
56         the query predicate.
57
58upsert:  When true, creates a new document if no document matches the
59         query.
60
61arrayFilters: An array of filters specifying to which array  elements
62         an update should apply.
63

DESCRIPTION

65       This  function  updates at most one document in collection that matches
66       selector.
67
68       To update multiple documents see mongoc_collection_update_many.
69
70       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

ERRORS

77       Errors are propagated via the error parameter.
78

RETURNS

80       Returns true if successful. Returns false and sets error if  there  are
81       invalid arguments or a server or network error.
82
83       A write concern timeout or write concern error is considered a failure.
84

EXAMPLE

86       example-update.c
87
88          #include "mongoc/mongoc.h"
89
90          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
105             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
114             client = mongoc_client_new_from_uri (uri);
115             if (!client) {
116                return EXIT_FAILURE;
117             }
118
119             coll = mongoc_client_get_collection (client, "db", "example_coll");
120
121             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
128             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
134             to_str = bson_as_relaxed_extended_json (to_insert, NULL);
135             printf ("inserted: %s\n", to_str);
136             bson_free (to_str);
137
138             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
142             to_str = bson_as_relaxed_extended_json (next_doc, NULL);
143             printf ("%s\n", to_str);
144             bson_free (to_str);
145
146             BSON_ASSERT (mongoc_collection_drop (coll, NULL));
147
148             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
155             return EXIT_SUCCESS;
156          }
157
158
159       SEE ALSO:
160          MongoDB update command documentation for more information on the update options.
161
162          mongoc_collection_update_many
163
164          mongoc_collection_replace_one
165
166

AUTHOR

168       MongoDB, Inc
169
171       2017-present, MongoDB, Inc
172
173
174
175
1761.20.0                           Nov 18, 2021  MONGOC_COLLECTION_UPDATE_ONE(3)
Impressum