mongoc_collection_update_one(3)

1MONGOC_COLLECTION_UPDATE_ONE(3)MongoDB C DriverMONGOC_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

18       · collection: A mongoc_collection_t.
19
20       · selector:  A  bson_t  containing  the query to match the document for
21         updating.
22
23       · update: A bson_t containing the update to perform. If updating with a
24         pipeline, a bson_t array.
25
26       · reply:  Optional.  An  uninitialized bson_t populated with the update
27         result, or NULL.
28
29       · error: 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
33       · 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
37       · 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
44       · 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
48       · bypassDocumentValidation: Set to true to skip server-side schema val‐
49         idation of the provided BSON documents.
50
51       · collation:  Configure  textual  comparisons.  See  Setting  Collation
52         Order,  and the MongoDB Manual entry on Collation. Collation requires
53         MongoDB 3.2 or later, otherwise an error is returned.
54
55       · upsert: When true, creates a new document if no document matches  the
56         query.
57
58       · arrayFilters:  An array of filters specifying to which array elements
59         an update should apply.
60

DESCRIPTION

62       This function updates at most one document in collection  that  matches
63       selector.
64
65       To update multiple documents see mongoc_collection_update_many.
66
67       If  you  pass  a non-NULL reply, it is filled out with fields  matched‐
68       Count, modifiedCount, and optionally upsertedId if applicable. If there
69       is a server error then reply contains either a "writeErrors" array with
70       one subdocument or a "writeConcernErrors"  array.  The  reply  must  be
71       freed with bson_destroy().
72

ERRORS

82       Errors are propagated via the error parameter.
83

RETURNS

85       Returns true if successful. Returns false and sets error if  there  are
86       invalid arguments or a server or network error.
87
88       A write concern timeout or write concern error is considered a failure.
89

EXAMPLE

91       example-update.c.INDENT 0.0
92
93          #include "mongoc/mongoc.h"
94
95          int
96          main (int argc, char **argv)
97          {
98             bson_t *to_insert = BCON_NEW ("_id", BCON_INT32 (1));
99             bson_t *selector = BCON_NEW ("_id", "{", "$gt", BCON_INT32 (0), "}");
100             bson_t *update = BCON_NEW ("$set", "{", "x", BCON_INT32 (1), "}");
101             const bson_t *next_doc;
102             char *to_str;
103             bson_error_t error = {0};
104             mongoc_cursor_t *cursor;
105             mongoc_client_t *client;
106             mongoc_collection_t *coll;
107             const char *uri_string = "mongodb://localhost:27017/?appname=example-update";
108             mongoc_uri_t *uri = mongoc_uri_new_with_error (uri_string, &error);
109
110             if (!uri) {
111                fprintf (stderr,
112                         "failed to parse URI: %s\n"
113                         "error message:       %s\n",
114                         uri_string,
115                         error.message);
116                return EXIT_FAILURE;
117             }
118
119             client = mongoc_client_new_from_uri (uri);
120             if (!client) {
121                return EXIT_FAILURE;
122             }
123
124             coll = mongoc_client_get_collection (client, "db", "example_coll");
125
126             mongoc_client_set_error_api (client, 2);
127             /* insert a document */
128             if (!mongoc_collection_insert_one (coll, to_insert, NULL, NULL, &error)) {
129                fprintf (stderr, "insert failed: %s\n", error.message);
130                return EXIT_FAILURE;
131             }
132
133             if (!mongoc_collection_update_one (
134                    coll, selector, update, NULL, NULL, &error)) {
135                fprintf (stderr, "update failed: %s\n", error.message);
136                return EXIT_FAILURE;
137             }
138
139             to_str = bson_as_relaxed_extended_json (to_insert, NULL);
140             printf ("inserted: %s\n", to_str);
141             bson_free (to_str);
142
143             cursor = mongoc_collection_find_with_opts (coll, selector, NULL, NULL);
144             BSON_ASSERT (mongoc_cursor_next (cursor, &next_doc));
145             printf ("after update, collection has the following document:\n");
146
147             to_str = bson_as_relaxed_extended_json (next_doc, NULL);
148             printf ("%s\n", to_str);
149             bson_free (to_str);
150
151             BSON_ASSERT (mongoc_collection_drop (coll, NULL));
152
153             bson_destroy (to_insert);
154             bson_destroy (update);
155             bson_destroy (selector);
156             mongoc_collection_destroy (coll);
157             mongoc_uri_destroy (uri);
158             mongoc_client_destroy (client);
159
160             return EXIT_SUCCESS;
161          }
162
163

AUTHOR

165       MongoDB, Inc
166

COPYRIGHT

168       2017-present, MongoDB, Inc
169
170
171
172
1731.15.2                           Nov 06, 2019  MONGOC_COLLECTION_UPDATE_ONE(3)