1MONGOC_CLIENT_WRITE_COMMAND_WITH_OPTlSi(b3mM)oOnNgGoOcC_CLIENT_WRITE_COMMAND_WITH_OPTS(3)
2
3
4

NAME

6       mongoc_client_write_command_with_opts     -    mongoc_client_write_com‐
7       mand_with_opts()
8

SYNOPSIS

10          bool
11          mongoc_client_write_command_with_opts (mongoc_client_t *client,
12                                                 const char *db_name,
13                                                 const bson_t *command,
14                                                 const bson_t *opts,
15                                                 bson_t *reply,
16                                                 bson_error_t *error);
17
18       Execute a command on the server, applying logic  that  is  specific  to
19       commands  that  write,  and  taking the MongoDB server version into ac‐
20       count. To send a raw command to the server without any of  this  logic,
21       use mongoc_client_command_simple().
22
23       Use  this  function  for commands that write such as "drop" or "create‐
24       Role" (but not for "insert", "update", or "delete", see Basic Write Op‐
25       erations).  Write  concern  and  collation can be overridden by various
26       sources. In a transaction, read concern and write concern  are  prohib‐
27       ited in opts. The highest-priority sources for these options are listed
28       first in the following table. The write concern is omitted for  MongoDB
29       before 3.4.
30
31                             ┌──────────────┬───────────┐
32                             │Write Concern │ Collation │
33                             ├──────────────┼───────────┤
34opts          opts      
35                             ├──────────────┼───────────┤
36                             │Transaction   │           │
37                             ├──────────────┼───────────┤
38client        │           │
39                             └──────────────┴───────────┘
40
41       See  the  example  for transactions and for the "distinct" command with
42       opts.
43
44       reply is always initialized, and must be freed with bson_destroy().
45

PARAMETERS

47client: A mongoc_client_t.
48
49db_name: The name of the database to run the command on.
50
51command: A bson_t containing the command specification.
52
53opts: A bson_t containing additional options.
54
55reply: A location for the resulting document.
56
57error: An optional location for a bson_error_t or NULL.
58
59       opts may be NULL or a BSON document with additional command options:
60
61writeConcern:   Construct   a    mongoc_write_concern_t    and    use
62         mongoc_write_concern_append()  to  add the write concern to opts. See
63         the example code for mongoc_client_write_command_with_opts().
64
65sessionId:   First,   construct   a   mongoc_client_session_t    with
66         mongoc_client_start_session().  You  can  begin  a  transaction  with
67         mongoc_client_session_start_transaction(),    optionally    with    a
68         mongoc_transaction_opt_t  that  overrides  the options inherited from
69         client, and use mongoc_client_session_append() to add the session  to
70         opts. See the example code for mongoc_client_session_t.
71
72collation:  Configure  textual comparisons. See Setting Collation Or‐
73         der, and the MongoDB Manual entry on  Collation.  Collation  requires
74         MongoDB 3.2 or later, otherwise an error is returned.
75
76serverId:  To  target  a specific server, include an int32 "serverId"
77         field. Obtain the id by calling  mongoc_client_select_server(),  then
78         mongoc_server_description_id() on its return value.
79
80       Consult  the  MongoDB  Manual  entry on Database Commands for each com‐
81       mand's arguments.
82

ERRORS

84       Errors are propagated via the error parameter.
85

RETURNS

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

BASIC WRITE OPERATIONS

93       Do  not  use  this  function to call the basic write commands "insert",
94       "update", and "delete". Those commands require special logic not imple‐
95       mented in mongoc_client_write_command_with_opts. For basic write opera‐
96       tions use CRUD functions such as mongoc_collection_insert_one() and the
97       others described in the CRUD tutorial, or use the Bulk API.
98

EXAMPLE

