dynamoid 3.5.0 → 3.6.0

data/lib/dynamoid/associations/association.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
-module Dynamoid #:nodoc:
+module Dynamoid
   # The base association module which all associations include. Every association has two very important components: the source and
   # the target. The source is the object which is calling the association information. It always has the target_ids inside of an attribute on itself.
   # The target is the object which is referencing by this association.
+  # @private
   module Associations
+    # @private
     module Association
       attr_accessor :name, :options, :source, :loaded
 
@@ -116,7 +118,7 @@ module Dynamoid #:nodoc:
 
       # Create a new instance of the target class without trying to add it to the association. This creates a base, that caller can update before setting or adding it.
       #
-      # @param [Hash] attribute hash for the new object
+      # @param attributes [Hash] attribute values for the new object
       #
       # @return [Dynamoid::Document] the newly-created object
       #

data/lib/dynamoid/associations/belongs_to.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
-module Dynamoid #:nodoc:
+module Dynamoid
   # The belongs_to association. For belongs_to, we reference only a single target instead of multiple records; that target is the
   # object to which the association object is associated.
   module Associations
+    # @private
     class BelongsTo
       include SingleAssociation
 

data/lib/dynamoid/associations/has_and_belongs_to_many.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
-module Dynamoid #:nodoc:
+module Dynamoid
   # The has and belongs to many association.
   module Associations
+    # @private
     class HasAndBelongsToMany
       include ManyAssociation
 

data/lib/dynamoid/associations/has_many.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
-module Dynamoid #:nodoc:
+module Dynamoid
   # The has_many association.
   module Associations
+    # @private
     class HasMany
       include ManyAssociation
 

data/lib/dynamoid/associations/has_one.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
-module Dynamoid #:nodoc:
+module Dynamoid
   # The HasOne association.
   module Associations
+    # @private
     class HasOne
       include Association
       include SingleAssociation

data/lib/dynamoid/associations/many_association.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Dynamoid #:nodoc:
+module Dynamoid
   module Associations
     module ManyAssociation
       include Association
@@ -13,6 +13,8 @@ module Dynamoid #:nodoc:
       end
 
       include Enumerable
+
+      # @private
       # Delegate methods to the records the association represents.
       delegate :first, :last, :empty?, :size, :class, to: :records
 
@@ -20,11 +22,13 @@ module Dynamoid #:nodoc:
       #
       # @return the association records; depending on which association this is, either a single instance or an array
       #
+      # @private
       # @since 0.2.0
       def find_target
         Array(target_class.find(source_ids.to_a))
       end
 
+      # @private
       def records
         if query.empty?
           target
@@ -43,13 +47,20 @@ module Dynamoid #:nodoc:
         records.include?(object)
       end
 
-      # Deletes an object or array of objects from the association. This removes their records from the association field on the source,
-      # and attempts to remove the source from the target association if it is detected to exist.
+      # Delete an object or array of objects from the association.
+      #
+      #   tag.posts.delete(post)
+      #   tag.posts.delete([post1, post2, post3])
       #
-      # @param [Dynamoid::Document] object the object (or array of objects) to remove from the association
+      # This removes their records from the association field on the source,
+      # and attempts to remove the source from the target association if it is
+      # detected to exist.
       #
-      # @return [Dynamoid::Document] the deleted object
+      # It saves both models immediately - the source model and the target one
+      # so any not saved changes will be saved as well.
       #
+      # @param object [Dynamoid::Document|Array] model (or array of models) to remove from the association
+      # @return [Dynamoid::Document|Array] the deleted model
       # @since 0.2.0
       def delete(object)
         disassociate(Array(object).collect(&:hash_key))
@@ -59,13 +70,19 @@ module Dynamoid #:nodoc:
         object
       end
 
-      # Add an object or array of objects to an association. This preserves the current records in the association (if any)
-      # and adds the object to the target association if it is detected to exist.
+      # Add an object or array of objects to an association.
       #
