dynamoid 3.10.0 → 3.12.1

data/lib/dynamoid/persistence.rb

@@ -10,6 +10,7 @@ require 'dynamoid/persistence/upsert'
 require 'dynamoid/persistence/save'
 require 'dynamoid/persistence/inc'
 require 'dynamoid/persistence/update_validations'
+require 'dynamoid/persistence/item_updater_with_dumping'
 
 # encoding: utf-8
 module Dynamoid
@@ -18,8 +19,9 @@ module Dynamoid
   module Persistence
     extend ActiveSupport::Concern
 
-    attr_accessor :new_record
+    attr_accessor :new_record, :destroyed
     alias new_record? new_record
+    alias destroyed? destroyed
 
     # @private
     UNIX_EPOCH_DATE = Date.new(1970, 1, 1).freeze
@@ -166,7 +168,7 @@ module Dynamoid
 
       # Create a model.
       #
-      # Initializes a new model and immediately saves it to DynamoDB.
+      # Initializes a new model and immediately saves it into DynamoDB.
       #
       #   User.create(first_name: 'Mark', last_name: 'Tyler')
       #
@@ -174,7 +176,8 @@ module Dynamoid
       #
       #   User.create([{ first_name: 'Alice' }, { first_name: 'Bob' }])
       #
-      # Creates a model and pass it into a block to set other attributes.
+      # Instantiates a model and pass it into an optional block to set other
+      # attributes.
       #
       #   User.create(first_name: 'Mark') do |u|
       #     u.age = 21
@@ -182,7 +185,10 @@ module Dynamoid
       #
       # Validates model and runs callbacks.
       #
-      # @param attrs [Hash|Array[Hash]] Attributes of the models
+      # Raises +Dynamoid::Errors::MissingRangeKey+ if a sort key is required
+      # but not specified or has value +nil+.
+      #
+      # @param attrs [Hash|Array<Hash>] Attributes of a model
       # @param block [Proc] Block to process a document after initialization
       # @return [Dynamoid::Document] The created document
       # @since 0.2.0
@@ -196,12 +202,31 @@ module Dynamoid
 
       # Create a model.
       #
-      # Initializes a new object and immediately saves it to the Dynamoid.
+      # Initializes a new object and immediately saves it into DynamoDB.
+      #
+      #   User.create!(first_name: 'Mark', last_name: 'Tyler')
+      #
       # Raises an exception +Dynamoid::Errors::DocumentNotValid+ if validation
-      # failed. Accepts both Hash and Array of Hashes and can create several
+      # failed.
+      #
+      # Accepts both Hash and Array of Hashes and can create several
       # models.
       #
-      # @param attrs [Hash|Array[Hash]] Attributes with which to create the object.
+      #   User.create!([{ first_name: 'Alice' }, { first_name: 'Bob' }])
+      #
+      # Instantiates a model and pass it into an optional block to set other
+      # attributes.
+      #
+      #   User.create!(first_name: 'Mark') do |u|
+      #     u.age = 21
+      #   end
+      #
+      # Validates model and runs callbacks.
+      #
+      # Raises +Dynamoid::Errors::MissingRangeKey+ if a sort key is required
+      # but not specified or has value +nil+.
+      #
+      # @param attrs [Hash|Array<Hash>] Attributes with which to create the object.
       # @param block [Proc] Block to process a document after initialization
       # @return [Dynamoid::Document] The created document
       # @since 0.2.0
@@ -292,10 +317,16 @@ module Dynamoid
       # Raises a +Dynamoid::Errors::UnknownAttribute+ exception if any of the
       # attributes is not on the model
       #
+      # Raises +Dynamoid::Errors::MissingHashKey+ if a partition key has value
+      # +nil+ and +Dynamoid::Errors::MissingRangeKey+ if a sort key is required
+      # but has value +nil+.
+      #
       # @param hash_key_value [Scalar value] hash key
       # @param range_key_value [Scalar value] range key (optional)
       # @param attrs [Hash]
       # @param conditions [Hash] (optional)