100       example-command-with-opts.c
101
102          /*
103
104          Demonstrates how to prepare options for mongoc_client_read_command_with_opts and
105          mongoc_client_write_command_with_opts. First it calls "cloneCollectionAsCapped"
106          command with "writeConcern" option, then "distinct" command with "collation" and
107          "readConcern" options,
108
109          Start a MongoDB 3.4 replica set with --enableMajorityReadConcern and insert two
110          documents:
111
112          $ mongo
113          MongoDB Enterprise replset:PRIMARY> db.my_collection.insert({x: 1, y: "One"})
114          WriteResult({ "nInserted" : 1 })
115          MongoDB Enterprise replset:PRIMARY> db.my_collection.insert({x: 2, y: "Two"})
116          WriteResult({ "nInserted" : 1 })
117
118          Build and run the example:
119
120          gcc example-command-with-opts.c -o example-command-with-opts $(pkg-config
121          --cflags --libs libmongoc-1.0)
122          ./example-command-with-opts [CONNECTION_STRING]
123          cloneCollectionAsCapped: { "ok" : 1 }
124          distinct: { "values" : [ 1, 2 ], "ok" : 1 }
125
126          */
127
128          #include <mongoc/mongoc.h>
129          #include <stdio.h>
130          #include <stdlib.h>
131
132          int
133          main (int argc, char *argv[])
134          {
135             mongoc_client_t *client;
136             const char *uri_string = "mongodb://127.0.0.1/?appname=client-example";
137             mongoc_uri_t *uri;
138             bson_t *cmd;
139             bson_t *opts;
140             mongoc_write_concern_t *write_concern;
141             mongoc_read_prefs_t *read_prefs;
142             mongoc_read_concern_t *read_concern;
143             bson_t reply;
144             bson_error_t error;
145             char *json;
146
147             mongoc_init ();
148
149             if (argc > 1) {
150                uri_string = argv[1];
151             }
152
153             uri = mongoc_uri_new_with_error (uri_string, &error);
154             if (!uri) {
155                fprintf (stderr,
156                         "failed to parse URI: %s\n"
157                         "error message:       %s\n",
158                         uri_string,
159                         error.message);
160                return EXIT_FAILURE;
161             }
162
163             client = mongoc_client_new_from_uri (uri);
164             if (!client) {
165                return EXIT_FAILURE;
166             }
167
168             mongoc_client_set_error_api (client, 2);
169
170             cmd = BCON_NEW ("cloneCollectionAsCapped",
171                             BCON_UTF8 ("my_collection"),
172                             "toCollection",
173                             BCON_UTF8 ("my_capped_collection"),
174                             "size",
175                             BCON_INT64 (1024 * 1024));
176
177             /* include write concern "majority" in command options */
178             write_concern = mongoc_write_concern_new ();
179             mongoc_write_concern_set_wmajority (write_concern, 10000 /* wtimeoutMS */);
180             opts = bson_new ();
181             mongoc_write_concern_append (write_concern, opts);
182
183             if (mongoc_client_write_command_with_opts (
184                    client, "test", cmd, opts, &reply, &error)) {
185                json = bson_as_canonical_extended_json (&reply, NULL);
186                printf ("cloneCollectionAsCapped: %s\n", json);
187                bson_free (json);
188             } else {
189                fprintf (stderr, "cloneCollectionAsCapped: %s\n", error.message);
190             }
191
192             bson_free (cmd);
193             bson_free (opts);
194
195             /* distinct values of "x" in "my_collection" where "y" sorts after "one" */
196             cmd = BCON_NEW ("distinct",
197                             BCON_UTF8 ("my_collection"),
198                             "key",
199                             BCON_UTF8 ("x"),
200                             "query",
201                             "{",
202                             "y",
203                             "{",
204                             "$gt",
205                             BCON_UTF8 ("one"),
206                             "}",
207                             "}");
208
209             read_prefs = mongoc_read_prefs_new (MONGOC_READ_SECONDARY);
210
211             /* "One" normally sorts before "one"; make "One" sort after "one" */
212             opts = BCON_NEW ("collation",
213                              "{",
214                              "locale",
215                              BCON_UTF8 ("en_US"),
216                              "caseFirst",
217                              BCON_UTF8 ("lower"),
218                              "}");
219
220             /* add a read concern to "opts" */
221             read_concern = mongoc_read_concern_new ();
222             mongoc_read_concern_set_level (read_concern,
223                                            MONGOC_READ_CONCERN_LEVEL_MAJORITY);
224
225             mongoc_read_concern_append (read_concern, opts);
226
227             if (mongoc_client_read_command_with_opts (
228                    client, "test", cmd, read_prefs, opts, &reply, &error)) {
229                json = bson_as_canonical_extended_json (&reply, NULL);
230                printf ("distinct: %s\n", json);
231                bson_free (json);
232             } else {
233                fprintf (stderr, "distinct: %s\n", error.message);
234             }
235
236             bson_destroy (cmd);
237             bson_destroy (opts);
238             bson_destroy (&reply);
239             mongoc_read_prefs_destroy (read_prefs);
240             mongoc_read_concern_destroy (read_concern);
241             mongoc_write_concern_destroy (write_concern);
242             mongoc_uri_destroy (uri);
243             mongoc_client_destroy (client);
244
245             mongoc_cleanup ();
246
247             return EXIT_SUCCESS;
248          }
249
250

AUTHOR

252       MongoDB, Inc
253
255       2017-present, MongoDB, Inc
256
257
258
259
2601.23.1                           Oct 20M,ON2G0O2C2_CLIENT_WRITE_COMMAND_WITH_OPTS(3)
Impressum