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