Method: AWS::DynamoDB::ItemCollection#query

Defined in:
lib/aws/dynamo_db/item_collection.rb

#query(options = {}, &block) ⇒ Object

Note:

This method is only valid for tables with a composite primary key.

Queries the items in the table by primary key values. This operation is generally more efficient than the scan operation, which always scans the whole table. A Query operation searches for a specific range of keys satisfying a given set of key conditions and does not have the added step of filtering out results.

# find all items with a given hash key value
items.query(:hash_value => "abc123")

# get only the colors attribute of each item
items.query(
  :hash_value => "abc123",
  :select => [:colors])

# find only the items where the range key is between two values
items.query(
  :hash_value => "abc123",
  :range_value => 1..100
)

Parameters:

  • options (Hash) (defaults to: {})

    Options for the query. :hash_value is required. Only one of the following options may be set:

    • :range_value
    • :range_greater_than
    • :range_less_than
    • :range_gte
    • :range_lte
    • :range_begins_with
  • [Boolean] (Hash)

    a customizable set of options

  • :select (Hash)

    a customizable set of options

Options Hash (options):

  • :hash_value (String, Numeric)

    Attribute value of the hash component of the composite primary key.

  • :select (Array<String, Symbol>, String, Symbol)

    Attribute name or names to retrieve. When this option is set, the returned or yielded items will be instances of AWS::DynamoDB::ItemData instead of AWS::DynamoDB::Item. The special value :all indicates that all attributes should be retrieved and returned in ItemData instances.

  • :range_value (String, Numeric, Range)

    Specifies which range key values to find in the table. If this is a Range, the query will return items with range key values between the beginning and end of the range (inclusive). If it is a string or number, the query will return only the item with that range key value.

  • :range_greater_than (String, Numeric)

    Matches items where the range key value is greater than this value.

  • :range_less_than (String, Numeric)

    Matches items where the range key value is less than this value.

  • :range_gte (String, Numeric)

    Matches items where the range key value is greater than or equal to this value.

  • :range_lte (String, Numeric)

    Matches items where the range key value is less than or equal to this value.

  • :range_begins_with (String, Numeric)

    Matches items where the range key value begins with this value. This option is only valid if the range key is a string.

Raises:

  • (ArgumentError)


697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
# File 'lib/aws/dynamo_db/item_collection.rb', line 697

def query(options = {}, &block)

  options = options.merge(:query => true)

  raise ArgumentError, "a hash key value is required" unless
    options[:hash_value]

  options[:hash_key_value] =
    format_attribute_value(options.delete(:hash_value))

  range = options.delete(:range_value)
  range_op = nil
  value_list = []
  if range and range.kind_of?(Range)
    value_list = [format_attribute_value(range.begin),
                  format_attribute_value(range.end)]
    range_op = "BETWEEN"
  elsif range
    value_list = [format_attribute_value(range)]
    range_op = "EQ"
  end

  RANGE_KEY_OPTIONS.each do |name, op|
    if value = options.delete(name)
      raise(ArgumentError,
            "only one range key condition is supported") if range_op
      range_op = op
      value_list = [format_attribute_value(value)]
    end
  end

  options[:range_key_condition] = {
    :attribute_value_list => value_list,
    :comparison_operator => range_op
  } if range_op

  if select = options.delete(:select)
    options[:item_data] = true
    options[:attributes_to_get] = select.map do |att|
      att.to_s
    end unless select == :all
  end

  if block
    each(options, &block)
  else
    enumerator(options)
  end
end