+      # @option conditions [Hash] :if conditions on attribute values
+      # @option conditions [Hash] :unless_exists conditions on attributes presence
       # @return [Dynamoid::Document|nil] Updated document
       def update_fields(hash_key_value, range_key_value = nil, attrs = {}, conditions = {})
         optional_params = [range_key_value, attrs, conditions].compact
@@ -348,12 +379,18 @@ module Dynamoid
       # an updated document back with one HTTP request.
       #
       # Raises a +Dynamoid::Errors::UnknownAttribute+ exception if any of the
-      # attributes is not on the model
+      # attributes is not declared in the model class.
+      #
+      # Raises +Dynamoid::Errors::MissingHashKey+ if a partition key has value
+      # +nil+ and raises +Dynamoid::Errors::MissingRangeKey+ if a sort key is
+      # required but has value +nil+.
       #
       # @param hash_key_value [Scalar value] hash key
       # @param range_key_value [Scalar value] range key (optional)
       # @param attrs [Hash]
       # @param conditions [Hash] (optional)
+      # @option conditions [Hash] :if conditions on attribute values
+      # @option conditions [Hash] :unless_exists conditions on attributes presence
       # @return [Dynamoid::Document|nil] Updated document
       def upsert(hash_key_value, range_key_value = nil, attrs = {}, conditions = {})
         optional_params = [range_key_value, attrs, conditions].compact
@@ -404,9 +441,10 @@ module Dynamoid
       # @param hash_key_value [Scalar value] hash key
       # @param range_key_value [Scalar value] range key (optional)
       # @param counters [Hash] value to increase by
-      # @option counters [true | Symbol | Array[Symbol]] :touch to update update_at attribute and optionally the specified ones
+      # @option counters [true | Symbol | Array<Symbol>] :touch to update update_at attribute and optionally the specified ones
       # @return [Model class] self
       def inc(hash_key_value, range_key_value = nil, counters)
+        # It's similar to Rails' #update_counters.
         Inc.call(self, hash_key_value, range_key_value, counters)
         self
       end
@@ -490,7 +528,7 @@ module Dynamoid
     #
     # +save+ by default sets timestamps attributes - +created_at+ and
     # +updated_at+ when creates new model and updates +updated_at+ attribute
-    # when update already existing one.
+    # when updates already existing one.
     #
     # Changing +updated_at+ attribute at updating a model can be skipped with
     # +touch: false+ option:
@@ -500,7 +538,8 @@ module Dynamoid
     # If a model is new and hash key (+id+ by default) is not assigned yet
     # it was assigned implicitly with random UUID value.
     #
-    # If +lock_version+ attribute is declared it will be incremented. If it's blank then it will be initialized with 1.
+    # If +lock_version+ attribute is declared it will be incremented. If it's
+    # blank then it will be initialized with 1.
     #
     # +save+ method call raises +Dynamoid::Errors::RecordNotUnique+ exception
     # if primary key (hash key + optional range key) already exists in a
@@ -511,6 +550,11 @@ module Dynamoid
     # already changed concurrently and +lock_version+ was consequently
     # increased.
     #
+    # Raises +Dynamoid::Errors::MissingHashKey+ if a model is already persisted
+    # and a partition key has value +nil+ and raises
+    # +Dynamoid::Errors::MissingRangeKey+ if a sort key is required but has
+    # value +nil+.
+    #
     # When a table is not created yet the first +save+ method call will create
     # a table. It's useful in test environment to avoid explicit table
     # creation.
@@ -534,8 +578,89 @@ module Dynamoid
       end
     end
 
