Class: Mongo::Protocol::Query

Relationships & Source Files
Namespace Children
Classes: `Upconverter`
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `Message`
Instance Chain: self, `::Mongo::Monitoring::Event::Secure`, `Message`, `Serializers`, `::Mongo::Id`
Inherits:	Mongo::Protocol::Message Object Mongo::Protocol::Message Mongo::Protocol::Query
Defined in:	lib/mongo/protocol/query.rb

Overview

MongoDB Wire protocol Query message.

This is a client request message that is sent to the server in order to retrieve documents matching provided query.

Users may also provide additional options such as a projection, to select a subset of the fields, a number to skip or a limit on the number of returned documents.

There are a variety of flags that can be used to adjust cursor parameters or the desired consistency and integrity the results.

Constant Summary

FLAGS = Internal use only

Available flags for a Query message.

# File 'lib/mongo/protocol/query.rb', line 183

[
  :reserved,
  :tailable_cursor,
  :secondary_ok,
  :oplog_replay,
  :no_cursor_timeout,
  :await_data,
  :exhaust,
  :partial
]

OP_CODE =

The operation code required to specify a Query message.
Returns:
- (Fixnum) —
  
  the operation code.
Since:
- 2.5.0
# File 'lib/mongo/protocol/query.rb', line 175
```
2004
```

Class Method Summary

.new(database, collection, selector, options = {}) ⇒ Query constructor

Creates a new Query message.

`Message` - Inherited

.deserialize	Deserializes messages from an IO stream.
.new	:nodoc:
.deserialize_array	Deserializes an array of fields in a message.
.deserialize_field	Deserializes a single field in a message.
.deserialize_header	Deserializes the header of the message.
.field	A method for declaring a message field.
.fields	A class method for getting the fields for a message class.

Instance Attribute Summary

#replyable? ⇒ true readonly

Query messages require replies from the database.
#flags ⇒ Array<Symbol> rw private
#limit ⇒ Integer rw private
#namespace ⇒ String rw private
#project ⇒ Hash rw private
#selector ⇒ Hash rw private
#skip ⇒ Integer rw private

`Message` - Inherited

#replyable?	The default for messages is not to require a reply after sending a message to the server.
#request_id	Returns the request id for the message.

Instance Method Summary

#maybe_compress(compressor, zlib_compression_level = nil) ⇒ Message Internal use only Internal use only

Compress the message, if the command being sent permits compression.
#payload ⇒ BSON::Document

Return the event payload for monitoring.
#serialize(buffer = BSON::ByteBuffer.new, max_bson_size = nil, bson_overhead = nil) ⇒ BSON::ByteBuffer

Serializes message into bytes that can be sent on the wire.
#determine_limit private
#validate_document_size!(max_bson_size) private

Validate that the documents in this message are all smaller than the maxBsonObjectSize.

`::Mongo::Monitoring::Event::Secure` - Included

#compression_allowed?	Is compression allowed for a given command message.
#redacted	Redact secure information from the document if:
#sensitive?	Check whether the command is sensitive in terms of command monitoring spec.

`Message` - Inherited

#==	Tests for equality between two wire protocol messages by comparing class and field values.
#eql?	Alias for Message#==.
#hash	Creates a hash from the values of the fields of a message.
#maybe_add_server_api,
#maybe_compress	Compress the message, if supported by the wire protocol used and if the command being sent permits compression.
#maybe_decrypt	Possibly decrypt this message with libmongocrypt.
#maybe_encrypt	Possibly encrypt this message with libmongocrypt.
#maybe_inflate	Inflate a message if it is compressed.
#number_returned	Default number returned value for protocol messages.
#serialize	Serializes message into bytes that can be sent on the wire.
#set_request_id	Generates a request id for a message.
#to_s	Alias for Message#serialize.
#compress_if_possible	Compress the message, if the command being sent permits compression.
#fields	A method for getting the fields for a message class.
#merge_sections,
#serialize_fields	Serializes message fields into a buffer.
#serialize_header	Serializes the header of the message consisting of 4 32bit integers.

Constructor Details

.new(database, collection, selector, options = {}) ⇒ `Query`

