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.
24
25       · reply: Optional. An uninitialized bson_t populated  with  the  update
26         result, or NULL.
27
28       · error: An optional location for a bson_error_t or NULL.
29
30       opts may be NULL or a BSON document with additional command options:
31
32       · writeConcern:   Construct   a  mongoc_write_concern_t  and  use  mon‐
33         goc_write_concern_append to add the write concern to  opts.  See  the
34         example code for mongoc_client_write_command_with_opts.
35
36       · sessionId:  First,  construct  a  mongoc_client_session_t  with  mon‐
37         goc_client_start_session. You  can  begin  a  transaction  with  mon‐
38         goc_client_session_start_transaction, optionally with a mongoc_trans‐
39         action_opt_t that overrides the options  inherited  from  collection,
40         and  use mongoc_client_session_append to add the session to opts. See
41         the example code for mongoc_client_session_t.
42
43       · validate:    Construct    a     bitwise-or     of     all     desired
44         bson_validate_flags_t. Set to false to skip client-side validation of
45         the provided BSON documents.
46
47       · bypassDocumentValidation: Set to true to skip server-side schema val‐
48         idation of the provided BSON documents.
49
50       · collation:  Configure  textual  comparisons.  See  Setting  Collation
51         Order, and the MongoDB Manual entry on Collation. Collation  requires
52         MongoDB 3.2 or later, otherwise an error is returned.
53
54       · upsert:  When true, creates a new document if no document matches the
55         query.
56
57       · arrayFilters: An array of filters specifying to which array  elements
58         an update should apply.
59

DESCRIPTION

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

ERRORS

81       Errors are propagated via the error parameter.
82

RETURNS

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

EXAMPLE

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

AUTHOR

164       MongoDB, Inc
165

COPYRIGHT

167       2017-present, MongoDB, Inc
168
169
170
171
1721.13.1                           Jan 24, 2019  MONGOC_COLLECTION_UPDATE_ONE(3)