cursor.returnKey.txt

==================
cursor.returnKey()
==================

.. default-domain:: mongodb

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

Definition
----------

.. method:: cursor.returnKey()


   .. include:: /includes/fact-mongosh-shell-method.rst

   .. tip::

      :expression:`$meta` supports the keyword ``"indexKey"`` to return index 
      key metadata if an index is used. The use of 
      :expression:`{ $meta: "indexKey" } <$meta>` is preferred over 
      :method:`cursor.returnKey()`.

   Modifies the cursor to return index keys rather than the documents.
   
   The :method:`cursor.returnKey()` has the following form:
   
   .. code-block:: javascript
   
      cursor.returnKey()

   :returns:

      The :term:`cursor` that :method:`~cursor.returnKey()` is attached to 
      with a modified result set. This allows for additional cursor modifiers 
      to be chained.

Compatibility
-------------

This method is available in deployments hosted in the following environments: 

.. include:: /includes/fact-environments-atlas-only.rst

.. include:: /includes/fact-environments-atlas-support-all.rst

.. include:: /includes/fact-environments-onprem-only.rst

Behavior
--------

If the query does not use an index to perform the read operation, the 
cursor returns empty documents.

Example
-------

The ``restaurants`` collection contains documents with the following schema:

.. code-block:: javascript

   {
      "_id" : ObjectId("564f3a35b385149fc7e3fab9"),
      "address" : {
         "building" : "2780",
         "coord" : [
            -73.98241999999999,
            40.579505
         ],
         "street" : "Stillwell Avenue",
         "zipcode" : "11224"
      },
      "borough" : "Brooklyn",
      "cuisine" : "American ",
      "grades" : [
         {
            "date" : ISODate("2014-06-10T00:00:00Z"),
            "grade" : "A",
            "score" : 5
         },
         {
            "date" : ISODate("2013-06-05T00:00:00Z"),
            "grade" : "A",
            "score" : 7
         }
      ],
      "name" : "Riviera Caterer",
      "restaurant_id" : "40356018"
   }
   
The collection has two indexes in addition to the default ``_id`` index:

.. code-block:: javascript

   {
      "v" : 1,
      "key" : {
         "_id" : 1
      },
      "name" : "_id_",
      "ns" : "guidebook.restaurant"
   },
   {
      "v" : 1,
      "key" : {
         "cuisine" : 1
      },
      "name" : "cuisine_1",
      "ns" : "guidebook.restaurant"
   },
   {
      "v" : 1,
      "key" : {
         "_fts" : "text",
         "_ftsx" : 1
      },
      "name" : "name_text",
      "ns" : "guidebook.restaurant",
      "weights" : {
         "name" : 1
      },
      "default_language" : "english",
      "language_override" : "language",
      "textIndexVersion" : 3
   }
      
The following code uses the :method:`cursor.returnKey()` method to return 
only the indexed fields used for executing the query:

.. code-block:: javascript

   var csr = db.restaurant.find( { "cuisine" : "Japanese" } )
   csr.returnKey()
   
This returns the following:

.. code-block:: javascript

   { "cuisine" : "Japanese" }
   { "cuisine" : "Japanese" }
   { "cuisine" : "Japanese" }
   { "cuisine" : "Japanese" }
   ...