-      # @param [Dynamoid::Document] object the object (or array of objects) to add to the association
+      #   tag.posts << post
+      #   tag.posts << [post1, post2, post3]
+      #
+      # This preserves the current records in the association (if any) and adds
+      # the object to the target association if it is detected to exist.
       #
-      # @return [Dynamoid::Document] the added object
+      # It saves both models immediately - the source model and the target one
+      # so any not saved changes will be saved as well.
       #
+      # @param object [Dynamoid::Document|Array] model (or array of models) to add to the association
+      # @return [Dynamoid::Document] the added model
       # @since 0.2.0
       def <<(object)
         associate(Array(object).collect(&:hash_key))
@@ -82,8 +99,9 @@ module Dynamoid #:nodoc:
       #
       # @param [Dynamoid::Document] object the object (or array of objects) to add to the association
       #
-      # @return [Dynamoid::Document] the added object
+      # @return [Dynamoid::Document|Array] the added object
       #
+      # @private
       # @since 0.2.0
       def setter(object)
         target.each { |o| delete(o) }
@@ -91,23 +109,37 @@ module Dynamoid #:nodoc:
         object
       end
 
-      # Create a new instance of the target class and add it directly to the association. If the create fails an exception will be raised.
+      # Create a new instance of the target class, persist it and add directly
+      # to the association.
       #
-      # @param [Hash] attribute hash for the new object
+      #   tag.posts.create!(title: 'foo')
       #
-      # @return [Dynamoid::Document] the newly-created object
+      # Several models can be created at once when an array of attributes
+      # specified:
+      #
+      #   tag.posts.create!([{ title: 'foo' }, {title: 'bar'} ])
+      #
+      # If the creation fails an exception will be raised.
       #
+      # @param attributes [Hash] attribute values for the new object
+      # @return [Dynamoid::Document|Array] the newly-created object
       # @since 0.2.0
       def create!(attributes = {})
         self << target_class.create!(attributes)
       end
 
-      # Create a new instance of the target class and add it directly to the association.
+      # Create a new instance of the target class, persist it and add directly
+      # to the association.
       #
-      # @param [Hash] attribute hash for the new object
+      #   tag.posts.create(title: 'foo')
       #
-      # @return [Dynamoid::Document] the newly-created object
+      # Several models can be created at once when an array of attributes
+      # specified:
+      #
+      #   tag.posts.create([{ title: 'foo' }, {title: 'bar'} ])
       #
+      # @param attributes [Hash] attribute values for the new object
+      # @return [Dynamoid::Document|Array] the newly-created object
       # @since 0.2.0
       def create(attributes = {})
         self << target_class.create(attributes)
@@ -115,16 +147,18 @@ module Dynamoid #:nodoc:
 
       # Create a new instance of the target class and add it directly to the association. If the create fails an exception will be raised.
       #
-      # @param [Hash] attribute hash for the new object
-      #
       # @return [Dynamoid::Document] the newly-created object
       #
+      # @private
       # @since 0.2.0
       def each(&block)
         records.each(&block)
       end
 
-      # Destroys all members of the association and removes them from the association.
+      # Destroys all members of the association and removes them from the
+      # association.
+      #
+      #   tag.posts.destroy_all
       #
       # @since 0.2.0
       def destroy_all
@@ -133,7 +167,10 @@ module Dynamoid #:nodoc:
         objs.each(&:destroy)
       end
 
-      # Deletes all members of the association and removes them from the association.
+      # Deletes all members of the association and removes them from the
+      # association.
+      #
+      #   tag.posts.delete_all
       #
       # @since 0.2.0
       def delete_all
@@ -144,10 +181,13 @@ module Dynamoid #:nodoc:
 
       # Naive association filtering.
       #
-      # @param [Hash] A hash of attributes; each must match every returned object's attribute exactly.
+      #   tag.posts.where(title: 'foo')
       #
-      # @return [Dynamoid::Association] the association this method was called on (for chaining purposes)
+      # It loads lazily all the associated models and checks provided
+      # conditions. That's why only equality conditions can be specified.
       #
