1MONGOC_CLIENT_READ_COMMAND_WITH_MOoPnTgSo(D3B)CMODNrGiOvCe_rCLIENT_READ_COMMAND_WITH_OPTS(3)
2
3
4

NAME

6       mongoc_client_read_command_with_opts      -     mongoc_client_read_com‐
7       mand_with_opts()
8

SYNOPSIS

10          bool
11          mongoc_client_read_command_with_opts (mongoc_client_t *client,
12                                                const char *db_name,
13                                                const bson_t *command,
14                                                const mongoc_read_prefs_t *read_prefs,
15                                                const bson_t *opts,
16                                                bson_t *reply,
17                                                bson_error_t *error);
18
19       Execute a command on the server, applying logic  that  is  specific  to
20       commands that read, and taking the MongoDB server version into account.
21       To send a raw command to the server without any of this logic, use mon‐
22       goc_client_command_simple.
23
24       Use this function for commands that read such as "count" or "distinct".
25
26       Read preferences, read concern, and collation can be overridden by var‐
27       ious sources. In a transaction, read concern and write concern are pro‐
28       hibited  in  opts  and the read preference must be primary or NULL. The
29       highest-priority sources for these options are listed first in the fol‐
30       lowing table. No write concern is applied.
31
32                    ┌─────────────────┬──────────────┬───────────┐
33                    │Read Preferences │ Read Concern │ Collation │
34                    ├─────────────────┼──────────────┼───────────┤
35read_prefs       opts         opts      
36                    ├─────────────────┼──────────────┼───────────┤
37                    │Transaction      │ Transaction  │           │
38                    ├─────────────────┼──────────────┼───────────┤
39client           │              │           │
40                    └─────────────────┴──────────────┴───────────┘
41
42       See  the  example  for transactions and for the "distinct" command with
43       opts.
44
45       reply is always initialized, and must be freed with bson_destroy().
46

PARAMETERS

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

ERRORS

88       Errors are propagated via the error parameter.
89

RETURNS

91       Returns  true  if successful. Returns false and sets error if there are
92       invalid arguments or a server or network error.
93

EXAMPLE

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

AUTHOR

247       MongoDB, Inc
248
250       2017-present, MongoDB, Inc
251
252
253
254
2551.14.0                           Feb 22,MO2N0G1O9C_CLIENT_READ_COMMAND_WITH_OPTS(3)
Impressum