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:



471
472
473
 
# File 'lib/aws-record/record/item_operations.rb', line 471

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.



555
556
557
558
559
560
561
 
# File 'lib/aws-record/record/item_operations.rb', line 555

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 Aws::DynamoDB::Client#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:



505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
 
# File 'lib/aws-record/record/item_operations.rb', line 505

def find_with_opts(opts)
  key = opts.delete(:key)
  request_key = {}
  @keys.keys.each_value do |attr_sym|
    raise Errors::KeyMissing, "Missing required key #{attr_sym} in #{key}" unless key[attr_sym]

    attr_name = attributes.storage_name_for(attr_sym)
    request_key[attr_name] = attributes.attribute_for(attr_sym)
                                       .serialize(key[attr_sym])
  end
  get_opts = {
    table_name: table_name,
    key: request_key
  }.merge(opts)
  resp = dynamodb_client.get_item(get_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.



395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
 
# File 'lib/aws-record/record/item_operations.rb', line 395

def tfind_opts(opts)
  opts = opts.dup
  key = opts.delete(:key)
  request_key = {}
  @keys.keys.each_value do |attr_sym|
    raise Errors::KeyMissing, "Missing required key #{attr_sym} in #{key}" unless key[attr_sym]

    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.



371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
 
# File 'lib/aws-record/record/item_operations.rb', line 371

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|
    raise Errors::KeyMissing, "Missing required key #{attr_sym} in #{key}" unless key[attr_sym]

    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.



446
447
448
449
450
451
452
453
454
455
 
# File 'lib/aws-record/record/item_operations.rb', line 446

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(new_params, 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:

  • new_params (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.

  • opts (Hash) (defaults to: {}) —

    Options to pass through to the Aws::DynamoDB::Client#update_item call.

Raises:



589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
 
# File 'lib/aws-record/record/item_operations.rb', line 589

def update(new_params, opts = {})
  key = {}
  @keys.keys.each_value do |attr_sym|
    unless (value = new_params.delete(attr_sym))
      raise Errors::KeyMissing, "Missing required key #{attr_sym} in #{new_params}"
    end

    attr_name = attributes.storage_name_for(attr_sym)
    key[attr_name] = attributes.attribute_for(attr_sym).serialize(value)
  end
  update_opts = {
    table_name: table_name,
    key: key
  }
  update_expression_opts = _build_update_expression(new_params)
  opts = _merge_update_expression_opts(update_expression_opts, opts)
  dynamodb_client.update_item(opts.merge(update_opts))
end