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 A newly allocated mongoc_cursor_t that should be freed with mongoc_cur‐
60 sor_destroy() when no longer in use.
61
63 Print All Documents in a Collection.INDENT 0.0
64 #include <bson/bson.h>
66 #include <mongoc/mongoc.h>
67 #include <stdio.h>
68 static void
70 print_all_documents (mongoc_collection_t *collection)
71 {
72 mongoc_cursor_t *cursor;
73 bson_error_t error;
74 const bson_t *doc;
75 char *str;
76 bson_t *query;
77 query = BCON_NEW ("$query",
79 "{",
80 "foo",
81 BCON_INT32 (1),
82 "}",
83 "$orderby",
84 "{",
85 "bar",
86 BCON_INT32 (-1),
87 "}");
88 cursor = mongoc_collection_find (
89 collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL);
90 while (mongoc_cursor_next (cursor, &doc)) {
92 str = bson_as_canonical_extended_json (doc, NULL);
93 printf ("%s\n", str);
94 bson_free (str);
95 }
96 if (mongoc_cursor_error (cursor, &error)) {
98 fprintf (stderr, "An error occurred: %s\n", error.message);
99 }
100 mongoc_cursor_destroy (cursor);
102 bson_destroy (query);
103 }
104
106 Queries have historically been sent as OP_QUERY wire protocol messages,
107 but beginning in MongoDB 3.2 queries use the "find" command instead.
108 The driver automatically converts queries to the new "find" command
110 syntax if needed, so this change is typically invisible to C Driver
111 users. However, an application written exclusively for MongoDB 3.2 and
112 later can choose to use the new syntax directly instead of relying on
113 the driver to convert from the old syntax:
114 /* MongoDB 3.2+ "find" command syntax */
116 query = BCON_NEW ("filter",
117 "{",
118 "foo",
119 BCON_INT32 (1),
120 "}",
121 "sort",
122 "{",
123 "bar",
124 BCON_INT32 (-1),
125 "}");
126 cursor = mongoc_collection_find (
127 collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL);
128 The "find" command takes different options from the traditional
130 OP_QUERY message.
131 ┌────────────────────┬────────────────┬───────────────┐
134 │Query │ $query │ filter │
135 ├────────────────────┼────────────────┼───────────────┤
136 │Sort │ $orderby │ sort │
137 ├────────────────────┼────────────────┼───────────────┤
138 │Show record loca‐ │ $showDiskLoc │ showRecordId │
139 │tion │ │ │
140 ├────────────────────┼────────────────┼───────────────┤
141 │Other $-options │ $<option name> │ <option name> │
142 └────────────────────┴────────────────┴───────────────┘
143 Most applications should use the OP_QUERY syntax, with "$query",
145 "$orderby", and so on, and rely on the driver to convert to the new
146 syntax if needed.
147
149 The "find" command in the MongoDB Manual.
150
152 With MongoDB before 3.2, a query with option $explain: true returns
153 information about the query plan, instead of the query results. Begin‐
154 ning in MongoDB 3.2, there is a separate "explain" command. The driver
155 will not convert "$explain" queries to "explain" commands, you must
156 call the "explain" command explicitly:
157 /* MongoDB 3.2+, "explain" command syntax */
159 command = BCON_NEW ("explain",
160 "{",
161 "find",
162 BCON_UTF8 ("collection_name"),
163 "filter",
164 "{",
165 "foo",
166 BCON_INT32 (1),
167 "}",
168 "}");
169 mongoc_collection_command_simple (collection, command, NULL, &reply, &error);
170
172 The "explain" command in the MongoDB Manual.
173
175 MongoDB, Inc
176
178 2017-present, MongoDB, Inc
1791.16.2 Feb 25, 2020 MONGOC_COLLECTION_FIND(3)