+    # Create new model or persist changes.
+    #
+    # Run the validation and callbacks. Raises
+    # +Dynamoid::Errors::DocumentNotValid+ is validation fails.
+    #
+    #   user = User.create
+    #
+    #   user.age = 26
+    #   user.save! # => user
+    #
+    # Validation can be skipped with +validate: false+ option:
+    #
+    #   user = User.new(age: -1)
+    #   user.save!(validate: false) # => user
+    #
+    # +save!+ by default sets timestamps attributes - +created_at+ and
+    # +updated_at+ when creates new model and updates +updated_at+ attribute
+    # when updates already existing one.
+    #
+    # Changing +updated_at+ attribute at updating a model can be skipped with
+    # +touch: false+ option:
+    #
+    #   user.save!(touch: false)
+    #
+    # If a model is new and hash key (+id+ by default) is not assigned yet
+    # it was assigned implicitly with random UUID value.
+    #
+    # If +lock_version+ attribute is declared it will be incremented. If it's
+    # blank then it will be initialized with 1.
+    #
+    # +save!+ method call raises +Dynamoid::Errors::RecordNotUnique+ exception
+    # if primary key (hash key + optional range key) already exists in a
+    # table.
+    #
+    # +save!+ method call raises +Dynamoid::Errors::StaleObjectError+ exception
+    # if there is +lock_version+ attribute and the document in a table was
+    # already changed concurrently and +lock_version+ was consequently
+    # increased.
+    #
+    # +save!+ method call raises +Dynamoid::Errors::RecordNotSaved+ exception
+    # if some callback aborted execution.
+    #
+    # Raises +Dynamoid::Errors::MissingHashKey+ if a model is already persisted
+    # and a partition key has value +nil+ and raises
+    # +Dynamoid::Errors::MissingRangeKey+ if a sort key is required but has
+    # value +nil+.
+    #
+    # When a table is not created yet the first +save!+ method call will create
+    # a table. It's useful in test environment to avoid explicit table
+    # creation.
+    #
+    # @param options [Hash] (optional)
+    # @option options [true|false] :validate validate a model or not - +true+ by default (optional)
+    # @option options [true|false] :touch update tiemstamps fields or not - +true+ by default (optional)
+    # @return [true|false] Whether saving successful or not
+    def save!(options = {})
+      # validation is handled in the Validation module
+
+      if Dynamoid.config.create_table_on_save
+        self.class.create_table(sync: true)
+      end
+
+      create_or_update = new_record? ? :create : :update
+      aborted = true
+
+      run_callbacks(:save) do
+        run_callbacks(create_or_update) do
+          aborted = false
+          Save.call(self, touch: options[:touch])
+        end
+      end
+
+      if aborted
+        raise Dynamoid::Errors::RecordNotSaved, self
+      end
+
+      self
+    end
+
     # Update multiple attributes at once, saving the object once the updates
-    # are complete. Returns +true+ if saving is successful and +false+
+    # are complete.
+    #
+    # Returns +true+ if saving is successful and +false+
     # otherwise.
     #
     #   user.update_attributes(age: 27, last_name: 'Tylor')
@@ -543,6 +668,10 @@ module Dynamoid
     # Raises a +Dynamoid::Errors::UnknownAttribute+ exception if any of the
     # attributes is not on the model
     #
+    # Raises +Dynamoid::Errors::MissingHashKey+ if a partition key has value
+    # +nil+ and raises +Dynamoid::Errors::MissingRangeKey+ if a sort key is
+    # required but has value +nil+.
+    #
     # @param attributes [Hash] a hash of attributes to update
     # @return [true|false] Whether updating successful or not
     # @since 0.2.0
@@ -562,6 +691,10 @@ module Dynamoid
     # Raises a +Dynamoid::Errors::UnknownAttribute+ exception if any of the
     # attributes is not on the model
     #
+    # Raises +Dynamoid::Errors::MissingHashKey+ if a partition key has value
+    # +nil+ and raises +Dynamoid::Errors::MissingRangeKey+ if a sort key is
+    # required but has value +nil+.
+    #
     # @param attributes [Hash] a hash of attributes to update
     def update_attributes!(attributes)
       attributes.each { |attribute, value| write_attribute(attribute, value) }
@@ -586,9 +719,6 @@ module Dynamoid
     # @since 0.2.0
     def update_attribute(attribute, value)
       # final implementation is in the Dynamoid::Validation module
