Class representing the optional arguments to a MongoDB query. More...

#include <find.hpp>

Public Member Functions
find &	allow_disk_use (bool allow_disk_use)
	Enables writing to temporary files on the server. More...

const stdx::optional< bool > &	allow_disk_use () const
	Gets the current setting for allowing disk use on the server. More...

find &	allow_partial_results (bool allow_partial)
	Sets whether to allow partial results from a mongos if some shards are down (instead of throwing an error). More...

const stdx::optional< bool > &	allow_partial_results () const
	Gets the current setting for allowing partial results from mongos. More...

find &	batch_size (std::int32_t batch_size)
	Sets the number of documents to return per batch. More...

const stdx::optional< std::int32_t > &	batch_size () const
	The current batch size setting. More...

find &	collation (bsoncxx::document::view_or_value collation)
	Sets the collation for this operation. More...

const stdx::optional< bsoncxx::document::view_or_value > &	collation () const
	Retrieves the current collation for this operation. More...

find &	comment (bsoncxx::string::view_or_value comment)
	Attaches a comment to the query. More...

const stdx::optional< bsoncxx::string::view_or_value > &	comment () const
	Gets the current comment attached to this query. More...

find &	cursor_type (cursor::type cursor_type)
	Indicates the type of cursor to use for this query. More...

const stdx::optional< cursor::type > &	cursor_type () const
	Gets the current cursor type. More...

find &	hint (class hint index_hint)
	Sets the index to use for this operation. More...

const stdx::optional< class hint > &	hint () const
	Gets the current hint. More...

find &	let (bsoncxx::document::view_or_value let)
	Set the value of the let option. More...

const stdx::optional< bsoncxx::document::view_or_value >	let () const
	Gets the current value of the let option. More...

find &	comment_option (bsoncxx::types::bson_value::view_or_value comment)
	Set the value of the comment option. More...

const stdx::optional< bsoncxx::types::bson_value::view_or_value > &	comment_option () const
	Gets the current value of the comment option. More...

find &	limit (std::int64_t limit)
	Sets maximum number of documents to return. More...

const stdx::optional< std::int64_t > &	limit () const
	Gets the current limit. More...

find &	max (bsoncxx::document::view_or_value max)
	Gets the current exclusive upper bound for a specific index. More...

const stdx::optional< bsoncxx::document::view_or_value > &	max () const
	Sets the current exclusive upper bound for a specific index. More...

find &	max_await_time (std::chrono::milliseconds max_await_time)
	The maximum amount of time for the server to wait on new documents to satisfy a tailable cursor query. More...

const stdx::optional< std::chrono::milliseconds > &	max_await_time () const
	The maximum amount of time for the server to wait on new documents to satisfy a tailable cursor query. More...

find &	max_time (std::chrono::milliseconds max_time)
	Sets the maximum amount of time for this operation to run (server-side) in milliseconds. More...

const stdx::optional< std::chrono::milliseconds > &	max_time () const
	The current max_time_ms setting. More...

find &	min (bsoncxx::document::view_or_value min)
	Gets the current inclusive lower bound for a specific index. More...

const stdx::optional< bsoncxx::document::view_or_value > &	min () const
	Sets the current inclusive lower bound for a specific index. More...

find &	no_cursor_timeout (bool no_cursor_timeout)
	Sets the cursor flag to prevent cursor from timing out server-side due to a period of inactivity. More...

const stdx::optional< bool > &	no_cursor_timeout () const
	Gets the current no_cursor_timeout setting. More...

find &	projection (bsoncxx::document::view_or_value projection)
	Sets a projection which limits the returned fields for all matching documents. More...

const stdx::optional< bsoncxx::document::view_or_value > &	projection () const
	Gets the current projection set on this query. More...

find &	read_preference (class read_preference rp)
	Sets the read_preference for this operation. More...

const stdx::optional< class read_preference > &	read_preference () const
	The current read_preference for this operation. More...

find &	return_key (bool return_key)
	Sets whether to return the index keys associated with the query results, instead of the actual query results themselves. More...

