# Class: Cursor

## Cursor

Class representing a query cursor. Note: The filter, limit, skip, project, group, unwind and sort, methods each add an additional stage to the cursor pipeline and thus do not override any previous invocations.

#### new Cursor()

cursor.js, line 30
  Note: Do not instantiate directly.

### Methods

#### filter(expr){Cursor}

cursor.js, line 150
  Filter documents.

  Name | Type | Description
  --- | --- | ---
  `expr` | object | The query document to filter by.

  ##### Returns:

  Type | Description
  --- | ---
  Cursor |

  ##### Example

      col.find().filter({ x: 4 });

#### forEach(fn, cb){Promise}

cursor.js, line 69
  Iterate over each document and apply a function.

  Name | Type | Description
  --- | --- | ---
  `fn` | function | optional The function to apply to each document.
  `cb` | function | optional The result callback.

  ##### Returns:

  Type | Description
  --- | ---
  Promise |

  ##### Example

      col.find().forEach((doc) => {
          console.log('doc:', doc);
      }, (error) => {
          if (error) { throw error; }
      });

#### group(spec){Cursor}

cursor.js, line 194
  Group documents by an _id and optionally add computed fields.

  Name | Type | Description
  --- | --- | ---
  `spec` | object | Specification for grouping documents.

  ##### Returns:

  Type | Description
  --- | ---
  Cursor |

  ##### Example

      col.find().group({
          _id: '$author',
          books: { $push: '$book' },
          count: { $sum: 1 }
      });

#### limit(num){Cursor}

cursor.js, line 160
  Limit the number of documents that can be iterated.

  Name | Type | Description
  --- | --- | ---
  `num` | number | The limit.

  ##### Returns:

  Type | Description
  --- | ---
  Cursor |

  ##### Example

      col.find().limit(10);

#### project(spec){Cursor}

cursor.js, line 180
  Add new fields, and include or exclude pre-existing fields.

  Name | Type | Description
  --- | --- | ---
  `spec` | object | Specification for projection.

  ##### Returns:

  Type | Description
  --- | ---
  Cursor |

  ##### Example

      col.find().project({ _id: 0, x: 1, n: { $add: ['$k', 4] } });

#### skip(num){Cursor}

cursor.js, line 170
  Skip over a specified number of documents.

  Name | Type | Description
  --- | --- | ---
  `num` | number | The number of documents to skip.

  ##### Returns:

  Type | Description
  --- | ---
  Cursor |

  ##### Example

      col.find().skip(4);

#### sort(spec){Cursor}

cursor.js, line 228
  Sort documents. Note: An index will not be used for sorting unless the query predicate references one of the fields to sort by or Cursor#hint is used. This is so as not to exclude documents that do not contain the indexed field, in accordance with the functionality of MongoDB.

  Name | Type | Description
  --- | --- | ---
  `spec` | object | Specification for sorting.

  ##### Returns:

  Type | Description
  --- | ---
  Cursor |

  ##### Examples

      // No indexes will be used for sorting.
      col.find().sort({ x: 1 });

      // If x is indexed, it will be used for sorting.
      col.find({ x: { $gt: 4 } }).sort({ x: 1 });

      // If x is indexed, it will be used for sorting.
      col.find().sort({ x: 1 }).hint('x');

#### toArray(cb){Promise}

cursor.js, line 104
  Collect all documents as an array.

  Name | Type | Description
  --- | --- | ---
  `cb` | function | optional The result callback.

  ##### Returns:

  Type | Description
  --- | ---
  Promise |

  ##### Example

      col.find().toArray((error, docs) => {
          if (error) { throw error; }

          for (let doc of docs) {
              console.log('doc:', doc);
          }
      });

#### unwind(path){Cursor}

cursor.js, line 204
  Deconstruct an iterable and output a document for each element.

  Name | Type | Description
  --- | --- | ---
  `path` | string | A path to an iterable to unwind.

  ##### Returns:

  Type | Description
  --- | ---
  Cursor |

  ##### Example

      col.find().unwind('$elements');

### Events

#### data

cursor.js, line 13
  Cursor data event.

  ##### Type:

  - object

#### end

cursor.js, line 19
  Cursor end event.