- Stitch >
- MongoDB Atlas >
- Reference >
- MongoDB Actions
collection.findOne()¶
On this page
Definition¶
-
collection.
findOne
()¶
Return a single document from a collection or view. If multiple documents satisfy the query, this method returns the first document according to the query’s sort order or natural order.
Usage¶
Example¶
- Functions
- JavaScript SDK
- Android SDK
- iOS SDK
To call the collection.findOne()
action from a
Function, get a collection handle with
database.collection()
then call the handle’s
findOne()
method.
To call the collection.findOne()
action from a JavaScript
SDK, use the RemoteMongoCollection.findOne() method.
To call the collection.findOne()
action from the
Java/Android SDK, use the
RemoteMongoCollection.findOne()
method.
Parameters¶
- Functions
- JavaScript SDK
- Android SDK
- iOS SDK
The collection.findOne()
action has the following form:
Parameter | Description |
---|---|
Query Filter query: <document> |
Optional. A standard MongoDB query document that specifies which documents to find. You can use most query selectors except for evaluation, geospatial, or bitwise selectors. Specify an empty query filter ( |
Projection projection: <document> |
Optional. A document that specifies which fields MongoDB should return or withhold from a returned document. To return all fields in the document, omit this parameter or
specify an empty projection document ( To return specific fields and the document’s To withhold specific fields, specify the fields in the projection
document with a value of Note You may specify either fields to include or fields to withhold
but not both. For example, the following projection is
invalid because it simultaneously includes the The exception to this rule is the |
The findOne() method has the following form:
Parameter | Description |
---|---|
Query Filter query: <document> |
Optional. A standard MongoDB query document that specifies which documents to find. You can use most query selectors except for evaluation, geospatial, or bitwise selectors. Specify an empty query filter ( |
Query Options options: <document> |
“” A document that specifies configuration options for the
query. The |
Projection options.projection: <document> |
Optional. A document that specifies which fields MongoDB should return or withhold in the returned document. To return all fields in the document, omit this parameter or
specify an empty projection document ( To return specific fields and the document’s To withhold specific fields, specify the fields in the projection
document with a value of Note You may specify either fields to include or fields to
withhold but not both. For example, the following projection
is invalid because it simultaneously includes the
The exception to this rule is the |
Sort options.sort: <document> |
Optional. A document that specifies a Example The following sort document specifies that documents should be
sorted first by |
The findOne() method has the following form:
Parameter | Description |
---|---|
Query Filter filter: <document> |
Required. A standard MongoDB query document that specifies which document to find. You can use most query selectors except for evaluation, geospatial, or bitwise selectors. If multiple documents match the query, only the first document in sort order or natural order will be updated. |
Find Options options: <RemoteFindOptions> |
Optional: An instance of the RemoteFindOptions. class. |
Sort RemoteFindOneOptions.sort: <document> |
Optional. Specifies the query sort order. Sort documents
specify one or more fields to sort on where the value of each
field indicates whether MongoDB should sort it in ascending
( Example The following sort document specifies that documents should be
sorted first by |
Projection RemoteFindOneOptions.projection: <document> |
Optional. A document that specifies which fields MongoDB should return or withhold in the document returned by the query. To return all fields in the matching document, omit this
parameter or specify an empty projection document ( To return specific fields and the document’s To withhold specific fields, specify the fields in the projection
document with a value of Note You may specify either fields to include or fields to withhold
but not both. For example, the following projection is
invalid because it simultaneously includes the The exception to this rule is the |
Limit RemoteFindOptions.limit: <int> |
Optional. The findOne method ignores this value completely. |
Result Class resultClass: <class> |
Optional. Indicates the type of the document returned by the operation. |
Parameter | Description |
---|---|
Query Filter filter: <document> |
Optional. Default If multiple documents match the query, only the first document in sort order or natural order will be updated. |
Find Options options: <RemoteFindOptions> |
Optional: A |
Limit RemoteFindOptions.limit: <Int64> |
Optional. The maximum number of documents to include in the
query result set. If the result set contains more documents
than the specified limit , the query will return documents
in order up to the limit not to exceed 50,000 documents. |
Projection RemoteFindOptions.projection: <document> |
Optional. A document that specifies which fields MongoDB should return or withhold in the returned document. To return all fields in the document, omit this parameter. To return specific fields and the document’s To withhold specific fields, specify the fields in the projection
document with a value of Note You may specify either fields to include or fields to
withhold but not both. For example, the following projection
is invalid because it simultaneously includes the
The exception to this rule is the |
Sort RemoteFindOptions.sort: <document> |
Optional. Specifies the query sort order. Sort documents
specify one or more fields to sort on where the value of each
field indicates whether MongoDB should sort it in ascending
( Example The following sort document specifies that documents should be
sorted first by |
completionHandler (StitchResult<CollectionType?>) -> Void |
Required. A completion handler that accepts StitchResult optional. This should be matched to check for successful completion of the operation. |
Return Value¶
- Functions
- JavaScript SDK
- Android SDK
- iOS SDK
The collection.findOne()
action returns a Promise that resolves to the
first document in the collection that matches the query filter. If no
documents match the specified query, the promise resolves to
null
.
The collection.findOne()
action returns a Promise that resolves to the
first document in the collection that matches the query filter. If no
documents match the specified query, the promise resolves to
null
.
The findOne()
function returns a
Task
containing the matched document, which can be accessed using
the task.getResult()
method. The type of the result
contained within the
Task
varies based on the configuration of the
RemoteMongoCollection
used for the operation and the value of the resultClass
parameter.
- If
resultClass
is specified, the returned Task contains an object of typeResultT
, which resolves to typeresultClass
. - If a
resultClass
is not specified, the returned Task contains an object of typeDocumentT
, which resolves to typeDocument
unless otherwise specified when the RemoteMongoCollection was instantiated. - If no document matches the provided query, the task will fail
and details can be accessed using
task.getException()
. If no
The findOne
method will call the supplied completionHandler
with
a StitchResult