+      # @param args [Hash] A hash of attributes; each must match every returned object's attribute exactly.
+      # @return [Dynamoid::Association] the association this method was called on (for chaining purposes)
       # @since 0.2.0
       def where(args)
         filtered = clone
@@ -167,6 +207,7 @@ module Dynamoid #:nodoc:
 
       # Delegate methods we don't find directly to the records array.
       #
+      # @private
       # @since 0.2.0
       def method_missing(method, *args)
         if records.respond_to?(method)
@@ -176,10 +217,12 @@ module Dynamoid #:nodoc:
         end
       end
 
+      # @private
       def associate(hash_key)
         source.update_attribute(source_attribute, source_ids.merge(Array(hash_key)))
       end
 
+      # @private
       def disassociate(hash_key)
         source.update_attribute(source_attribute, source_ids - Array(hash_key))
       end

data/lib/dynamoid/associations/single_association.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
-module Dynamoid #:nodoc:
+module Dynamoid
   module Associations
     module SingleAssociation
       include Association
 
       delegate :class, to: :target
 
+      # @private
       def setter(object)
         if object.nil?
           delete
@@ -19,16 +20,37 @@ module Dynamoid #:nodoc:
         object
       end
 
+      # Delete a model from the association.
+      #
+      #   post.logo.delete # => nil
+      #
+      # Saves both models immediately - a source model and a target one so any
+      # unsaved changes will be saved. Doesn't delete an associated model from
+      # DynamoDB.
       def delete
         target.send(target_association).disassociate(source.hash_key) if target && target_association
         disassociate
         target
       end
 
+      # Create a new instance of the target class, persist it and associate.
+      #
+      #   post.logo.create!(hight: 50, width: 90)
+      #
+      # If the creation fails an exception will be raised.
+      #
+      # @param attributes [Hash] attributes of a model to create
+      # @return [Dynamoid::Document] created model
       def create!(attributes = {})
         setter(target_class.create!(attributes))
       end
 
+      # Create a new instance of the target class, persist it and associate.
+      #
+      #   post.logo.create(hight: 50, width: 90)
+      #
+      # @param attributes [Hash] attributes of a model to create
+      # @return [Dynamoid::Document] created model
       def create(attributes = {})
         setter(target_class.create(attributes))
       end
@@ -44,6 +66,7 @@ module Dynamoid #:nodoc:
 
       # Delegate methods we don't find directly to the target.
       #
+      # @private
       # @since 0.2.0
       def method_missing(method, *args)
         if target.respond_to?(method)
@@ -53,21 +76,25 @@ module Dynamoid #:nodoc:
         end
       end
 
+      # @private
       def nil?
         target.nil?
       end
 
+      # @private
       def empty?
         # This is needed to that ActiveSupport's #blank? and #present?
         # methods work as expected for SingleAssociations.
         target.nil?
       end
 
+      # @private
       def associate(hash_key)
         target.send(target_association).disassociate(source.hash_key) if target && target_association
         source.update_attribute(source_attribute, Set[hash_key])
       end
 
+      # @private
       def disassociate(_hash_key = nil)
         source.update_attribute(source_attribute, nil)
       end

data/lib/dynamoid/components.rb

@@ -3,6 +3,7 @@
 module Dynamoid
   # All modules that a Document is composed of are defined in this
   # module, to keep the document class from getting too cluttered.
+  # @private
   module Components
     extend ActiveSupport::Concern
 

data/lib/dynamoid/config.rb

@@ -2,13 +2,13 @@
 
 require 'uri'
 require 'logger'
-require 'null_logger'
 require 'dynamoid/config/options'
 require 'dynamoid/config/backoff_strategies/constant_backoff'
 require 'dynamoid/config/backoff_strategies/exponential_backoff'
 
 module Dynamoid
   # Contains all the basic configuration information required for Dynamoid: both sensible defaults and required fields.
+  # @private
   module Config
     # @since 3.3.1
     DEFAULT_NAMESPACE = if defined?(Rails)