-      write_attribute(attribute, value)
-      save
-      self
     end
 
     # Update a model.
@@ -599,8 +729,7 @@ module Dynamoid
     # attributes. Supports following operations: +add+, +delete+ and +set+.
     #
     # Operation +add+ just adds a value for numeric attributes and join
-    # collections if attribute is a collection (one of +array+, +set+ or
-    # +map+).
+    # collections if attribute is a set.
     #
     #   user.update! do |t|
     #     t.add(age: 1, followers_count: 5)
@@ -625,7 +754,7 @@ module Dynamoid
     # {parameter}[https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.AttributeUpdates.html]
     # of +UpdateItem+ operation.
     #
-    # It's an atomic operation. So adding or deleting elements in a collection
+    # It's atomic operations. So adding or deleting elements in a collection
     # or incrementing or decrementing a numeric field is atomic and does not
     # interfere with other write requests.
     #
@@ -665,21 +794,33 @@ module Dynamoid
 
         begin
           table_name = self.class.table_name
+          partition_key_dumped = Dumping.dump_field(hash_key, self.class.attributes[self.class.hash_key])
+          conditions = conditions.dup
+          conditions[:if] ||= {}
+          conditions[:if][self.class.hash_key] = partition_key_dumped
+          if self.class.range_key
+            sort_key_dumped = Dumping.dump_field(range_value, self.class.attributes[self.class.range_key])
+            conditions[:if][self.class.range_key] = sort_key_dumped
+          end
+
           update_item_options = options.merge(conditions: conditions)
 
-          new_attrs = Dynamoid.adapter.update_item(table_name, hash_key, update_item_options) do |t|
-            t.add(lock_version: 1) if self.class.attributes[:lock_version]
+          new_attrs = Dynamoid.adapter.update_item(table_name, partition_key_dumped, update_item_options) do |t|
+            item_updater = ItemUpdaterWithDumping.new(self.class, t)
+
+            item_updater.add(lock_version: 1) if self.class.attributes[:lock_version]
 
             if self.class.timestamps_enabled?
-              time_now = DateTime.now.in_time_zone(Time.zone)
-              time_now_dumped = Dumping.dump_field(time_now, self.class.attributes[:updated_at])
-              t.set(updated_at: time_now_dumped)
+              item_updater.set(updated_at: DateTime.now.in_time_zone(Time.zone))
             end
 
             yield t
           end
           load(Undumping.undump_attributes(new_attrs, self.class.attributes))
         rescue Dynamoid::Errors::ConditionalCheckFailedException
+          # exception may be raised either because of failed user provided conditions
+          # or because of conditions on partition and sort keys. We cannot
+          # distinguish these two cases.
           raise Dynamoid::Errors::StaleObjectError.new(self, 'update')
         end
       end
@@ -695,8 +836,7 @@ module Dynamoid
     # attributes. Supports following operations: +add+, +delete+ and +set+.
     #
     # Operation +add+ just adds a value for numeric attributes and join
-    # collections if attribute is a collection (one of +array+, +set+ or
-    # +map+).
+    # collections if attribute is a set.
     #
     #   user.update do |t|
     #     t.add(age: 1, followers_count: 5)
@@ -804,7 +944,7 @@ module Dynamoid
     #
     # @param attribute [Symbol] attribute name
     # @param by [Numeric] value to add (optional)
-    # @param touch [true | Symbol | Array[Symbol]] to update update_at attribute and optionally the specified ones
+    # @param touch [true | Symbol | Array<Symbol>] to update update_at attribute and optionally the specified ones
     # @return [Dynamoid::Document] self
     def increment!(attribute, by = 1, touch: nil)
       increment(attribute, by)
@@ -855,7 +995,7 @@ module Dynamoid
     #
     # @param attribute [Symbol] attribute name
     # @param by [Numeric] value to subtract (optional)
