Skip to content

Commit

Permalink
CDRIVER-1522 update find docs
Browse files Browse the repository at this point in the history 
Two changes in particular. First, $-modifiers once again have the "$"
stripped for "find" commands, and added for OP_QUERY messages. I'd
removed this behavior a few commits ago and restored it in 63a9d42e.

Second, "filter" is no longer treated specially by the old "find()", so
you don't have to do special things to query on a "filter" field.
  • Loading branch information
@ajdavis
ajdavis committed Sep 13, 2016
1 parent 0c12cc6 commit 27cad5c
Show file tree
Hide file tree
Showing 3 changed files with 19 additions and 34 deletions.
3 changes: 3 additions & 0 deletions NEWS
View file
Expand Up @@ -17,6 +17,9 @@ New features and bug fixes:
* connectTimeoutMS timer now begins after DNS resolution, and resets
for each interface attempted (e.g., if the driver first tries IPv6,
then IPv4).
* mongoc_collection_find no longer treats the "filter" key specially in
queries - querying for a document with a key named "filter" is the same
now as any other key.

Thanks to everyone who contributed to the development of this release.

Expand Down
37 changes: 7 additions & 30 deletions doc/mongoc_collection_find.page
View file
Expand Up @@ -13,6 +13,10 @@
</info>
<title>mongoc_collection_find()</title>

<section id="deprecation">
<p>For a more convenient API, see <code xref="mongoc_collection_find_with_opts">mongoc_collection_find_with_opts</code>.</p>
</section>