const stdx::optional< bool > &	return_key () const
	Gets the current setting for returning the index keys associated with the query results, instead of the actual query results themselves. More...

find &	show_record_id (bool show_record_id)
	Sets whether to include the record identifier for each document in the query results. More...

const stdx::optional< bool > &	show_record_id () const
	Gets the current setting for whether the record identifier is returned for each document in the query results. More...

find &	skip (std::int64_t skip)
	Sets the number of documents to skip before returning results. More...

const stdx::optional< std::int64_t > &	skip () const
	Gets the current number of documents to skip. More...

find &	sort (bsoncxx::document::view_or_value ordering)
	The order in which to return matching documents. More...

const stdx::optional< bsoncxx::document::view_or_value > &	sort () const
	Gets the current sort ordering for this query. More...

Detailed Description

Class representing the optional arguments to a MongoDB query.

Examples: examples/mongocxx/client_session.cpp.

Member Function Documentation

◆ allow_disk_use() [1/2]

const stdx::optional<bool>& mongocxx::options::find::allow_disk_use ( ) const

Gets the current setting for allowing disk use on the server.

This option may only be used with MongoDB version 4.4 or later.

Returns: Whether disk use on the server is allowed.

◆ allow_disk_use() [2/2]

find& mongocxx::options::find::allow_disk_use ( bool allow_disk_use )

Enables writing to temporary files on the server.

When set to true, the server can write temporary data to disk while executing the find operation.

This option is sent only if the caller explicitly provides a value. The default is to not send a value.

This option may only be used with MongoDB version 4.4 or later.

Parameters

allow_disk_use Whether to allow writing temporary files on the server.

Returns: A reference to this object to facilitate method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ allow_partial_results() [1/2]

const stdx::optional<bool>& mongocxx::options::find::allow_partial_results ( ) const

Gets the current setting for allowing partial results from mongos.

Returns: Whether partial results from mongos are allowed.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ allow_partial_results() [2/2]

find& mongocxx::options::find::allow_partial_results ( bool allow_partial )

Sets whether to allow partial results from a mongos if some shards are down (instead of throwing an error).

Parameters

allow_partial Whether to allow partial results from mongos.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ batch_size() [1/2]

const stdx::optional<std::int32_t>& mongocxx::options::find::batch_size ( ) const

The current batch size setting.

Returns: The current batch size.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ batch_size() [2/2]

find& mongocxx::options::find::batch_size ( std::int32_t batch_size )

Sets the number of documents to return per batch.

Parameters

batch_size The size of the batches to request.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ collation() [1/2]

const stdx::optional<bsoncxx::document::view_or_value>& mongocxx::options::find::collation ( ) const

Retrieves the current collation for this operation.

Returns: The current collation.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ collation() [2/2]

find& mongocxx::options::find::collation ( bsoncxx::document::view_or_value collation )

Sets the collation for this operation.

Parameters

collation The new collation.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ comment() [1/2]

const stdx::optional<bsoncxx::string::view_or_value>& mongocxx::options::find::comment ( ) const

Gets the current comment attached to this query.

Deprecated:: use comment_option instead.

Returns: The comment attached to this query.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ comment() [2/2]

find& mongocxx::options::find::comment ( bsoncxx::string::view_or_value comment )

Attaches a comment to the query.

If $comment also exists in the modifiers document then the comment field overwrites $comment.

Deprecated:: use comment_option instead.

Parameters

comment The comment to attach to this query.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ comment_option() [1/2]

const stdx::optional<bsoncxx::types::bson_value::view_or_value>& mongocxx::options::find::comment_option ( ) const

Gets the current value of the comment option.

Note: Not to be confused with the $comment query modifier.

Returns: The current comment option.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ comment_option() [2/2]

find& mongocxx::options::find::comment_option ( bsoncxx::types::bson_value::view_or_value comment )

Set the value of the comment option.

Note: Not to be confused with the $comment query modifier.

Parameters

comment The new comment option.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ cursor_type() [1/2]

const stdx::optional<cursor::type>& mongocxx::options::find::cursor_type ( ) const

Gets the current cursor type.

Returns: The current cursor type.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ cursor_type() [2/2]

