Add query examples and create BSON tutorial page

docs/tutorial/crud.md

@@ -11,21 +11,12 @@ the [MongoDB Manual][crud].
 [crud-spec]: https://github.com/mongodb/specifications/blob/master/source/crud/crud.rst
 [crud]: https://docs.mongodb.org/manual/crud/
 
-## Querying
-
-### Finding One Document
+## Finding One Document
 
 The [findOne()][findone] method returns the first matched document, or null if
-no document was matched. By default, the library returns BSON documents and
-arrays as MongoDB\Model\BSONDocument and MongoDB\Model\BSONArray objects,
-respectively. Both of those classes extend PHP's [ArrayObject][arrayobject]
-class and implement the driver's [MongoDB\BSON\Serializable][serializable] and
-[MongoDB\BSON\Unserializable][unserializable] interfaces.
+no document was matched.
 
 [findone]: ../classes/collection.md#findone
-[arrayobject]: http://php.net/arrayobject
-[serializable]: http://php.net/mongodb-bson-serializable
-[unserializable]: http://php.net/mongodb-bson-unserializable
 
 ```
 <?php
@@ -65,21 +56,55 @@ object(MongoDB\Model\BSONDocument)#13 (1) {
 }
 ```
 
-Most methods that read data from MongoDB support a "typeMap" option, which
-allows control over how BSON is converted to PHP. If desired, this option can be
-used to return everything as a PHP array, as was done in the legacy
-[mongo extension][ext-mongo]:
+## Finding Many Documents
+
+The [find()][find] method returns a [MongoDB\Driver\Cursor][cursor] object,
+which may be iterated upon to access all matched documents. The following
+example queries for all zip codes in a given city:
+
+[find]: ../classes/collection.md#find
+[cursor]: http://php.net/mongodb-driver-cursor
+
+```
+<?php
+
+$collection = (new MongoDB\Client)->demo->zips;
+
+$cursor = $collection->find(['city' => 'JERSEY CITY', 'state' => 'NJ']);
+
+foreach ($cursor as $document) {
+    echo $document['_id'], "\n";
+}
+```
+
+The above example would output something similar to:
+
+```
+07302
+07304
+07305
+07306
+07307
+07310
+```
+
+## Query Projection
+
+Queries may include a [projection][projection] to include or exclude specific
+fields in the returned documents. The following example selects only the
+population field for the zip code:
+
+[projection]: https://docs.mongodb.org/manual/tutorial/project-fields-from-query-results/
 
-[ext-mongo]: http://php.net/mongo
 
 ```
 <?php
 
 $collection = (new MongoDB\Client)->demo->zips;
 
 $document = $collection->findOne(
-    ['_id' => '94301'],
-    ['typeMap' => ['root' => 'array', 'document' => 'array', 'array' => 'array']]
+    ['_id' => '10011'],
+    ['projection' => ['pop => 1']]
 );
 
 var_dump($document);
@@ -88,39 +113,37 @@ var_dump($document);
 The above example would output something similar to:
 
 ```
-array(5) {
-  ["_id"]=>
-  string(5) "94301"
-  ["city"]=>
-  string(9) "PALO ALTO"
-  ["loc"]=>
+object(MongoDB\Model\BSONDocument)#12 (1) {
+  ["storage":"ArrayObject":private]=>
   array(2) {
-    [0]=>
-    float(-122.149685)
-    [1]=>
-    float(37.444324)
+    ["_id"]=>
+    string(5) "10011"
+    ["pop"]=>
+    int(46560)
   }
-  ["pop"]=>
-  int(15965)
-  ["state"]=>
-  string(2) "CA"
 }
 ```
 
-### Finding Many Documents
+**Note:** the "_id" field is included by default unless explicitly excluded.
 
-The [find()][find] method returns a [MongoDB\Driver\Cursor][cursor] object,
-which may be iterated upon to access all matched documents.
+## Limit, Sort, and Skip Options
 
-[find]: ../classes/collection.md#find
-[cursor]: http://php.net/mongodb-driver-cursor
+In addition to criteria, queries may take options to limit, sort, and skip
+returned documents. The following example queries for the five most populous
+zip codes in the United States:
 
 ```
 <?php
 
 $collection = (new MongoDB\Client)->demo->zips;
 
-$cursor = $collection->find(['city' => 'JERSEY CITY', 'state' => 'NJ']);
+$cursor = $collection->find(
+    [],
+    [
+        'limit' => 5,
+        'sort' => ['pop' => -1],
+    ]
+);
 
 foreach ($cursor as $document) {
     echo $document['_id'], "\n";
@@ -130,10 +153,9 @@ foreach ($cursor as $document) {
 The above example would output something similar to:
 
 ```
-07302
-07304
-07305
-07306
-07307
-07310
+60623: CHICAGO, IL
+11226: BROOKLYN, NY
+10021: NEW YORK, NY
+10025: NEW YORK, NY
+90201: BELL GARDENS, CA
 ```

mkdocs.yml

@@ -9,6 +9,7 @@ pages:
     - 'Getting Started': 'getting-started.md'
     - 'Upgrade Guide': 'upgrade-guide.md'
     - Tutorial:
+        - 'BSON Conversion': 'tutorial/bson.md'
         - 'CRUD Operations': 'tutorial/crud.md'
         - 'Database Commands': 'tutorial/commands.md'
         - 'Indexes': 'tutorial/indexes.md'