@@ -54,6 +54,7 @@ module Dynamoid
       constant: BackoffStrategies::ConstantBackoff,
       exponential: BackoffStrategies::ExponentialBackoff
     }
+    option :log_formatter, default: nil
     option :http_continue_timeout, default: nil # specify if you'd like to overwrite Aws Configure - default: 1
     option :http_idle_timeout, default: nil     #                                                  - default: 5
     option :http_open_timeout, default: nil     #                                                  - default: 15
@@ -78,7 +79,7 @@ module Dynamoid
     # @since 0.2.0
     def logger=(logger)
       case logger
-      when false, nil then @logger = NullLogger.new
+      when false, nil then @logger = ::Logger.new(nil)
       when true then @logger = default_logger
       else
         @logger = logger if logger.respond_to?(:info)

data/lib/dynamoid/config/backoff_strategies/constant_backoff.rb

@@ -2,6 +2,7 @@
 
 module Dynamoid
   module Config
+    # @private
     module BackoffStrategies
       class ConstantBackoff
         def self.call(sec = 1)

data/lib/dynamoid/config/backoff_strategies/exponential_backoff.rb

@@ -2,6 +2,7 @@
 
 module Dynamoid
   module Config
+    # @private
     module BackoffStrategies
       # Truncated binary exponential backoff algorithm
       # See https://en.wikipedia.org/wiki/Exponential_backoff

data/lib/dynamoid/config/options.rb

@@ -4,6 +4,7 @@
 module Dynamoid
   module Config
     # Encapsulates logic for setting options.
+    # @private
     module Options
       # Get the defaults or initialize a new empty hash.
       #

data/lib/dynamoid/criteria.rb

@@ -7,6 +7,7 @@ module Dynamoid
   module Criteria
     extend ActiveSupport::Concern
 
+    # @private
     module ClassMethods
       %i[where all first last each record_limit scan_limit batch start scan_index_forward find_by_pages project pluck].each do |meth|
         # Return a criteria chain in response to a method that will begin or end a chain. For more information,

data/lib/dynamoid/criteria/chain.rb

@@ -22,26 +22,74 @@ module Dynamoid
         @consistent_read = false
         @scan_index_forward = true
 
-        # Honor STI and :type field if it presents
-        type = @source.inheritance_field
-        if @source.attributes.key?(type)
-          @query[:"#{type}.in"] = @source.deep_subclasses.map(&:name) << @source.name
-        end
-
         # we should re-initialize keys detector every time we change query
         @key_fields_detector = KeyFieldsDetector.new(@query, @source)
       end
 
-      # The workhorse method of the criteria chain. Each key in the passed in hash will become another criteria that the
-      # ultimate query must match. A key can either be a symbol or a string, and should be an attribute name or
-      # an attribute name with a range operator.
+      # Returns a chain which is a result of filtering current chain with the specified conditions.
+      #
+      # It accepts conditions in the form of a hash.
+      #
+      #   Post.where(links_count: 2)
+      #
+      # A key could be either string or symbol.
+      #
+      # In order to express conditions other than equality predicates could be used.
+      # Predicate should be added to an attribute name to form a key +'created_at.gt' => Date.yesterday+
+      #
+      # Currently supported following predicates:
+      # - +gt+ - greater than
+      # - +gte+ - greater or equal
+      # - +lt+ - less than
+      # - +lte+ - less or equal
+      # - +ne+ - not equal
+      # - +between+ - an attribute value is greater than the first value and less than the second value
+      # - +in+ - check an attribute in a list of values
+      # - +begins_with+ - check for a prefix in string
+      # - +contains+ - check substring or value in a set or array
+      # - +not_contains+ - check for absence of substring or a value in set or array
+      # - +null+ - attribute doesn't exists in an item
+      # - +not_null+ - attribute exists in an item
+      #
+      # All the predicates match operators supported by DynamoDB's
+      # {ComparisonOperator}[https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Condition.html#DDB-Type-Condition-ComparisonOperator]
+      #
+      #   Post.where('size.gt' => 1000)
+      #   Post.where('size.gte' => 1000)
+      #   Post.where('size.lt' => 35000)
+      #   Post.where('size.lte' => 35000)
+      #   Post.where('author.ne' => 'John Doe')
+      #   Post.where('created_at.between' => [Time.now - 3600, Time.now])
+      #   Post.where('category.in' => ['tech', 'fashion'])
+      #   Post.where('title.begins_with' => 'How long')
+      #   Post.where('tags.contains' => 'Ruby')
+      #   Post.where('tags.not_contains' => 'Ruby on Rails')
+      #   Post.where('legacy_attribute.null' => true)
+      #   Post.where('optional_attribute.not_null' => true)
+      #
+      # There are some limitations for a sort key. Only following predicates
+      # are supported - +gt+, +gte+, +lt+, +lte+, +between+, +begins_with+.
+      #
+      # +where+ without argument will return the current chain.
+      #
+      # Multiple calls can be chained together and conditions will be merged:
+      #
+      #   Post.where('size.gt' => 1000).where('title' => 'some title')
       #