<section id="synopsis">
<title>Synopsis</title>
<synopsis><code mime="text/x-csrc"><![CDATA[mongoc_cursor_t *
Expand Down Expand Up @@ -46,13 +50,12 @@ mongoc_collection_find (mongoc_collection_t *collection,
<section id="description">
<title>Description</title>
<p>This function shall execute a query on the underlying <code>collection</code>.</p>
<p>If no options are necessary, <code>query</code> can simply contain a query such as <code>{a:1}</code>. If you would like to specify options such as a sort order, the query must be placed inside of <code>{"$query": {}}</code> as specified by the server documentation. See the example below for how to properly specify additional options to <code>query</code>.</p>
<p>If no options are necessary, <code>query</code> can simply contain a query such as <code>{a:1}</code>. If you would like to specify options such as a sort order, the query must be placed inside of <code>{"$query": {}}</code>. See the example below for how to properly specify additional options to <code>query</code>.</p>
</section>

<section id="return">
<title>Returns</title>
<p>A newly allocated <code xref="mongoc_cursor_t">mongoc_cursor_t</code> that should be freed with <code xref="mongoc_cursor_destroy">mongoc_cursor_destroy()</code> when no longer in use. If invalid parameters are supplied, <code>NULL</code> may be returned.</p>
<note style="warning"><p>Failure to handle the result of this function is a programming error.</p></note>
<p>A newly allocated <code xref="mongoc_cursor_t">mongoc_cursor_t</code> that should be freed with <code xref="mongoc_cursor_destroy">mongoc_cursor_destroy()</code> when no longer in use.</p>
</section>

<section id="example">
Expand Down Expand Up @@ -121,38 +124,12 @@ cursor = mongoc_collection_find (collection, MONGOC_QUERY_NONE, 0, 0, 0, query,
<td><p>Other $-options</p></td> <td><p><code>$&lt;option name&gt;</code></p></td> <td><p><code>&lt;option name&gt;</code></p></td>
</tr>
</table>
<p>Most applications should use the OP_QUERY syntax, with "$query", "$orderby", and so on, and rely on the driver to convert to the new syntax if needed. There are two caveats: querying documents by a key named "filter", and using new "find" command options that OP_QUERY does not support.</p>
<p>Most applications should use the OP_QUERY syntax, with "$query", "$orderby", and so on, and rely on the driver to convert to the new syntax if needed.</p>

<section id="seealso">
<title>See Also</title>
<p><link href="https://docs.mongodb.org/master/reference/command/find/">The "find" command</link> in the MongoDB Manual.</p>
</section>

<section id="key-named-filter">
<title>Finding a document by a key named "filter"</title>
<p>To find a document like <code mime="x-json">{ "_id": 1, "filter": "value" }</code>, this query works in MongoDB before 3.2:</p>
<code mime="text/x-csrc"><![CDATA[/* Fails with MongoDB 3.2+ */
query = BCON_NEW ("filter", BCON_UTF8 ("value"));
cursor = mongoc_collection_find (collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL);
]]></code>
<p>Beginning in MongoDB 3.2, the "filter" option has special meaning, and it is no longer assumed to be a field in a document you are querying for. To execute this query on any MongoDB version, wrap it in "$query":</p>
<code mime="text/x-csrc"><![CDATA[/* Works in all MongoDB versions */
query = BCON_NEW ("$query", "{", "filter", BCON_UTF8 ("value"), "}");
cursor = mongoc_collection_find (collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL);
]]></code>
<p>This code works for any MongoDB version. The driver sends it as-is to a MongoDB server older than 3.2, and before sending to MongoDB 3.2 or later converts it to the following:</p>
<code mime="text/x-json">{ "filter": { "filter": "value" } }</code>
</section>
<section id="find-command-options">
<title>Options specific to the "find" command</title>
<p>The "find" command has new options like "singleBatch" not supported by OP_QUERY. Applications should use the new "find" syntax directly to take advantage of them:</p>
<code mime="text/x-csrc"><![CDATA[/* MongoDB 3.2+ "find" command syntax */
query = BCON_NEW ("filter", "{", "foo", BCON_INT32 (1), "}",
"sort", "{", "bar", BCON_INT32 (-1), "}",
"singleBatch", BCON_BOOL (true));
cursor = mongoc_collection_find (collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL);
]]></code>
</section>
</section>

<section id="explain-command">
Expand Down
13 changes: 9 additions & 4 deletions doc/mongoc_collection_find_with_opts.page
View file
Expand Up @@ -37,12 +37,12 @@ mongoc_collection_find_with_opts (mongoc_collection_t *collection,

<section id="description">
<title>Description</title>
<p>This function shall execute a query on the underlying <code>collection</code>.</p>
<p>Query on <code>collection</code>, passing arbitrary query options to the server in <code>opts</code>.</p>
</section>

<section id="return">
<title>Returns</title>
<p>A newly allocated <code xref="mongoc_cursor_t">mongoc_cursor_t</code> that should be freed with <code xref="mongoc_cursor_destroy">mongoc_cursor_destroy()</code> when no longer in use. If invalid parameters are supplied, <code>NULL</code> may be returned.</p>
<p>A newly allocated <code xref="mongoc_cursor_t">mongoc_cursor_t</code> that must be freed with <code xref="mongoc_cursor_destroy">mongoc_cursor_destroy()</code>.</p>
</section>

<section id="examples">
Expand All @@ -62,7 +62,7 @@ print_ten_documents (mongoc_collection_t *collection)
const bson_t *doc;
char *str;
/* filter by "foo": 1, order by "bar" */
/* filter by "foo": 1, order by "bar" descending */
filter = BCON_NEW ("foo", BCON_INT32 (1));
opts = BCON_NEW ("limit", BCON_INT64 (10),
"sort", "{", "bar", BCON_INT32 (-1), "}");
Expand All @@ -81,10 +81,12 @@ print_ten_documents (mongoc_collection_t *collection)
mongoc_cursor_destroy (cursor);
bson_destroy (filter);
bson_destroy (opts);
}]]></code>
</listing>
<listing>
<title>Other Options</title>
<p>More examples of modifying the query with <code>opts</code>:</p>
<code mime="text/x-csrc"><![CDATA[bson_t *filter;
bson_t *opts;
mongoc_read_prefs_t *read_prefs;
Expand Down Expand Up @@ -143,7 +145,10 @@ cursor = mongoc_collection_find_with_opts (collection, filter, read_prefs, opts)

<section id="seealso">
<title>See Also</title>
<p><link href="https://docs.mongodb.org/master/reference/command/find/">The "find" command</link> in the MongoDB Manual. All options listed there are supported by the C Driver.</p>
<p>
<link href="https://docs.mongodb.org/master/reference/command/find/">The "find" command</link> in the MongoDB Manual. All options listed there are supported by the C Driver.
For MongoDB servers before 3.2, or for exhaust queries, the driver transparently converts the query to a legacy OP_QUERY message.
</p>
</section>

<section id="explain-command">
Expand Down

0 comments on commit 27cad5c

Please sign in to comment.