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