-      # @example A simple criteria
-      #   where(:name => 'Josh')
+      # It's equivalent to:
       #
-      # @example A more complicated criteria
-      #   where(:name => 'Josh', 'created_at.gt' => DateTime.now - 1.day)
+      #   Post.where('size.gt' => 1000, 'title' => 'some title')
       #
+      # But only one condition can be specified for a certain attribute. The
+      # last specified condition will override all the others. Only condition
+      # 'size.lt' => 200 will be used in following examples:
+      #
+      #   Post.where('size.gt' => 100, 'size.lt' => 200)
+      #   Post.where('size.gt' => 100).where('size.lt' => 200)
+      #
+      # Internally +where+ performs either +Scan+ or +Query+ operation.
+      #
+      # @return [Dynamoid::Criteria::Chain]
       # @since 0.2.0
       def where(args)
         detector = IgnoredConditionsDetector.new(args)
@@ -67,6 +115,13 @@ module Dynamoid
         self
       end
 
+      # Turns on strongly consistent reads.
+      #
+      # By default reads are eventually consistent.
+      #
+      #   Post.where('size.gt' => 1000).consistent
+      #
+      # @return [Dynamoid::Criteria::Chain]
       def consistent
         @consistent_read = true
         self
@@ -74,11 +129,39 @@ module Dynamoid
 
       # Returns all the records matching the criteria.
       #
+      # Since +where+ and most of the other methods return a +Chain+
+      # the only way to get a result as a collection is to call the +all+
+      # method. It returns +Enumerator+ which could be used directly or
+      # transformed into +Array+
+      #
+      #   Post.all                            # => Enumerator
+      #   Post.where(links_count: 2).all      # => Enumerator
+      #   Post.where(links_count: 2).all.to_a # => Array
+      #
+      # When the result set is too large DynamoDB divides it into separate
+      # pages.  While an enumerator iterates over the result models each page
+      # is loaded lazily. So even an extra large result set can be loaded and
+      # processed with considerably small memory footprint and throughput
+      # consumption.
+      #
+      # @return [Enumerator::Lazy]
       # @since 0.2.0
       def all
         records
       end
 
+      # Returns the actual number of items in a table matching the criteria.
+      #
+      #   Post.where(links_count: 2).count
+      #
+      # Internally it uses either `Scan` or `Query` DynamoDB's operation so it
+      # costs like all the matching items were read from a table.
+      #
+      # The only difference is that items are read by DynemoDB but not actually
+      # loaded on the client side. DynamoDB returns only count of items after
+      # filtering.
+      #
+      # @return [Integer]
       def count
         if @key_fields_detector.key_present?
           count_via_query
@@ -87,16 +170,61 @@ module Dynamoid
         end
       end
 