Creates a new Query message

Examples:

Find all users named Tyler.

Query.new('xgen', 'users', {:name => 'Tyler'})

Find all users named Tyler skipping 5 and returning 10.

Query.new('xgen', 'users', {:name => 'Tyler'}, :skip => 5,
                                               :limit => 10)

Find all users with secondaryOk bit set

Query.new('xgen', 'users', {:name => 'Tyler'}, :flags => [:secondary_ok])

Find all user ids.

Query.new('xgen', 'users', {}, :fields => {:id => 1})

Parameters:

database (String, Symbol) —

The database to query.
collection (String, Symbol) —

The collection to query.
selector (Hash) —

The query selector.
options (Hash) (defaults to: {}) —

The additional query options.

Options Hash (options):

:flags (Array<Symbol>) —

The flag bits. Currently supported values are :await_data, :exhaust, :no_cursor_timeout, :oplog_replay, :partial, :secondary_ok, :tailable_cursor.
:limit (Integer) —

The number of documents to return.
:project (Hash) —

The projection.
:skip (Integer) —

The number of documents to skip.

[ GitHub ]

# File 'lib/mongo/protocol/query.rb', line 64


def initialize(database, collection, selector, options = {})
  @database = database
  @namespace = "#{database}.#{collection}"
  if selector.nil?
    raise ArgumentError, 'Selector cannot be nil'
  end
  @selector = selector
  @options = options
  @project = options[:project]
  @limit = determine_limit
  @skip = options[:skip]  || 0
  @flags = options[:flags] || []
  @upconverter = Upconverter.new(
    collection,
    BSON::Document.new(selector),
    BSON::Document.new(options),
    flags,
  )
  super
end

Instance Attribute Details

#flags ⇒ `Array`<Symbol> (rw, private)

Returns:

(Array<Symbol>) —

The flags for this query message.

[ GitHub ]

# File 'lib/mongo/protocol/query.rb', line 196


field :flags, BitVector.new(FLAGS)

#limit ⇒ `Integer` (rw, private)

Returns:

(Integer) —

The number of documents to return.

[ GitHub ]

# File 'lib/mongo/protocol/query.rb', line 208


field :limit, Int32

#namespace ⇒ `String` (rw, private)

Returns:

(String) —

The namespace for this query message.

[ GitHub ]

# File 'lib/mongo/protocol/query.rb', line 200


field :namespace, CString

#project ⇒ `Hash` (rw, private)

Returns:

(Hash) —

The projection.

[ GitHub ]

# File 'lib/mongo/protocol/query.rb', line 216


field :project, Document

#replyable? ⇒ `true` (readonly)

Query messages require replies from the database.

Examples:

Does the message require a reply?

message.replyable?

Returns:

(true) —

Always true for queries.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/protocol/query.rb', line 110


def replyable?
  true
end

#selector ⇒ `Hash` (rw, private)

Returns:

(Hash) —

The query selector.

[ GitHub ]

# File 'lib/mongo/protocol/query.rb', line 212


field :selector, Document

#skip ⇒ `Integer` (rw, private)

Returns:

(Integer) —

The number of documents to skip.

[ GitHub ]

# File 'lib/mongo/protocol/query.rb', line 204


field :skip, Int32

Instance Method Details

#determine_limit (private)

[ GitHub ]

# File 'lib/mongo/protocol/query.rb', line 177


def determine_limit
  [ @options[:limit] || @options[:batch_size], @options[:batch_size] || @options[:limit] ].min || 0
end

#maybe_compress(compressor, zlib_compression_level = nil) ⇒ Message

This method is for internal use only.

Compress the message, if the command being sent permits compression. Otherwise returns self.

Parameters:

compressor (String, Symbol) —

The compressor to use.
zlib_compression_level (Integer) (defaults to: nil) —

The zlib compression level to use.

Returns:

(Message) —

A Protocol::Compressed message or self, depending on whether this message can be compressed.

Since:

2.5.0

[ GitHub ]

# File 'lib/mongo/protocol/query.rb', line 125


def maybe_compress(compressor, zlib_compression_level = nil)
  compress_if_possible(selector.keys.first, compressor, zlib_compression_level)
