1MONGOC_COLLECTION_FIND(3) libmongoc MONGOC_COLLECTION_FIND(3)
2
6 mongoc_collection_find - mongoc_collection_find()
7
9 This function is deprecated and should not be used in new code.
10 Use the more convenient mongoc_collection_find_with_opts instead.
12
14 mongoc_cursor_t *
15 mongoc_collection_find (mongoc_collection_t *collection,
16 mongoc_query_flags_t flags,
17 uint32_t skip,
18 uint32_t limit,
19 uint32_t batch_size,
20 const bson_t *query,
21 const bson_t *fields,
22 const mongoc_read_prefs_t *read_prefs)
23 BSON_GNUC_DEPRECATED_FOR (mongoc_collection_find_with_opts)
24 BSON_GNUC_WARN_UNUSED_RESULT;
25
27 • collection: A mongoc_collection_t.
28 • flags: A mongoc_query_flags_t.
30 • skip: A uint32_t of number of documents to skip or 0.
32 • limit: A uint32_t of max number of documents to return or 0.
34 • batch_size: A uint32_t containing batch size of document result sets
36 or 0 for default. Default is 100.
37 • query: A bson_t containing the query and options to execute.
39 • fields: A bson_t containing fields to return or NULL.
41 • read_prefs: A mongoc_read_prefs_t or NULL for default read prefer‐
43 ences.
44
46 This function shall execute a query on the underlying collection.
47 If no options are necessary, query can simply contain a query such as
49 {a:1}. If you would like to specify options such as a sort order, the
50 query must be placed inside of {"$query": {}}. See the example below
51 for how to properly specify additional options to query.
52 This function is considered a retryable read operation. Upon a tran‐
54 sient error (a network error, errors due to replica set failover, etc.)
55 the operation is safely retried once. If retryreads is false in the
56 URI (see mongoc_uri_t) the retry behavior does not apply.
57
59 This function returns a newly allocated mongoc_cursor_t that should be
60 freed with mongoc_cursor_destroy() when no longer in use. The returned
61 mongoc_cursor_t is never NULL, even on error. The user must call mon‐
62 goc_cursor_next() on the returned mongoc_cursor_t to execute the ini‐
63 tial command.
64 Cursor errors can be checked with mongoc_cursor_error_document. It al‐
66 ways fills out the bson_error_t if an error occurred, and optionally
67 includes a server reply document if the error occurred server-side.
68 WARNING:
70 Failure to handle the result of this function is a programming er‐
71 ror.
72
74 Print All Documents in a Collection
75 #include <bson/bson.h>
77 #include <mongoc/mongoc.h>
78 #include <stdio.h>
79 static void
81 print_all_documents (mongoc_collection_t *collection)
82 {
83 mongoc_cursor_t *cursor;
84 bson_error_t error;
85 const bson_t *doc;
86 char *str;
87 bson_t *query;
88 query = BCON_NEW ("$query",
90 "{",
91 "foo",
92 BCON_INT32 (1),
93 "}",
94 "$orderby",
95 "{",
96 "bar",
97 BCON_INT32 (-1),
98 "}");
99 cursor = mongoc_collection_find (
100 collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL);
101 while (mongoc_cursor_next (cursor, &doc)) {
103 str = bson_as_canonical_extended_json (doc, NULL);
104 printf ("%s\n", str);
105 bson_free (str);
106 }
107 if (mongoc_cursor_error (cursor, &error)) {
109 fprintf (stderr, "An error occurred: %s\n", error.message);
110 }
111 mongoc_cursor_destroy (cursor);
113 bson_destroy (query);
114 }
115
117 Queries have historically been sent as OP_QUERY wire protocol messages,
118 but beginning in MongoDB 3.2 queries use the "find" command instead.
119 The driver automatically converts queries to the new "find" command
121 syntax if needed, so this change is typically invisible to C Driver
122 users. However, an application written exclusively for MongoDB 3.2 and
123 later can choose to use the new syntax directly instead of relying on
124 the driver to convert from the old syntax:
125 /* MongoDB 3.2+ "find" command syntax */
127 query = BCON_NEW ("filter",
128 "{",
129 "foo",
130 BCON_INT32 (1),
131 "}",
132 "sort",
133 "{",
134 "bar",
135 BCON_INT32 (-1),
136 "}");
137 cursor = mongoc_collection_find (
138 collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL);
139 The "find" command takes different options from the traditional
141 OP_QUERY message.
142 ┌────────────────────┬────────────────┬───────────────┐
144 │Query │ $query │ filter │
145 ├────────────────────┼────────────────┼───────────────┤
146 │Sort │ $orderby │ sort │
147 ├────────────────────┼────────────────┼───────────────┤
148 │Show record loca‐ │ $showDiskLoc │ showRecordId │
149 │tion │ │ │
150 ├────────────────────┼────────────────┼───────────────┤
151 │Other $-options │ $<option name> │ <option name> │
152 └────────────────────┴────────────────┴───────────────┘
153 Most applications should use the OP_QUERY syntax, with "$query", "$or‐
155 derby", and so on, and rely on the driver to convert to the new syntax
156 if needed.
157 SEE ALSO:
159 The "find" command in the MongoDB Manual.
160
163 With MongoDB before 3.2, a query with option $explain: true returns in‐
164 formation about the query plan, instead of the query results. Beginning
165 in MongoDB 3.2, there is a separate "explain" command. The driver will
166 not convert "$explain" queries to "explain" commands, you must call the
167 "explain" command explicitly:
168 /* MongoDB 3.2+, "explain" command syntax */
170 command = BCON_NEW ("explain",
171 "{",
172 "find",
173 BCON_UTF8 ("collection_name"),
174 "filter",
175 "{",
176 "foo",
177 BCON_INT32 (1),
178 "}",
179 "}");
180 mongoc_collection_command_simple (collection, command, NULL, &reply, &error);
181 SEE ALSO:
183 The "explain" command in the MongoDB Manual.
184
187 MongoDB, Inc
188
190 2017-present, MongoDB, Inc
1911.21.1 Mar 02, 2022 MONGOC_COLLECTION_FIND(3)