-      # Returns the last fetched record matched the criteria
-      # Enumerable doesn't implement `last`, only `first`
-      # So we have to implement it ourselves
+      # Returns the first item matching the criteria.
+      #
+      #   Post.where(links_count: 2).first
+      #
+      # Applies `record_limit(1)` to ensure only a single record is fetched
+      # when no non-key conditions are present and `scan_limit(1)` when no
+      # conditions are present at all.
+      #
+      # If used without criteria it just returns the first item of some
+      # arbitrary order.
+      #
+      #   Post.first
+      #
+      # @return [Model|nil]
+      def first(*args)
+        n = args.first || 1
+
+        return scan_limit(n).to_a.first(*args) if @query.blank?
+        return super if @key_fields_detector.non_key_present?
+
+        record_limit(n).to_a.first(*args)
+      end
+
+      # Returns the last item matching the criteria.
+      #
+      #   Post.where(links_count: 2).last
       #
+      # DynamoDB doesn't support ordering by some arbitrary attribute except a
+      # sort key. So this method is mostly useful during development and
+      # testing.
+      #
+      # If used without criteria it just returns the last item of some arbitrary order.
+      #
+      #   Post.last
+      #
+      # It isn't efficient from the performance point of view as far as it reads and
+      # loads all the filtered items from DynamoDB.
+      #
+      # @return [Model|nil]
       def last
         all.to_a.last
       end
 
-      # Destroys all the records matching the criteria.
+      # Deletes all the items matching the criteria.
       #
+      #   Post.where(links_count: 2).delete_all
+      #
+      # If called without criteria then it deletes all the items in a table.
+      #
+      #   Post.delete_all
+      #
+      # It loads all the items either with +Scan+ or +Query+ operation and
+      # deletes them in batch with +BatchWriteItem+ operation. +BatchWriteItem+
+      # is limited by request size and items count so it's quite possible the
+      # deletion will require several +BatchWriteItem+ calls.
       def delete_all
         ids = []
         ranges = []
@@ -117,53 +245,215 @@ module Dynamoid
       end
       alias destroy_all delete_all
 
-      # The record limit is the limit of evaluated records returned by the
-      # query or scan.
+      # Set the record limit.
+      #
+      # The record limit is the limit of evaluated items returned by the
+      # +Query+ or +Scan+. In other words it's how many items should be
+      # returned in response.
+      #
+      #   Post.where(links_count: 2).record_limit(1000) # => 1000 models
+      #   Post.record_limit(1000)                       # => 1000 models
+      #
+      # It could be very inefficient in terms of HTTP requests in pathological
+      # cases. DynamoDB doesn't support out of the box the limits for items
+      # count after filtering. So it's possible to make a lot of HTTP requests
+      # to find items matching criteria and skip not matching. It means that
+      # the cost (read capacity units) is unpredictable.
+      #
+      # Because of such issues with performance and cost it's mostly useful in
+      # development and testing.
+      #
+      # When called without criteria it works like +scan_limit+.
+      #
+      # @return [Dynamoid::Criteria::Chain]
       def record_limit(limit)
         @record_limit = limit
         self
       end
 
-      # The scan limit which is the limit of records that DynamoDB will
-      # internally query or scan. This is different from the record limit
-      # as with filtering DynamoDB may look at N scanned records but return 0
-      # records if none pass the filter.
+      # Set the scan limit.
+      #
+      # The scan limit is the limit of records that DynamoDB will internally
+      # read with +Query+ or +Scan+. It's different from the record limit as
+      # with filtering DynamoDB may look at N scanned items but return 0
+      # items if none passes the filter. So it can return less items than was
+      # specified with the limit.
+      #
+      #   Post.where(links_count: 2).scan_limit(1000)   # => 850 models
+      #   Post.scan_limit(1000)                         # => 1000 models
+      #
+      # By contrast with +record_limit+ the cost (read capacity units) and
+      # performance is predictable.
+      #
+      # When called without criteria it works like +record_limit+.
+      #
+      # @return [Dynamoid::Criteria::Chain]
       def scan_limit(limit)
         @scan_limit = limit
         self
       end
 
