<page id="finding-document"
      type="topic"
      xmlns="http://projectmallard.org/1.0/">

  <info>
    <link type="guide" xref="tutorial#crud-operations"/>
  </info>

  <title>Finding a Document</title>
  <p>To query a MongoDB collection with the C driver, use the function <link xref="mongoc_collection_find">mongoc_collection_find()</link>. This returns a <link xref="mongoc_cursor_t">cursor</link> to the matching documents. The following examples iterate through the result cursors and print the matches to <code>stdout</code> as JSON strings.</p>
  <p>Note that <code>mongoc_collection_find</code> uses a document as a query specifier; for example,</p>

  <screen><code mime="x-js">{ "color" : "red" }</code></screen>

  <p>will match any document with a field named "color" with value "red". An empty document <code>{}</code> can be used to match all documents.</p>
  <p>This first example uses an empty query specifier to find all documents in the database "mydb" and collection "mycoll".</p>

  <listing>
    <title><file>find.c</file></title>
    <synopsis><code mime="text/x-csrc"><![CDATA[#include <bson.h>
#include <mongoc.h>
#include <stdio.h>

int
main (int   argc,
     char *argv[])
{
  mongoc_client_t *client;
  mongoc_collection_t *collection;
  mongoc_cursor_t *cursor;
  const bson_t *doc;
  bson_t *query;
  char *str;

  mongoc_init ();

  client = mongoc_client_new ("mongodb://localhost:27017/");
  collection = mongoc_client_get_collection (client, "mydb", "mycoll");
  query = bson_new ();
  cursor = mongoc_collection_find (collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL);

  while (mongoc_cursor_next (cursor, &doc)) {
     str = bson_as_json (doc, NULL);
     printf ("%s\n", str);
     bson_free (str);
  }

  bson_destroy (query);
  mongoc_cursor_destroy (cursor);
  mongoc_collection_destroy (collection);
  mongoc_client_destroy (client);
  mongoc_cleanup ();

  return 0;
}
]]></code></synopsis>
      </listing>

      <p>Compile the code and run it: </p>
      <screen><output style="prompt">$ gcc -o find find.c $(pkg-config --cflags --libs libmongoc-1.0)
$ ./find
{ "_id" : { "$oid" : "55ef43766cb5f36a3bae6ee4" }, "hello" : "world" }</output></screen>

      <p>On Windows:</p>
      <screen><output style="prompt">C:\> cl.exe /IC:\mongo-c-driver\include\libbson-1.0 /IC:\mongo-c-driver\include\libmongoc-1.0 find.c
C:\> find
{ "_id" : { "$oid" : "55ef43766cb5f36a3bae6ee4" }, "hello" : "world" }</output></screen>

      <p>To look for a specific document, add a specifier to <code>query</code>. This example adds a call to <code>BSON_APPEND_UTF8()</code> to look for all documents matching <code mime="text/x-js">{"hello" : "world"}</code>.</p>

      <listing>
        <title><file>find-specific.c</file></title>
        <synopsis><code mime="text/x-csrc"><![CDATA[#include <bson.h>
  #include <mongoc.h>
  #include <stdio.h>

  int
  main (int   argc,
        char *argv[])
  {
      mongoc_client_t *client;
      mongoc_collection_t *collection;
      mongoc_cursor_t *cursor;
      const bson_t *doc;
      bson_t *query;
      char *str;

      mongoc_init ();

      client = mongoc_client_new ("mongodb://localhost:27017/");
      collection = mongoc_client_get_collection (client, "mydb", "mycoll");
      query = bson_new ();
      BSON_APPEND_UTF8 (query, "hello", "world");

      cursor = mongoc_collection_find (collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL);

      while (mongoc_cursor_next (cursor, &doc)) {
          str = bson_as_json (doc, NULL);
          printf ("%s\n", str);
          bson_free (str);
      }

      bson_destroy (query);
      mongoc_cursor_destroy (cursor);
      mongoc_collection_destroy (collection);
      mongoc_client_destroy (client);
      mongoc_cleanup ();

      return 0;
  }
  ]]></code></synopsis>
  </listing>

  <screen><output style="prompt">$ gcc -o find-specific find-specific.c $(pkg-config --cflags --libs libmongoc-1.0)
$ ./find-specific
{ "_id" : { "$oid" : "55ef43766cb5f36a3bae6ee4" }, "hello" : "world" }</output></screen>

  <screen><output style="prompt">C:\> cl.exe /IC:\mongo-c-driver\include\libbson-1.0 /IC:\mongo-c-driver\include\libmongoc-1.0 find-specific.c
C:\> find-specific
{ "_id" : { "$oid" : "55ef43766cb5f36a3bae6ee4" }, "hello" : "world" }</output></screen>
</page>
