Module: Aws::Record::ItemOperations::ItemOperationsClassMethods

Included in:
Aws::Record
Defined in:
lib/aws-record/record/item_operations.rb

Instance Method Summary collapse

Instance Method Details

#find(opts) ⇒ Aws::Record

Returns builds and returns an instance of your model.

Examples:

Usage Example

class MyModel
  include Aws::Record
  integer_attr :id,   hash_key: true
  string_attr  :name, range_key: true
end

MyModel.find(id: 1, name: "First")

Parameters:

  • opts (Hash) —

    attribute-value pairs for the key you wish to search for.

Returns:

  • (Aws::Record) —

    builds and returns an instance of your model.

Raises:



460
461
462
 
# File 'lib/aws-record/record/item_operations.rb', line 460

def find(opts)
  find_with_opts(key: opts)
end

#find_all(keys) ⇒ Aws::Record::BatchRead

Provides support for the Aws::DynamoDB::Client#batch_get_item for your model.

This method will take a list of keys and return an instance of Aws::Record::BatchRead

See Batch.read for more details.

Examples:

Usage Example

class MyModel
  include Aws::Record
  integer_attr :id,   hash_key: true
  string_attr  :name, range_key: true
end

# returns a homogenous list of items
foo_items = MyModel.find_all(
  [
    {id: 1, name: 'n1'},
    {id: 2, name: 'n2'}
  ])

Parameters:

  • keys (Array) —

    an array of item key hashes you wish to search for.

Returns:

  • (Aws::Record::BatchRead) —

    An instance that contains modeled items from the BatchGetItem result and stores unprocessed keys to be manually processed later.

Raises:

  • (Aws::Record::Errors::KeyMissing) —

    if your param hashes do not include all the keys defined in model.

  • (ArgumentError) —

    if the provided keys are a duplicate.



544
545
546
547
548
549
550
 
# File 'lib/aws-record/record/item_operations.rb', line 544

def find_all(keys)
  Aws::Record::Batch.read do |db|
    keys.each do |key|
      db.find(self, key)
    end
  end
end

#find_with_opts(opts) ⇒ Aws::Record

Note that #find_with_opts will pass through all options other than :key unaltered to the underlying Aws::DynamoDB::Client#get_item request. You should ensure that you have an aws-sdk gem version which supports the options you are including, and avoid adding options not recognized by the underlying client to avoid runtime exceptions.

Examples:

Usage Example

class MyModel
  include Aws::Record
  integer_attr :id,   hash_key: true
  string_attr  :name, range_key: true
end

MyModel.find_with_opts(
  key: { id: 1, name: "First" },
  consistent_read: true
)

Parameters:

  • opts (Hash) —

    Options to pass through to the DynamoDB #get_item request. The :key option is a special case where attributes are serialized and translated for you similar to the #find method.

Options Hash (opts):

  • :key (Hash) —

    attribute-value pairs for the key you wish to search for.

Returns:

  • (Aws::Record) —

    builds and returns an instance of your model.

Raises:



490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
 
# File 'lib/aws-record/record/item_operations.rb', line 490

def find_with_opts(opts)
  key = opts.delete(:key)
  request_key = {}
  @keys.keys.each_value do |attr_sym|
    unless key[attr_sym]
      raise Errors::KeyMissing.new(
        "Missing required key #{attr_sym} in #{key}"
      )
    end
    attr_name = attributes.storage_name_for(attr_sym)
    request_key[attr_name] = attributes.attribute_for(attr_sym).
      serialize(key[attr_sym])
  end
  request_opts = {
    table_name: table_name,
    key: request_key
  }.merge(opts)
  resp = dynamodb_client.get_item(request_opts)
  if resp.item.nil?
    nil
  else
    build_item_from_resp(resp)
  end
end

#tfind_opts(opts) ⇒ Object

Used in Transactions.transact_find, which is a way to run transactional find across multiple DynamoDB items, including transactions which get items across multiple actual or virtual tables.

This operation provide extra metadata used to marshal your items after retrieval.

See transact_find for more info and usage example.



382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
 
# File 'lib/aws-record/record/item_operations.rb', line 382

def tfind_opts(opts)
  opts = opts.dup
  key = opts.delete(:key)
  request_key = {}
  @keys.keys.each_value do |attr_sym|
    unless key[attr_sym]
      raise Errors::KeyMissing.new(
        "Missing required key #{attr_sym} in #{key}"
      )
    end
    attr_name = attributes.storage_name_for(attr_sym)
    request_key[attr_name] = attributes.attribute_for(attr_sym).
      serialize(key[attr_sym])
  end
  # this is a :get item used by #transact_get_items, with the exception
  # of :model_class which needs to be removed before passing along
  opts[:key] = request_key
  opts[:table_name] = table_name
  {
    model_class: self,
    get: opts
  }