find& mongocxx::options::find::cursor_type ( cursor::type cursor_type )

Indicates the type of cursor to use for this query.

Parameters

cursor_type The cursor type to set.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ hint() [1/2]

const stdx::optional<class hint>& mongocxx::options::find::hint ( ) const

Gets the current hint.

Returns: The current hint, if one is set.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ hint() [2/2]

find& mongocxx::options::find::hint ( class hint index_hint )

Sets the index to use for this operation.

See also: https://docs.mongodb.com/manual/reference/command/find/

Note: if the server already has a cached shape for this query, it may ignore a hint.

Parameters

index_hint Object representing the index to use.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ let() [1/2]

const stdx::optional<bsoncxx::document::view_or_value> mongocxx::options::find::let ( ) const

Gets the current value of the let option.

Returns: The current let option.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ let() [2/2]

find& mongocxx::options::find::let ( bsoncxx::document::view_or_value let )

Set the value of the let option.

Parameters

let	The new let option.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ limit() [1/2]

const stdx::optional<std::int64_t>& mongocxx::options::find::limit ( ) const

Gets the current limit.

Returns: The current limit.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ limit() [2/2]

find& mongocxx::options::find::limit ( std::int64_t limit )

Sets maximum number of documents to return.

Parameters

limit The maximum number of documents to return.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ max() [1/2]

const stdx::optional<bsoncxx::document::view_or_value>& mongocxx::options::find::max ( ) const

Sets the current exclusive upper bound for a specific index.

Returns: The exclusive upper bound for a specific index.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ max() [2/2]

find& mongocxx::options::find::max ( bsoncxx::document::view_or_value max )

Gets the current exclusive upper bound for a specific index.

Parameters

max	The exclusive upper bound for a specific index.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ max_await_time() [1/2]

const stdx::optional<std::chrono::milliseconds>& mongocxx::options::find::max_await_time ( ) const

The maximum amount of time for the server to wait on new documents to satisfy a tailable cursor query.

Returns: The current max await time (in milliseconds).

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ max_await_time() [2/2]

find& mongocxx::options::find::max_await_time ( std::chrono::milliseconds max_await_time )

The maximum amount of time for the server to wait on new documents to satisfy a tailable cursor query.

This only applies to a TAILABLE_AWAIT cursor. When the cursor is not a TAILABLE_AWAIT cursor, this option is ignored. The default on the server is to wait for one second.

Note: On servers < 3.2, this option is ignored.

Parameters

max_await_time The max amount of time (in milliseconds) to wait for new documents.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ max_time() [1/2]

const stdx::optional<std::chrono::milliseconds>& mongocxx::options::find::max_time ( ) const

The current max_time_ms setting.

Returns: The current max time (in milliseconds).

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ max_time() [2/2]

find& mongocxx::options::find::max_time ( std::chrono::milliseconds max_time )

Sets the maximum amount of time for this operation to run (server-side) in milliseconds.

Parameters

max_time The max amount of time (in milliseconds).

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

Examples: examples/mongocxx/client_session.cpp.

◆ min() [1/2]

const stdx::optional<bsoncxx::document::view_or_value>& mongocxx::options::find::min ( ) const

Sets the current inclusive lower bound for a specific index.

Returns: The inclusive lower bound for a specific index.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ min() [2/2]

find& mongocxx::options::find::min ( bsoncxx::document::view_or_value min )

Gets the current inclusive lower bound for a specific index.

Parameters

min	The inclusive lower bound for a specific index.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ no_cursor_timeout() [1/2]

const stdx::optional<bool>& mongocxx::options::find::no_cursor_timeout ( ) const

Gets the current no_cursor_timeout setting.

Returns: The current no_cursor_timeout setting.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ no_cursor_timeout() [2/2]

find& mongocxx::options::find::no_cursor_timeout ( bool no_cursor_timeout )

Sets the cursor flag to prevent cursor from timing out server-side due to a period of inactivity.

Parameters

no_cursor_timeout When true prevents the cursor from timing out.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ projection() [1/2]

const stdx::optional<bsoncxx::document::view_or_value>& mongocxx::options::find::projection ( ) const

