findOne.txt

.. _csharp-find-one:

===============
Find a Document
===============

.. facet::
   :name: genre
   :values: reference

.. meta::
   :keywords: code example, .NET, operation
   :description: Retrieve a document from a collection using the `Find()` method in C# with examples for both asynchronous and synchronous operations.

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

You can retrieve a document by using the ``Find()`` method on a collection object.

Example
-------

Find a Document by Using Builders
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following example uses ``Builders`` to find a document in the ``restaurants``
collection that has a ``name`` field with a value of "Bagels N Buns".

Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the 
corresponding code.

.. tabs::

   .. tab:: Synchronous
      :tabid: builders-sync

      .. literalinclude:: ../includes/code-examples/find-one/FindOne.cs
         :start-after: start-find-builders
         :end-before: end-find-builders
         :language:  csharp
         :copyable:
         :dedent:

      For a fully runnable example of using the ``Find()`` method
      to synchronously find one document, see the `Synchronous Find One Example
      <{+example+}/find-one/FindOne.cs>`__.

   .. tab:: Asynchronous
      :tabid: builders-async

      .. literalinclude:: ../includes/code-examples/find-one/FindOneAsync.cs
         :start-after: start-find-builders
         :end-before: end-find-builders
         :language:  csharp
         :copyable:
         :dedent:

      For a fully runnable example of using the ``Find()`` method
      to asynchronously find one document, see the `Asynchronous Find One Example <{+example+}/find-one/FindOneAsync.cs>`__.

Find a Document by Using LINQ
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following example uses LINQ to find a document in the ``restaurants``
collection that has a ``name`` field with a value of "Bagels N Buns".

Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the 
corresponding code.

.. tabs::

   .. tab:: Synchronous
      :tabid: linq-sync

      .. literalinclude:: ../includes/code-examples/find-one/FindOne.cs
         :start-after: start-find-linq
         :end-before: end-find-linq
         :language:  csharp
         :copyable:
         :dedent:

      For a fully runnable example of using the ``Find()`` method
      to synchronously find one document, see the `Synchronous Find One Example
      <{+example+}/find-one/FindOne.cs>`__.
      
   .. tab:: Asynchronous
      :tabid: linq-async

      .. literalinclude:: ../includes/code-examples/find-one/FindOneAsync.cs
         :start-after: start-find-linq
         :end-before: end-find-linq
         :language:  csharp
         :copyable:
         :dedent:

      For a fully runnable example of using the ``Find()`` method
      to asynchronously find one document, see the `Asynchronous Find One Example <{+example+}/find-one/FindOneAsync.cs>`__.

Expected Result
~~~~~~~~~~~~~~~

Running any of the preceding full examples prints results similar to the following:

.. code-block:: none

   { 
      "_id" : ObjectId("5eb3d668b31de5d588f42950"), 
      "name" : "Bagels N Buns", 
      "restaurant_id" : "40363427", 
      "cuisine" : "Delicatessen", 
      "address" : {...}, 
      "borough" : "Staten Island", 
      "grades" : [...] 
   }

Additional Information
----------------------

To learn more about retrieving documents, see the :ref:`csharp-retrieve` guide.

To learn more about using builders, see :ref:`csharp-builders`.

To learn how to find a document using LINQ, see :ref:`csharp-linq`.

API Documentation
-----------------

- `Find() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollectionExtensions.Find.html>`__
- `FirstOrDefault() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IFindFluentExtensions.FirstOrDefault.html>`__
- `FirstOrDefaultAsync() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Linq.MongoQueryable.FirstOrDefaultAsync.html>`__