AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

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:



451
452
453
# File 'lib/aws-record/record/item_operations.rb', line 451

def find(opts)
  find_with_opts(key: opts)
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:



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

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



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

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.

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.



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

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.



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

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:



528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
# File 'lib/aws-record/record/item_operations.rb', line 528

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