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

  <info>
    <link type="guide" xref="index#getting-started" />
  </info>

  <title>Finding a Document</title>

  <p>The following guide will step you through the process of connecting to MongoDB and submitting your first query.</p>

  <include href="basic-prequisites.xml" xmlns="http://www.w3.org/2001/XInclude" />

  <section id="connecting-basics">
    <title>The Basics</title>

    <p>
      The following code example creates a new <code>mongoc_client_t</code> that we will use to communicate with MongoDB.
      The <link href="http://docs.mongodb.org/manual/reference/connection-string/">Connection String URI</link> component is quite comprehensive.
    </p>

    <p>
      Using our <code>mongoc_client_t</code>, we get a handle to a <code>mongoc_collection_t</code> which represents the remote collection.
      <code>query</code> is initialized to a new BSON document that contains no elements, therefore matching every document in the MongoDB collection.
    </p>

    <p>
      Using the returned cursor, we convert each resulting document to a <link href="http://docs.mongodb.org/manual/reference/mongodb-extended-json/">MongoDB Extended JSON</link> string and print it to <code>stdout</code>.
    </p>

    <p>
      Lastly, we release all of our heap allocated structures.
    </p>

    <listing>
      <title><file>example1.c</file></title>
      <desc>Print all documents in a collection.</desc>
      <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, "test", "test");
    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);

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

    <p>Let's use <code>GCC</code> and <code>pkg-config</code> to compile <file>example1.c</file>.</p>
    <screen>gcc -o example1 example1.c $(pkg-config --cflags --libs libmongoc-1.0)</screen>

    <note style="warning">
      <p>
        When using the MongoDB C Driver, you must call <link xref="mongoc_init">mongoc_init()</link> at the beginning of your application.
        This allows the driver to initialize it's required subsystems.
        Failure to do so will result in a runtime crash.
      </p>
    </note>

    <p>Now let's run it!</p>

    <screen>./example1</screen>

    <p>Oops, nothing to print! Let's insert a document into our collection using the MongoDB shell.</p>

    <screen>[christian@starpulse ~]$ mongo
MongoDB shell version: 2.4.10
connecting to: test
> use test
switched to db test
> db.test.insert({'hello': 'world'})
> 
bye</screen>

    <p>And now let's run it again!</p>

    <screen>./example1
{ "_id" : { "$oid" : "534cde1a4f05ea4055d4cd4c" }, "hello" : "world" }</screen>

    <p>Congratulations on your first query with the MongoDB C Driver!</p>

  </section>

  <section>
    <title>Specifying a Query</title>
    <p>
      The above example is useful, but wouldn't it be more useful if we could find a specific document?
      Let's modify the above program to find a specific document matching <code mime="text/x-js">{"hello": "world"}</code>.
    </p>

    <listing>
      <title><file>example2.c</file></title>
      <desc>Finding a specific document.</desc>
      <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, "test", "test");
    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);

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

    <screen>gcc -o example2 example2.c $(pkg-config --cflags --libs libmongoc-1.0)
./example2
{ "_id" : { "$oid" : "534cde1a4f05ea4055d4cd4c" }, "hello" : "world" }</screen>

    <p>
      Our document still matches the query, so it is still printed to <code>stdout</code>.
      Try changing the element values to see how the results change.
    </p>

  </section>

</page>
