find (database command)

string

The name of the collection or view to query.

document

Optional. The query predicate. If unspecified, then all documents in the collection will match the predicate.

document

Optional. The sort specification for the ordering of the results.

document

Optional. The projection specification to determine which fields to include in the returned documents.

find() operations on views do not support the following find command projection operators:

• $

• $elemMatch

• $slice

• $meta

string or document

Optional. Index specification. Specify either the index name as a string or the index key pattern. If specified, then the query system will only consider plans using the hinted index.

With the following exception, hint is required if the command includes the min and/or max fields; hint is not required with min and/or max if the filter is an equality condition on the _id field { _id: <value> }.

Positive integer

Optional. Number of documents to skip. Defaults to 0.

Non-negative integer

Optional. The maximum number of documents to return. If unspecified, then defaults to no limit. A limit of 0 is equivalent to setting no limit.

non-negative integer

Optional. The maximum number of documents that can be returned in each batch of a query result. By default, the find command has an initial batchSize of the lesser of 101 documents or 16 mebibytes (MiB) worth of documents. Subsequent batches have a maximum size of 16 MiB. This option can enforce a smaller limit than 16 MiB, but not a larger one. When set, the batchSize is the lesser of batchSize documents or 16 MiB worth of documents.

A batchSize of 0 means that the cursor is established, but no documents are returned in the first batch.

Unlike the previous wire protocol version, a batchSize of 1 for the find command does not close the cursor.

boolean

Optional. Determines whether to close the cursor after the first batch. Defaults to false.

any

Optional. A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations:

• mongod log messages, in the attr.command.cursor.comment field.

• Database profiler output, in the command.comment field.

• currentOp output, in the command.comment field.

A comment can be any valid BSON type (string, integer, object, array, etc).

Any comment set on a find command is inherited by any subsequent getMore commands run on the find cursor.

non-negative integer

Optional.

Specifies a time limit in milliseconds. If you do not specify a value for maxTimeMS, operations will not time out. A value of 0 explicitly specifies the default unbounded behavior.

MongoDB terminates operations that exceed their allotted time limit using the same mechanism as db.killOp(). MongoDB only terminates an operation at one of its designated interrupt points.

When specifying linearizable read concern, always use maxTimeMS in case a majority of data bearing members are unavailable. maxTimeMS ensures that the operation does not block indefinitely and instead returns an error if the read concern cannot be fulfilled.

document

Optional. Specifies the read concern.

The readConcern option has the following syntax: readConcern: { level: <value> }

Possible read concern levels are:

• "local". This is the default read concern level for read operations against the primary and secondaries.

• "available". Available for read operations against the primary and secondaries. "available" behaves the same as "local" against the primary and non-sharded secondaries. The query returns the instance's most recent data.

• "majority". Available for replica sets that use WiredTiger storage engine.

• "linearizable". Available for read operations on the primary only.

• "snapshot". Available for multi-document transactions and certain read operations outside of multi-document transactions.

For more formation on the read concern levels, see Read Concern Levels.

The getMore command uses the readConcern level specified in the originating find command.

document

Optional. The exclusive upper bound for a specific index. See cursor.max() for details.

To use the max field, the command must also use hint unless the specified filter is an equality condition on the _id field { _id: <value> }.

document

Optional. The inclusive lower bound for a specific index. See cursor.min() for details.

To use the min field, the command must also use hint unless the specified filter is an equality condition on the _id field { _id: <value> }.

boolean

Optional. If true, returns only the index keys in the resulting documents. Default value is false. If returnKey is true and the find command does not use an index, the returned documents will be empty.

boolean

Optional. Determines whether to return the record identifier for each document. If true, adds a field $recordId to the returned documents.

boolean

Optional. Returns a tailable cursor for a capped collections.

boolean

Optional. Use in conjunction with the tailable option to block a getMore command on the cursor temporarily at the end of data rather than returning no data. After a timeout period, find returns as normal.

boolean

Optional. Prevents the server from timing out non-session idle cursors after an inactivity period of 30 minutes. Ignored for cursors that are part of a session. For more information, refer to Session Idle Timeout.

boolean

Optional. For queries against a sharded collection, allows the command (or subsequent getMore commands) to return partial results, rather than an error, if one or more queried shards are unavailable.

If find (or subsequent getMore commands) returns partial results because the queried shard(s) aren't available, the find output includes a partialResultsReturned indicator field. If the queried shards are available for the initial find command, but one or more shards become unavailable for subsequent getMore commands, only the getMore commands that run while the shards aren't available include partialResultsReturned in their output.

document

Optional.

Specifies the collation to use for the operation.

Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.

The collation option has the following syntax:

collation: {
    locale: <string>,
    caseLevel: <boolean>,
    caseFirst: <string>,
    strength: <int>,
    numericOrdering: <boolean>,
    alternate: <string>,
    maxVariable: <string>,
    backwards: <boolean>
 }

When specifying collation, the locale field is mandatory; all other collation fields are optional. For descriptions of the fields, see Collation Document.

If the collation is unspecified but the collection has a default collation (see db.createCollection()), the operation uses the collation specified for the collection.

If no collation is specified for the collection or for the operations, MongoDB uses the simple binary comparison used in prior versions for string comparisons.

You cannot specify multiple collations for an operation. For example, you cannot specify different collations per field, or if performing a find with a sort, you cannot use one collation for the find and another for the sort.

boolean

Optional.

Use this option to override allowDiskUseByDefault for a specific query. You can use this option to either:

• Prohibit disk use on a system where disk use is allowed by default.

• Allow disk use on a system where disk use is prohibited by default.

Starting in MongoDB 6.0, if allowDiskUseByDefault is set to true and the server requires more than 100 megabytes of memory for a pipeline execution stage, MongoDB automatically writes temporary files to disk unless the query specifies { allowDiskUse: false }.

For details, see allowDiskUseByDefault.

allowDiskUse has no effect if MongoDB can satisfy the specified sort using an index, or if the in-memory sort requires less than 100 megabytes of memory.

For more complete documentation on allowDiskUse, see cursor.allowDiskUse().

For more information on memory restrictions for large in-memory sorts, see Sort and Index Use.

document

Optional.

Specifies a document with a list of variables. This allows you to improve command readability by separating the variables from the query text.

The document syntax is:

{
  <variable_name_1>: <expression_1>,
  ...,
  <variable_name_n>: <expression_n>
}

The variable is set to the value returned by the expression, and cannot be changed afterwards.

To access the value of a variable in the command, use the double dollar sign prefix ($$) together with your variable name in the form $$<variable_name>. For example: $$targetTotal.

To use a variable to filter results, you must access the variable within the $expr operator.

For a complete example using let and variables, see Use Variables in let.