+      # Set the batch size.
+      #
+      # The batch size is a number of items which will be lazily loaded one by one.
+      # When the batch size is set then items will be loaded batch by batch of
+      # the specified size instead of relying on the default paging mechanism
+      # of DynamoDB.
+      #
+      #   Post.where(links_count: 2).batch(1000).all.each do |post|
+      #     # process a post
+      #   end
+      #
+      # It's useful to limit memory usage or throughput consumption
+      #
+      # @return [Dynamoid::Criteria::Chain]
       def batch(batch_size)
         @batch_size = batch_size
         self
       end
 
+      # Set the start item.
+      #
+      # When the start item is set the items will be loaded starting right
+      # after the specified item.
+      #
+      #   Post.where(links_count: 2).start(post)
+      #
+      # It can be used to implement an own pagination mechanism.
+      #
+      #   Post.where(author_id: author_id).start(last_post).scan_limit(50)
+      #
+      # The specified start item will not be returned back in a result set.
+      #
+      # Actually it doesn't need all the item attributes to start - an item may
+      # have only the primary key attributes (partition and sort key if it's
+      # declared).
+      #
+      #   Post.where(links_count: 2).start(Post.new(id: id))
+      #
+      # It also supports a +Hash+ argument with the keys attributes - a
+      # partition key and a sort key (if it's declared).
+      #
+      #   Post.where(links_count: 2).start(id: id)
+      #
+      # @return [Dynamoid::Criteria::Chain]
       def start(start)
         @start = start
         self
       end
 
+      # Reverse the sort order.
+      #
+      # By default the sort order is ascending (by the sort key value). Set a
+      # +false+ value to reverse the order.
+      #
+      #   Post.where(id: id, 'views_count.gt' => 1000).scan_index_forward(false)
+      #
+      # It works only for queries with a partition key condition e.g. +id:
+      # 'some-id'+ which internally performs +Query+ operation.
+      #
+      # @return [Dynamoid::Criteria::Chain]
       def scan_index_forward(scan_index_forward)
         @scan_index_forward = scan_index_forward
         self
       end
 
-      # Allows you to use the results of a search as an enumerable over the results found.
+      # Allows to use the results of a search as an enumerable over the results
+      # found.
+      #
+      #   Post.each do |post|
+      #   end
+      #
+      #   Post.all.each do |post|
+      #   end
+      #
+      #   Post.where(links_count: 2).each do |post|
+      #   end
+      #
+      # It works similar to the +all+ method so results are loaded lazily.
       #
       # @since 0.2.0
       def each(&block)
         records.each(&block)
       end
 
+      # Iterates over the pages returned by DynamoDB.
+      #
+      # DynamoDB has its own paging machanism and divides a large result set
+      # into separate pages. The +find_by_pages+ method provides access to
+      # these native DynamoDB pages.
+      #
+      # The pages are loaded lazily.
+      #
+      #   Post.where('views_count.gt' => 1000).find_by_pages do |posts, options|
+      #     # process posts
+      #   end
+      #
+      # It passes as block argument an +Array+ of models and a Hash with options.
+      #
+      # Options +Hash+ contains only one option +:last_evaluated_key+. The last
+      # evaluated key is a Hash with key attributes of the last item processed by
+      # DynamoDB. It can be used to resume querying using the +start+ method.
+      #
+      #   posts, options = Post.where('views_count.gt' => 1000).find_by_pages.first
+      #   last_key = options[:last_evaluated_key]
+      #
+      #   # ...
+      #
+      #   Post.where('views_count.gt' => 1000).start(last_key).find_by_pages do |posts, options|
+      #   end
+      #
+      # If it's called without a block then it returns an +Enumerator+.
+      #
+      #   enum = Post.where('views_count.gt' => 1000).find_by_pages
+      #
+      #   enum.each do |posts, options|
+      #     # process posts
+      #   end
+      #
+      # @return [Enumerator::Lazy]
       def find_by_pages(&block)
         pages.each(&block)
       end
 
