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
47       This function is considered a retryable read operation.  Upon  a  tran‐
48       sient error (a network error, errors due to replica set failover, etc.)
49       the operation is safely retried once.  If retryreads is  false  in  the
50       URI (see mongoc_uri_t) the retry behavior does not apply.
51
52       Retry  logic  occurs  regardless  of  the  underlying command. Retrying
53       mapReduce has the potential for degraded performance.  Retrying a  get‐
54       More command has the potential to miss results. For those commands, use
55       generic command helpers (like mongoc_client_command_with_opts) instead.
56

PARAMETERS

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

ERRORS

98       Errors are propagated via the error parameter.
99

RETURNS

101       Returns  true  if successful. Returns false and sets error if there are
102       invalid arguments or a server or network error.
103

EXAMPLE

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

AUTHOR

257       MongoDB, Inc
258
260       2017-present, MongoDB, Inc
261
262
263
264
2651.15.2                           Nov 06,MO2N0G1O9C_CLIENT_READ_COMMAND_WITH_OPTS(3)
Impressum