Class: Mongo::Protocol::Query

Inherits:
Message
  • Object
show all
Includes:
Monitoring::Event::Secure
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.

Defined Under Namespace

Classes: Upconverter

Constant Summary

Constants included from Monitoring::Event::Secure

Monitoring::Event::Secure::REDACTED_COMMANDS

Constants inherited from Message

Message::BATCH_SIZE, Message::COLLECTION, Message::LIMIT, Message::MAX_MESSAGE_SIZE, Message::ORDERED, Message::Q

Instance Attribute Summary

Attributes inherited from Message

#request_id

Instance Method Summary collapse

Methods included from Monitoring::Event::Secure

#compression_allowed?, #redacted, #sensitive?

Methods inherited from Message

#==, deserialize, #hash, #maybe_add_server_api, #maybe_decrypt, #maybe_encrypt, #maybe_inflate, #number_returned, #set_request_id

Methods included from Id

included

Constructor Details

#initialize(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.



64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# 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 Method Details

#maybe_compress(compressor, zlib_compression_level = nil) ⇒ Message

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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



125
126
127
 
# 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



93
94
95
96
97
98
99
100
 
# 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

#replyable? ⇒ true

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



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

def replyable?
  true
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.



135
136
137
138
139
 
# 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