-    # @param touch [true | Symbol | Array[Symbol]] to update update_at attribute and optionally the specified ones
+    # @param touch [true | Symbol | Array<Symbol>] to update update_at attribute and optionally the specified ones
     # @return [Dynamoid::Document] self
     def decrement!(attribute, by = 1, touch: nil)
       increment!(attribute, -by, touch: touch)
@@ -870,6 +1010,10 @@ module Dynamoid
     #
     # Returns +self+ if deleted successfully and +false+ otherwise.
     #
+    # Raises +Dynamoid::Errors::MissingHashKey+ if a partition key has value
+    # +nil+ and raises +Dynamoid::Errors::MissingRangeKey+ if a sort key is
+    # required but has value +nil+.
+    #
     # @return [Dynamoid::Document|false] whether deleted successfully
     # @since 0.2.0
     def destroy
@@ -891,6 +1035,10 @@ module Dynamoid
     #
     # Raises +Dynamoid::Errors::RecordNotDestroyed+ exception if model deleting
     # failed.
+    #
+    # Raises +Dynamoid::Errors::MissingHashKey+ if a partition key has value
+    # +nil+ and raises +Dynamoid::Errors::MissingRangeKey+ if a sort key is
+    # required but has value +nil+.
     def destroy!
       destroy || (raise Dynamoid::Errors::RecordNotDestroyed, self)
     end
@@ -903,10 +1051,18 @@ module Dynamoid
     # Raises +Dynamoid::Errors::StaleObjectError+ exception if cannot delete a
     # model.
     #
+    # Raises +Dynamoid::Errors::MissingHashKey+ if a partition key has value
+    # +nil+ and raises +Dynamoid::Errors::MissingRangeKey+ if a sort key is
+    # required but has value +nil+.
+    #
     # @return [Dynamoid::Document] self
     # @since 0.2.0
     def delete
+      raise Dynamoid::Errors::MissingHashKey if hash_key.nil?
+      raise Dynamoid::Errors::MissingRangeKey if self.class.range_key? && range_value.nil?
+
       options = range_key ? { range_key: Dumping.dump_field(read_attribute(range_key), self.class.attributes[range_key]) } : {}
+      partition_key_dumped = Dumping.dump_field(hash_key, self.class.attributes[self.class.hash_key])
 
       # Add an optimistic locking check if the lock_version column exists
       if self.class.attributes[:lock_version]
@@ -922,7 +1078,7 @@ module Dynamoid
 
       @destroyed = true
 
-      Dynamoid.adapter.delete(self.class.table_name, hash_key, options)
+      Dynamoid.adapter.delete(self.class.table_name, partition_key_dumped, options)
 
       self.class.associations.each_key do |name|
         send(name).disassociate_source