end

#payload ⇒ `BSON::Document`

Return the event payload for monitoring.

Examples:

Return the event payload.

message.payload

Returns:

(BSON::Document) —

The event payload.

Since:

2.1.0

[ GitHub ]

# File 'lib/mongo/protocol/query.rb', line 93


def payload
  BSON::Document.new(
    command_name: upconverter.command_name,
    database_name: @database,
    command: upconverter.command,
    request_id: request_id
  )
end

#serialize(buffer = BSON::ByteBuffer.new, max_bson_size = nil, bson_overhead = nil) ⇒ `BSON::ByteBuffer`

Serializes message into bytes that can be sent on the wire.

Parameters:

buffer (BSON::ByteBuffer) (defaults to: BSON::ByteBuffer.new) —

where the message should be inserted.
max_bson_size (Integer) (defaults to: nil) —

The maximum bson object size.

Returns:

(BSON::ByteBuffer) —

buffer containing the serialized message.

[ GitHub ]

# File 'lib/mongo/protocol/query.rb', line 135


def serialize(buffer = BSON::ByteBuffer.new, max_bson_size = nil, bson_overhead = nil)
  validate_document_size!(max_bson_size)

  super
end

#validate_document_size!(max_bson_size) (private)

Validate that the documents in this message are all smaller than the maxBsonObjectSize. If not, raise an exception.

[ GitHub ]

# File 'lib/mongo/protocol/query.rb', line 149


def validate_document_size!(max_bson_size)
  max_bson_size ||= Mongo::Server::ConnectionBase::DEFAULT_MAX_BSON_OBJECT_SIZE

  documents = if @selector.key?(:documents)
                @selector[:documents]
              elsif @selector.key?(:deletes)
                @selector[:deletes]
              elsif @selector.key?(:updates)
                @selector[:updates]
              else
                []
              end

  contains_too_large_document = documents.any? do |doc|
    doc.to_bson.length > max_bson_size
  end

  if contains_too_large_document
    raise Error::MaxBSONSize.new('The document exceeds maximum allowed BSON object size after serialization')
  end
end

Class: Mongo::Protocol::Query

Overview

Constant Summary

Serializers - Included

Message - Inherited

::Mongo::Monitoring::Event::Secure - Included

Class Method Summary

Message - Inherited

Instance Attribute Summary

Message - Inherited

Instance Method Summary

::Mongo::Monitoring::Event::Secure - Included

Message - Inherited

Constructor Details

.new(database, collection, selector, options = {}) ⇒ Query

Instance Attribute Details

#flags ⇒ Array<Symbol> (rw, private)

#limit ⇒ Integer (rw, private)

#namespace ⇒ String (rw, private)

#project ⇒ Hash (rw, private)

#replyable? ⇒ true (readonly)

#selector ⇒ Hash (rw, private)

#skip ⇒ Integer (rw, private)

Instance Method Details

#determine_limit (private)

#maybe_compress(compressor, zlib_compression_level = nil) ⇒ Message

#payload ⇒ BSON::Document

#serialize(buffer = BSON::ByteBuffer.new, max_bson_size = nil, bson_overhead = nil) ⇒ BSON::ByteBuffer

#validate_document_size!(max_bson_size) (private)

`Serializers` - Included

`Message` - Inherited

`::Mongo::Monitoring::Event::Secure` - Included

`Message` - Inherited

`Message` - Inherited

`::Mongo::Monitoring::Event::Secure` - Included

`Message` - Inherited

.new(database, collection, selector, options = {}) ⇒ `Query`

#flags ⇒ `Array`<Symbol> (rw, private)

#limit ⇒ `Integer` (rw, private)

#namespace ⇒ `String` (rw, private)

#project ⇒ `Hash` (rw, private)

#replyable? ⇒ `true` (readonly)

#selector ⇒ `Hash` (rw, private)

#skip ⇒ `Integer` (rw, private)

#payload ⇒ `BSON::Document`

#serialize(buffer = BSON::ByteBuffer.new, max_bson_size = nil, bson_overhead = nil) ⇒ `BSON::ByteBuffer`