Gets the current projection set on this query.

Returns: The current projection.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ projection() [2/2]

find& mongocxx::options::find::projection ( bsoncxx::document::view_or_value projection )

Sets a projection which limits the returned fields for all matching documents.

Parameters

projection The projection document.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ read_preference() [1/2]

const stdx::optional<class read_preference>& mongocxx::options::find::read_preference ( ) const

The current read_preference for this operation.

Returns: The current read_preference.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ read_preference() [2/2]

find& mongocxx::options::find::read_preference ( class read_preference rp )

Sets the read_preference for this operation.

Parameters

rp	The new read_preference.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

Examples: examples/mongocxx/client_session.cpp.

◆ return_key() [1/2]

const stdx::optional<bool>& mongocxx::options::find::return_key ( ) const

Gets the current setting for returning the index keys associated with the query results, instead of the actual query results themselves.

Returns: Whether index keys associated with the query results are returned, instead of the actual query results themselves.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ return_key() [2/2]

find& mongocxx::options::find::return_key ( bool return_key )

Sets whether to return the index keys associated with the query results, instead of the actual query results themselves.

Parameters

return_key Whether to return the index keys associated with the query results, instead of the actual query results themselves.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ show_record_id() [1/2]

const stdx::optional<bool>& mongocxx::options::find::show_record_id ( ) const

Gets the current setting for whether the record identifier is returned for each document in the query results.

Returns: Whether the record identifier is included.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ show_record_id() [2/2]

find& mongocxx::options::find::show_record_id ( bool show_record_id )

Sets whether to include the record identifier for each document in the query results.

Parameters

show_record_id Whether to include the record identifier.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ skip() [1/2]

const stdx::optional<std::int64_t>& mongocxx::options::find::skip ( ) const

Gets the current number of documents to skip.

Returns: The number of documents to skip.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ skip() [2/2]

find& mongocxx::options::find::skip ( std::int64_t skip )

Sets the number of documents to skip before returning results.

Parameters

skip	The number of documents to skip.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ sort() [1/2]

const stdx::optional<bsoncxx::document::view_or_value>& mongocxx::options::find::sort ( ) const

Gets the current sort ordering for this query.

Returns: The current sort ordering.

See also: https://docs.mongodb.com/manual/reference/command/find/

◆ sort() [2/2]

find& mongocxx::options::find::sort ( bsoncxx::document::view_or_value ordering )

The order in which to return matching documents.

If $orderby also exists in the modifiers document, the sort field takes precedence over $orderby.

Parameters

ordering Document describing the order of the documents to be returned.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/command/find/

The documentation for this class was generated from the following file:

src/mongocxx/options/find.hpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ allow_disk_use() [1/2]

◆ allow_disk_use() [2/2]

◆ allow_partial_results() [1/2]

◆ allow_partial_results() [2/2]

◆ batch_size() [1/2]

◆ batch_size() [2/2]

◆ collation() [1/2]

◆ collation() [2/2]

◆ comment() [1/2]

◆ comment() [2/2]

◆ comment_option() [1/2]

◆ comment_option() [2/2]

◆ cursor_type() [1/2]

◆ cursor_type() [2/2]

◆ hint() [1/2]

◆ hint() [2/2]

◆ let() [1/2]

◆ let() [2/2]

◆ limit() [1/2]

◆ limit() [2/2]

◆ max() [1/2]

◆ max() [2/2]

◆ max_await_time() [1/2]

◆ max_await_time() [2/2]

◆ max_time() [1/2]

◆ max_time() [2/2]

◆ min() [1/2]

◆ min() [2/2]

◆ no_cursor_timeout() [1/2]

◆ no_cursor_timeout() [2/2]

◆ projection() [1/2]

◆ projection() [2/2]

◆ read_preference() [1/2]

◆ read_preference() [2/2]

◆ return_key() [1/2]

◆ return_key() [2/2]

◆ show_record_id() [1/2]

◆ show_record_id() [2/2]

◆ skip() [1/2]

◆ skip() [2/2]

◆ sort() [1/2]

◆ sort() [2/2]