data/lib/dynamoid/transaction_read/find.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Dynamoid
+  class TransactionRead
+    class Find
+      attr_reader :model_class
+
+      def initialize(model_class, *ids, **options)
+        @model_class = model_class
+        @ids = ids
+        @options = options
+      end
+
+      def on_registration
+        validate_primary_key!
+      end
+
+      def observable_by_user_result
+        nil
+      end
+
+      def action_request
+        if single_key_given?
+          action_request_for_single_key
+        else
+          action_request_for_multiple_keys
+        end
+      end
+
+      def process_responses(responses)
+        models = responses.map do |response|
+          if response.item
+            @model_class.from_database(response.item)
+          elsif @options[:raise_error] == false
+            nil
+          else
+            message = build_record_not_found_exception_message(responses)
+            raise Dynamoid::Errors::RecordNotFound, message
+          end
+        end
+
+        unless single_key_given?
+          models.compact!
+        end
+
+        models.each { |m| m&.run_callbacks :find }
+        models
+      end
+
+      private
+
+      def single_key_given?
+        @ids.size == 1 && !@ids[0].is_a?(Array)
+      end
+
+      def validate_primary_key!
+        if single_key_given?
+          partition_key = @ids[0]
+          sort_key = @options[:range_key]
+
+          raise Dynamoid::Errors::MissingHashKey if partition_key.nil?
+          raise Dynamoid::Errors::MissingRangeKey if @model_class.range_key && sort_key.nil?
+        else
+          ids = @ids.flatten(1)
+
+          raise Dynamoid::Errors::MissingHashKey if ids.any? { |pk, _sk| pk.nil? }
+          raise Errors::MissingRangeKey if @model_class.range_key && ids.any? { |_pk, sk| sk.nil? }
+        end
+      end
+
+      def action_request_for_single_key
+        partition_key = @ids[0]
+
+        key = { @model_class.hash_key => cast_and_dump_attribute(@model_class.hash_key, partition_key) }
+
+        if @model_class.range_key
+          sort_key = @options[:range_key]
+          key[@model_class.range_key] = cast_and_dump_attribute(@model_class.range_key, sort_key)
+        end
+
+        {
+          get: {
+            key: key,
+            table_name: @model_class.table_name
+          }
+        }
+      end
+
+      def action_request_for_multiple_keys
+        @ids.flatten(1).map do |id|
+          if @model_class.range_key
+            # expect [hash-key, range-key] pair
+            pk, sk = id
+            pk_dumped = cast_and_dump_attribute(@model_class.hash_key, pk)
+            sk_dumped = cast_and_dump_attribute(@model_class.range_key, sk)
+
+            key = { @model_class.hash_key => pk_dumped, @model_class.range_key => sk_dumped }
+          else
+            pk_dumped = cast_and_dump_attribute(@model_class.hash_key, id)
+
+            key = { @model_class.hash_key => pk_dumped }
+          end
+
+          {
+            get: {
+              key: key,
+              table_name: @model_class.table_name
+            }
+          }
+        end
+      end
+
+      def cast_and_dump_attribute(name, value)
+        attribute_options = @model_class.attributes[name]
+        casted_value = TypeCasting.cast_field(value, attribute_options)
+        Dumping.dump_field(casted_value, attribute_options)
+      end
+
+      def build_record_not_found_exception_message(responses)
+        items = responses.map(&:item)
+        ids = @ids.flatten(1)
+
+        if single_key_given?
+          id = ids[0]
+          primary_key = @model_class.range_key ? "(#{id.inspect},#{@options[:range_key].inspect})" : id.inspect
+          message = "Couldn't find #{@model_class.name} with primary key #{primary_key}"
+        else
+          ids_list = @model_class.range_key ? ids.map { |pk, sk| "(#{pk.inspect},#{sk.inspect})" } : ids.map(&:inspect)
+          message = "Couldn't find all #{@model_class.name.pluralize} with primary keys [#{ids_list.join(', ')}] "
+          message += "(found #{items.compact.size} results, but was looking for #{items.size})"
+        end
+
+        message
+      end
+    end
+  end
+end