+      # Select only specified fields.
+      #
+      # It takes one or more field names and returns a collection of models with only
+      # these fields set.
+      #
+      #   Post.where('views_count.gt' => 1000).select(:title)
+      #   Post.where('views_count.gt' => 1000).select(:title, :created_at)
+      #   Post.select(:id)
+      #
+      # It can be used to avoid loading large field values and to decrease a
+      # memory footprint.
+      #
+      # @return [Dynamoid::Criteria::Chain]
       def project(*fields)
         @project = fields.map(&:to_sym)
         self
       end
 
+      # Select only specified fields.
+      #
+      # It takes one or more field names and returns an array of either values
+      # or arrays of values.
+      #
+      #   Post.pluck(:id)                   # => ['1', '2']
+      #   Post.pluck(:title, :title)        # => [['1', 'Title #1'], ['2', 'Title#2']]
+      #
+      #   Post.where('views_count.gt' => 1000).pluck(:title)
+      #
+      # There are some differences between +pluck+ and +project+. +pluck+
+      # - doesn't instantiate models
+      # - it isn't chainable and returns +Array+ instead of +Chain+
+      #
+      # It deserializes values if a field type isn't supported by DynamoDB natively.
+      #
+      # It can be used to avoid loading large field values and to decrease a
+      # memory footprint.
+      #
+      # @return [Array]
       def pluck(*args)
         fields = args.map(&:to_sym)
         @project = fields
@@ -325,6 +615,13 @@ module Dynamoid
 
       def range_query
         opts = {}
+        query = self.query
+
+        # Honor STI and :type field if it presents
+        if @source.attributes.key?(@source.inheritance_field) &&
+           @key_fields_detector.hash_key.to_sym != @source.inheritance_field.to_sym
+          query.update(sti_condition)
+        end
 
         # Add hash key
         opts[:hash_key] = @key_fields_detector.hash_key
@@ -332,15 +629,7 @@ module Dynamoid
 
         # Add range key
         if @key_fields_detector.range_key
-          opts[:range_key] = @key_fields_detector.range_key
-          if query[@key_fields_detector.range_key].present?
-            value = type_cast_condition_parameter(@key_fields_detector.range_key, query[@key_fields_detector.range_key])
-            opts.update(range_eq: value)
-          end
-
-          query.keys.select { |k| k.to_s =~ /^#{@key_fields_detector.range_key}\./ }.each do |key|
-            opts.merge!(range_hash(key))
-          end
+          add_range_key_to_range_query(query, opts)
         end
 
         (query.keys.map(&:to_sym) - [@key_fields_detector.hash_key.to_sym, @key_fields_detector.range_key.try(:to_sym)])
@@ -357,6 +646,18 @@ module Dynamoid
         opts.merge(query_opts).merge(consistent_opts)
       end
 
+      def add_range_key_to_range_query(query, opts)
+        opts[:range_key] = @key_fields_detector.range_key
+        if query[@key_fields_detector.range_key].present?
+          value = type_cast_condition_parameter(@key_fields_detector.range_key, query[@key_fields_detector.range_key])
+          opts.update(range_eq: value)
+        end
+
+        query.keys.select { |k| k.to_s =~ /^#{@key_fields_detector.range_key}\./ }.each do |key|
+          opts.merge!(range_hash(key))
+        end
+      end
+
       # TODO: casting should be operator aware
       # e.g. for NULL operator value should be boolean
       # and isn't related to an attribute own type
@@ -418,6 +719,13 @@ module Dynamoid
       end
 
       def scan_query
+        query = self.query
+
+        # Honor STI and :type field if it presents
+        if sti_condition
+          query.update(sti_condition)
+        end
+
         {}.tap do |opts|
           query.keys.map(&:to_sym).each do |key|
             if key.to_s.include?('.')
@@ -440,6 +748,18 @@ module Dynamoid
         opts[:project] = @project
         opts
       end
+
+      def sti_condition
+        condition = {}
+        type = @source.inheritance_field
+
+        if @source.attributes.key?(type)
+          class_names = @source.deep_subclasses.map(&:name) << @source.name
+          condition[:"#{type}.in"] = class_names
+        end
+
+        condition
+      end
     end
   end
 end