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:



449
450
451
 
# File 'lib/aws-record/record/item_operations.rb', line 449

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.



530
531
532
533
534
535
536
 
# File 'lib/aws-record/record/item_operations.rb', line 530

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:



479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
 
# File 'lib/aws-record/record/item_operations.rb', line 479

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, "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.



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

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, "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.



347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
 
# File 'lib/aws-record/record/item_operations.rb', line 347

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, "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.



424
425
426
427
428
429
430
431
432
433
 
# File 'lib/aws-record/record/item_operations.rb', line 424

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:



560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
 
# File 'lib/aws-record/record/item_operations.rb', line 560

def update(opts)
  key = {}
  @keys.keys.each_value do |attr_sym|
    unless (value = opts.delete(attr_sym))
      raise Errors::KeyMissing, "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