data/lib/dynamoid/transaction_read.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'dynamoid/transaction_read/find'
+
+module Dynamoid
+  # The class +TransactionRead+ provides means to perform multiple reading
+  # operations in transaction, that is atomically, so that either all of them
+  # succeed, or all of them fail.
+  #
+  # The reading methods are supposed to be as close as possible to their
+  # non-transactional counterparts:
+  #
+  #   user_id = params[:user_id]
+  #   payment = params[:payment_id]
+  #
+  #   models = Dynamoid::TransactionRead.execute do |t|
+  #     t.find User, user_id
+  #     t.find Payment, payment_id
+  #   end
+  #
+  # The only difference is that the methods are called on a transaction
+  # instance and a model or a model class should be specified. So +User.find+
+  # becomes +t.find(user_id)+ and +Payment.find(payment_id)+ becomes +t.find
+  # Payment, payment_id+.
+  #
+  # A transaction can be used without a block. This way a transaction instance
+  # should be instantiated and committed manually with +#commit+ method:
+  #
+  #   t = Dynamoid::TransactionRead.new
+  #
+  #   t.find user_id
+  #   t.find payment_id
+  #
+  #   models = t.commit
+  #
+  #
+  # ### DynamoDB's transactions
+  #
+  # The main difference between DynamoDB transactions and a common interface is
+  # that DynamoDB's transactions are executed in batch. So in Dynamoid no
+  # data actually loaded when some transactional method (e.g+ `#find+) is
+  # called. All the changes are loaded at the end.
+  #
+  # A +TransactGetItems+ DynamoDB operation is used (see
+  # [documentation](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactGetItems.html)
+  # for details).
+  class TransactionRead
+    def self.execute
+      transaction = new
+
+      begin
+        yield transaction
+        transaction.commit
+      end
+    end
+
+    def initialize
+      @actions = []
+    end
+
+    # Load all the models.
+    #
+    #   transaction = Dynamoid::TransactionRead.new
+    #   # ...
+    #   transaction.commit
+    def commit
+      return [] if @actions.empty?
+
+      # some actions may produce multiple requests
+      action_request_groups = @actions.map(&:action_request).map do |action_request|
+        action_request.is_a?(Array) ? action_request : [action_request]
+      end
+      action_requests = action_request_groups.flatten(1)
+
+      return [] if action_requests.empty?
+
+      response = Dynamoid.adapter.transact_read_items(action_requests)
+
+      responses = response.responses.dup
+      @actions.zip(action_request_groups).map do |action, action_requests|
+        action_responses = responses.shift(action_requests.size)
+        action.process_responses(action_responses)
+      end.flatten
+    end
+
+    # Find one or many objects, specified by one id or an array of ids.
+    #
+    # By default it raises +RecordNotFound+ exception if at least one model
+    # isn't found. This behavior can be changed with +raise_error+ option. If
+    # specified +raise_error: false+ option then +find+ will not raise the
+    # exception.
+    #
+    # When a document schema includes range key it should always be specified
+    # in +find+ method call. In case it's missing +MissingRangeKey+ exception
+    # will be raised.
+    #
+    # Please note that there are the following differences between
+    # transactional and non-transactional +find+:
+    # - transactional +find+ preserves order of models in result when given multiple ids
+    # - transactional +find+ doesn't return results immediately, a single
+    #   collection with results of all the +find+ calls is returned instead
+    # - +:consistent_read+ option isn't supported
+    # - transactional +find+ is subject to limitations of the
+    #   [TransactGetItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactGetItems.html)
+    #   DynamoDB operation, e.g. the whole read transaction can load only up to 100 models.
+    #
+    # @param [Object|Array] ids a single primary key or an array of primary keys
+    # @param [Hash] options optional parameters of the operation
+    # @option options [Object] :range_key sort key of a model; required when a single partition key is given and a sort key is declared for a model
+    # @option options [true|false] :raise_error whether to raise a +RecordNotFound+ exception; specify explicitly +raise_error: false+ to suppress the exception; default is +true+
+    # @return [nil]
+    #
+    # @example Find by partition key
+    #   Dynamoid::TransactionRead.execute do |t|
+    #     t.find Document, 101
+    #   end
+    #
+    # @example Find by partition key and sort key
+    #   Dynamoid::TransactionRead.execute do |t|
+    #     t.find Document, 101, range_key: 'archived'
+    #   end
+    #
+    # @example Find several documents by partition key
+    #   Dynamoid::TransactionRead.execute do |t|
+    #     t.find Document, 101, 102, 103
+    #     t.find Document, [101, 102, 103]
+    #   end
+    #
+    # @example Find several documents by partition key and sort key
+    #   Dynamoid::TransactionRead.execute do |t|
+    #     t.find Document, [[101, 'archived'], [102, 'new'], [103, 'deleted']]
+    #   end
+    def find(model_class, *ids, **options)
+      action = Dynamoid::TransactionRead::Find.new(model_class, *ids, **options)
+      register_action action
+    end
+
+    private
+
+    def register_action(action)
+      @actions << action
+      action.on_registration
+      action.observable_by_user_result
+    end
+  end
+end