end

#transact_check_expression(opts) ⇒ Hash

Allows you to build a “check” expression for use in transactional write operations.

See transact_write for more info.

Examples:

Usage Example

check_exp = Model.transact_check_expression(
  key: { uuid: "foo" },
  condition_expression: "size(#T) <= :v",
  expression_attribute_names: {
    "#T" => "body"
  },
  expression_attribute_values: {
    ":v" => 1024
  }
)

Parameters:

  • opts (Hash) —

    Options matching the :condition_check contents in the Aws::DynamoDB::Client#transact_write_items API, with the exception that keys will be marshalled for you, and the table name will be provided for you by the operation.

Returns:

  • (Hash) —

    Options suitable to be used as a check expression when calling the #transact_write operation.



355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
 
# File 'lib/aws-record/record/item_operations.rb', line 355

def transact_check_expression(opts)
  # need to transform the key, and add the table name
  opts = opts.dup
  key = opts.delete(:key)
  check_key = {}
  @keys.keys.each_value do |attr_sym|
    unless key[attr_sym]
      raise Errors::KeyMissing.new(
        "Missing required key #{attr_sym} in #{key}"
      )
    end
    attr_name = attributes.storage_name_for(attr_sym)
    check_key[attr_name] = attributes.attribute_for(attr_sym).
      serialize(key[attr_sym])
  end
  opts[:key] = check_key
  opts[:table_name] = table_name
  opts
end

#transact_find(opts) ⇒ OpenStruct

Provides a way to run a transactional find across multiple DynamoDB items, including transactions which get items across multiple actual or virtual tables.

Examples:

Usage Example

class Table
  include Aws::Record
  string_attr :hk, hash_key: true
  string_attr :rk, range_key: true
end

results = Table.transact_find(
  transact_items: [
    {key: { hk: "hk1", rk: "rk1"}},
    {key: { hk: "hk2", rk: "rk2"}}
  ]
) # => results.responses contains nil or instances of Table

Parameters:

  • opts (Hash) —

    Options to pass through to Aws::DynamoDB::Client#transact_get_items, with the exception of the :transact_items array, which uses the #tfind_opts operation on your model class to provide extra metadata used to marshal your items after retrieval.

Options Hash (opts):

  • :transact_items (Array) —

    A set of options describing instances of the model class to return.

Returns:

  • (OpenStruct) —

    Structured like the client API response from #transact_get_items, except that the responses member contains Aws::Record items marshaled into the model class used to call this method. See the usage example.



435
436
437
438
439
440
441
442
443
444
 
# File 'lib/aws-record/record/item_operations.rb', line 435

def transact_find(opts)
  opts = opts.dup
  transact_items = opts.delete(:transact_items)
  global_transact_items = transact_items.map do |topts|
    tfind_opts(topts)
  end
  opts[:transact_items] = global_transact_items
  opts[:client] = dynamodb_client
  Transactions.transact_find(opts)
end

#update(opts) ⇒ Object

Performs an Aws::DynamoDB::Client#update_item call immediately on the table, using the attribute key/value pairs provided.

Examples:

Usage Example

class MyModel
  include Aws::Record
  integer_attr :id,   hash_key: true
  string_attr  :name, range_key: true
  string_attr  :body
  boolean_attr :sir_not_appearing_in_this_example
end

MyModel.update(id: 1, name: "First", body: "Hello!")

Parameters:

  • opts (Hash) —

    attribute-value pairs for the update operation you wish to perform. You must include all key attributes for a valid call, then you may optionally include any other attributes that you wish to update.

Raises:



574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
 
# File 'lib/aws-record/record/item_operations.rb', line 574

def update(opts)
  key = {}
  updates = {}
  @keys.keys.each_value do |attr_sym|
    unless value = opts.delete(attr_sym)
      raise Errors::KeyMissing.new(
        "Missing required key #{attr_sym} in #{opts}"
      )
    end
    attr_name = attributes.storage_name_for(attr_sym)
    key[attr_name] = attributes.attribute_for(attr_sym).serialize(value)
  end
  request_opts = {
    table_name: table_name,
    key: key
  }
  update_tuple = _build_update_expression(opts)
  unless update_tuple.nil?
    uex, exp_attr_names, exp_attr_values = update_tuple
    request_opts[:update_expression] = uex
    request_opts[:expression_attribute_names] = exp_attr_names
    request_opts[:expression_attribute_values] = exp_attr_values unless exp_attr_values.empty?
  end
  dynamodb_client.update_item(request_opts)
end