synamoid 1.2.1

data/lib/dynamoid/finders.rb

@@ -0,0 +1,199 @@
+# encoding: utf-8
+module Dynamoid
+
+  # This module defines the finder methods that hang off the document at the
+  # class level, like find, find_by_id, and the method_missing style finders.
+  module Finders
+    extend ActiveSupport::Concern
+
+    RANGE_MAP = {
+      'gt'            => :range_greater_than,
+      'lt'            => :range_less_than,
+      'gte'           => :range_gte,
+      'lte'           => :range_lte,
+      'begins_with'   => :range_begins_with,
+      'between'       => :range_between,
+      'eq'            => :range_eq
+    }
+
+    module ClassMethods
+
+      # Find one or many objects, specified by one id or an array of ids.
+      #
+      # @param [Array/String] *id an array of ids or one single id
+      #
+      # @return [Dynamoid::Document] one object or an array of objects, depending on whether the input was an array or not
+      #
+      # @since 0.2.0
+      def find(*ids)
+        options = if ids.last.is_a? Hash
+                    ids.slice!(-1)
+                  else
+                    {}
+                  end
+        expects_array = ids.first.kind_of?(Array)
+
+        ids = Array(ids.flatten.uniq)
+        if ids.count == 1
+          result = self.find_by_id(ids.first, options)
+          expects_array ? Array(result) : result
+        else
+          find_all(ids)
+        end
+      end
+
+      # Return objects found by the given array of ids, either hash keys, or hash/range key combinations using BatchGet.
+      # Returns empty array if no results found.
+      #
+      # @param [Array<ID>] ids
+      # @param [Hash] options: Passed to the underlying query.
+      #
+      # @example
+      #   find all the user with hash key
+      #   User.find_all(['1', '2', '3'])
+      #
+      #   find all the tweets using hash key and range key with consistent read
+      #   Tweet.find_all([['1', 'red'], ['1', 'green']], :consistent_read => true)
+      def find_all(ids, options = {})
+        items = Dynamoid.adapter.read(self.table_name, ids, options)
+        items ? items[self.table_name].map{|i| from_database(i)} : []
+      end
+
+      # Find one object directly by id.
+      #
+      # @param [String] id the id of the object to find
+      #
+      # @return [Dynamoid::Document] the found object, or nil if nothing was found
+      #
+      # @since 0.2.0
+      def find_by_id(id, options = {})
+        if item = Dynamoid.adapter.read(self.table_name, id, options)
+          from_database(item)
+        else
+          nil
+        end
+      end
+
+      # Find one object directly by hash and range keys
+      #
+      # @param [String] hash_key of the object to find
+      # @param [String/Number] range_key of the object to find
+      #
+      def find_by_composite_key(hash_key, range_key, options = {})
+        find_by_id(hash_key, options.merge({:range_key => range_key}))
+      end
+
+      # Find all objects by hash and range keys.
+      #
+      # @example find all ChamberTypes whose level is greater than 1
+      #   class ChamberType
+      #     include Dynamoid::Document
+      #     field :chamber_type,            :string
+      #     range :level,                   :integer
+      #     table :key => :chamber_type
+      #   end
+      #   ChamberType.find_all_by_composite_key('DustVault', range_greater_than: 1)
+      #
+      # @param [String] hash_key of the objects to find
+      # @param [Hash] options the options for the range key
+      # @option options [Range] :range_value find the range key within this range
+      # @option options [Number] :range_greater_than find range keys greater than this
+      # @option options [Number] :range_less_than find range keys less than this
+      # @option options [Number] :range_gte find range keys greater than or equal to this
+      # @option options [Number] :range_lte find range keys less than or equal to this
+      #
+      # @return [Array] an array of all matching items
+      #
+      def find_all_by_composite_key(hash_key, options = {})
+        Dynamoid.adapter.query(self.table_name, options.merge({hash_value: hash_key})).collect do |item|
+          from_database(item)
+        end
+      end
+
+      # Find all objects by using local secondary or global secondary index
+      #
+      # @example
+      #   class User
+      #     include Dynamoid::Document
+      #     field :email,          :string
+      #     field :age,            :integer
+      #     field :gender,         :string
+      #     field :rank            :number
+      #     table :key => :email
+      #     global_secondary_index :hash_key => :age, :range_key => :rank
+      #   end
+      #   # NOTE: the first param and the second param are both hashes,
+      #   #       so curly braces must be used on first hash param if sending both params
+      #   User.find_all_by_secondary_index({:age => 5}, :range => {"rank.lte" => 10})
+      #
+      # @param [Hash] eg: {:age => 5}
+      # @param [Hash] eg: {"rank.lte" => 10}
+      # @param [Hash] options - query filter, projected keys, scan_index_forward etc
+      # @return [Array] an array of all matching items
+      def find_all_by_secondary_index(hash, options = {})
+        range = options[:range] || {}
+        hash_key_field, hash_key_value = hash.first
+        range_key_field, range_key_value = range.first
+        range_op_mapped = nil
+
+        if range_key_field
+          range_key_field = range_key_field.to_s
+          range_key_op = "eq"
+          if range_key_field.include?(".")
+            range_key_field, range_key_op = range_key_field.split(".", 2)
+          end
+          range_op_mapped = RANGE_MAP.fetch(range_key_op)
+        end
+
+        # Find the index
+        index = self.find_index(hash_key_field, range_key_field)
+        raise Dynamoid::Errors::MissingIndex.new("attempted to find #{[hash_key_field, range_key_field]}") if index.nil?
+
+        # query
+        opts = {
+          :hash_key => hash_key_field.to_s,
+          :hash_value => hash_key_value,
+          :index_name => index.name,
+        }
+        if range_key_field
+          opts[:range_key] = range_key_field
+          opts[range_op_mapped] = range_key_value
+        end
+        dynamo_options = opts.merge(options.reject {|key, _| key == :range })
+        Dynamoid.adapter.query(self.table_name, dynamo_options).map do |item|
+          from_database(item)
+        end
+      end
+
+      # Find using exciting method_missing finders attributes. Uses criteria chains under the hood to accomplish this neatness.
+      #
+      # @example find a user by a first name
+      #   User.find_by_first_name('Josh')
+      #
+      # @example find all users by first and last name
+      #   User.find_all_by_first_name_and_last_name('Josh', 'Symonds')
+      #
+      # @return [Dynamoid::Document/Array] the found object, or an array of found objects if all was somewhere in the method
+      #
+      # @since 0.2.0
+      def method_missing(method, *args)
+        if method =~ /find/
+          finder = method.to_s.split('_by_').first
+          attributes = method.to_s.split('_by_').last.split('_and_')
+
+          chain = Dynamoid::Criteria::Chain.new(self)
+          chain.query = Hash.new.tap {|h| attributes.each_with_index {|attr, index| h[attr.to_sym] = args[index]}}
+
+          if finder =~ /all/
+            return chain.all
+          else
+            return chain.first
+          end
+        else
+          super
+        end
+      end
+    end
+  end
+
+end

data/lib/dynamoid/identity_map.rb

@@ -0,0 +1,92 @@
+module Dynamoid
+  module IdentityMap
+    extend ActiveSupport::Concern
+
+    def self.clear
+      Dynamoid.included_models.each { |m| m.identity_map.clear }
+    end
+
+    module ClassMethods
+      def identity_map
+        @identity_map ||= {}
+      end
+
+      def from_database(attrs = {})
+        return super if identity_map_off?
+
+        key = identity_map_key(attrs)
+        document = identity_map[key]
+
+        if document.nil?
+          document = super
+          identity_map[key] = document
+        else
+          document.load(attrs)
+        end
+
+        document
+      end
+
+      def find_by_id(id, options = {})
+        return super if identity_map_off?
+
+        key = id.to_s
+
+        if range_key = options[:range_key]
+          key += "::#{range_key}"
+        end
+
+        if identity_map[key]
+          identity_map[key]
+        else
+          super
+        end
+      end
+
+      def identity_map_key(attrs)
+        key = attrs[hash_key].to_s
+        if range_key
+          key += "::#{attrs[range_key]}"
+        end
+        key
+      end
+
+      def identity_map_on?
+        Dynamoid::Config.identity_map
+      end
+
+      def identity_map_off?
+        !identity_map_on?
+      end
+    end
+
+    def identity_map
+      self.class.identity_map
+    end
+
+    def save(*args)
+      return super if self.class.identity_map_off?
+
+      if result = super
+        identity_map[identity_map_key] = self
+      end
+      result
+    end
+
+    def delete
+      return super if self.class.identity_map_off?
+
+      identity_map.delete(identity_map_key)
+      super
+    end
+
+
+    def identity_map_key
+      key = hash_key.to_s
+      if self.class.range_key
+        key += "::#{range_value}"
+      end
+      key
+    end
+  end
+end

data/lib/dynamoid/indexes.rb

@@ -0,0 +1,273 @@
+module Dynamoid
+  module Indexes
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :local_secondary_indexes
+      class_attribute :global_secondary_indexes
+      self.local_secondary_indexes = {}
+      self.global_secondary_indexes = {}
+    end
+
+    module ClassMethods
+      # Defines a Global Secondary index on a table. Keys can be specified as
+      # hash-only, or hash & range.
+      #
+      # @param [Hash] options options to pass for this table
+      # @option options [Symbol] :name the name for the index; this still gets
+      #         namespaced.  If not specified, will use a default name.
+      # @option options [Symbol] :hash_key the index hash key column.
+      # @option options [Symbol] :range_key the index range key column (if
+      #         applicable).
+      # @option options [Symbol, Array<Symbol>] :projected_attributes table
+      #         attributes to project for this index. Can be :keys_only, :all
+      #         or an array of included fields. If not specified, defaults to
+      #         :keys_only.
+      # @option options [Integer] :read_capacity set the read capacity for the
+      #         index; does not work on existing indexes.
+      # @option options [Integer] :write_capacity set the write capacity for
+      #         the index; does not work on existing indexes.
+      def global_secondary_index(options={})
+        unless options.present?
+          raise Dynamoid::Errors::InvalidIndex.new('empty index definition')
+        end
+
+        unless options[:hash_key].present?
+          raise Dynamoid::Errors::InvalidIndex.new(
+            'A global secondary index requires a :hash_key to be specified'
+          )
+        end
+
+        index_opts = {
+            :read_capacity => Dynamoid::Config.read_capacity,
+            :write_capacity => Dynamoid::Config.write_capacity
+        }.merge(options)
+
+        index_opts[:dynamoid_class] = self
+        index_opts[:type] = :global_secondary
+
+        index = Dynamoid::Indexes::Index.new(index_opts)
+        gsi_key = index_key(options[:hash_key], options[:range_key])
+        self.global_secondary_indexes[gsi_key] = index
+        self
+      end
+
+
+      # Defines a local secondary index on a table. Will use the same primary
+      # hash key as the table.
+      #
+      # @param [Hash] options options to pass for this index.
+      # @option options [Symbol] :name the name for the index; this still gets
+      #         namespaced. If not specified, a name is automatically generated.
+      # @option options [Symbol] :range_key the range key column for the index.
+      # @option options [Symbol, Array<Symbol>] :projected_attributes table
+      #         attributes to project for this index. Can be :keys_only, :all
+      #         or an array of included fields. If not specified, defaults to
+      #         :keys_only.
+      def local_secondary_index(options={})
+        unless options.present?
+          raise Dynamoid::Errors::InvalidIndex.new('empty index definition')
+        end
+
+        primary_hash_key = self.hash_key
+        primary_range_key = self.range_key
+        index_range_key = options[:range_key]
+
+        unless index_range_key.present?
+          raise Dynamoid::Errors::InvalidIndex.new('A local secondary index '\
+            'requires a :range_key to be specified')
+        end
+
+        if primary_range_key.present? && index_range_key == primary_range_key
+          raise Dynamoid::Errors::InvalidIndex.new('A local secondary index'\
+            ' must use a different :range_key than the primary key')
+        end
+
+        index_opts = options.merge({
+          :dynamoid_class => self,
+          :type => :local_secondary,
+          :hash_key => primary_hash_key
+        })
+
+        index = Dynamoid::Indexes::Index.new(index_opts)
+        key = index_key(primary_hash_key, index_range_key)
+        self.local_secondary_indexes[key] = index
+        self
+      end
+
+
+      def find_index(hash, range=nil)
+        index = self.indexes[index_key(hash, range)]
+        index
+      end
+
+
+      # Returns true iff the provided hash[,range] key combo is a local
+      # secondary index.
+      #
+      # @param [Symbol] hash hash key name.
+      # @param [Symbol] range range key name.
+      # @return [Boolean] true iff provided keys correspond to a local
+      #         secondary index.
+      def is_local_secondary_index?(hash, range=nil)
+        self.local_secondary_indexes[index_key(hash, range)].present?
+      end
+
+
+      # Returns true iff the provided hash[,range] key combo is a global
+      # secondary index.
+      #
+      # @param [Symbol] hash hash key name.
+      # @param [Symbol] range range key name.
+      # @return [Boolean] true iff provided keys correspond to a global
+      #         secondary index.
+      def is_global_secondary_index?(hash, range=nil)
+        self.global_secondary_indexes[index_key(hash, range)].present?
+      end
+
+
+      # Generates a convenient lookup key name for a hash/range index.
+      # Should normally not be used directly.
+      #
+      # @param [Symbol] hash hash key name.
+      # @param [Symbol] range range key name.
+      # @return [String] returns "hash" if hash only, "hash_range" otherwise.
+      def index_key(hash, range=nil)
+        name = hash.to_s
+        if range.present?
+          name += "_#{range.to_s}"
+        end
+        name
+      end
+
+
+      # Generates a default index name.
+      #
+      # @param [Symbol] hash hash key name.
+      # @param [Symbol] range range key name.
+      # @return [String] index name of the form "table_name_index_index_key".
+      def index_name(hash, range=nil)
+        "#{self.table_name}_index_#{self.index_key(hash, range)}"
+      end
+
+
+      # Convenience method to return all indexes on the table.
+      #
+      # @return [Hash<String, Object>] the combined hash of global and local
+      #         secondary indexes.
+      def indexes
+        self.local_secondary_indexes.merge(self.global_secondary_indexes)
+      end
+
+      def indexed_hash_keys
+        self.global_secondary_indexes.map do |name, index|
+          index.hash_key.to_s
+        end
+      end
+    end
+
+
+    # Represents the attributes of a DynamoDB index.
+    class Index
+      include ActiveModel::Validations
+
+      PROJECTION_TYPES = [:keys_only, :all].to_set
+      DEFAULT_PROJECTION_TYPE = :keys_only
+
+      attr_accessor :name, :dynamoid_class, :type, :hash_key, :range_key,
+          :hash_key_schema, :range_key_schema, :projected_attributes,
+          :read_capacity, :write_capacity
+
+
+      validate do
+        validate_index_type
+        validate_hash_key
+        validate_range_key
+        validate_projected_attributes
+      end
+
+
+      def initialize(attrs={})
+        unless attrs[:dynamoid_class].present?
+          raise Dynamoid::Errors::InvalidIndex.new(':dynamoid_class is required')
+        end
+
+        @dynamoid_class = attrs[:dynamoid_class]
+        @type = attrs[:type]
+        @hash_key = attrs[:hash_key]
+        @range_key = attrs[:range_key]
+        @name = attrs[:name] || @dynamoid_class.index_name(@hash_key, @range_key)
+        @projected_attributes =
+            attrs[:projected_attributes] || DEFAULT_PROJECTION_TYPE
+        @read_capacity = attrs[:read_capacity]
+        @write_capacity = attrs[:write_capacity]
+
+        raise Dynamoid::Errors::InvalidIndex.new(self) unless self.valid?
+      end
+
+
+      # Convenience method to determine the projection type for an index.
+      # Projection types are: :keys_only, :all, :include.
+      #
+      # @return [Symbol] the projection type.
+      def projection_type
+        if @projected_attributes.is_a? Array
+          :include
+        else
+          @projected_attributes
+        end
+      end
+
+
+      private
+
+        def validate_projected_attributes
+          unless (@projected_attributes.is_a?(Array) ||
+                  PROJECTION_TYPES.include?(@projected_attributes))
+            errors.add(:projected_attributes, 'Invalid projected attributes specified.')
+          end
+        end
+
+        def validate_index_type
+          unless (@type.present? &&
+            [:local_secondary, :global_secondary].include?(@type))
+              errors.add(:type, 'Invalid index :type specified')
+          end
+        end
+
+        def validate_range_key
+          if @range_key.present?
+            range_field_attributes = @dynamoid_class.attributes[@range_key]
+            if range_field_attributes.present?
+              range_key_type = range_field_attributes[:type]
+              if Dynamoid::Fields::PERMITTED_KEY_TYPES.include?(range_key_type)
+                @range_key_schema = {
+                  @range_key => @dynamoid_class.dynamo_type(range_key_type)
+                }
+              else
+                errors.add(:range_key, 'Index :range_key is not a valid key type')
+              end
+            else
+              errors.add(:range_key, "No such field #{@range_key} defined on table")
+            end
+          end
+        end
+
+        def validate_hash_key
+          hash_field_attributes = @dynamoid_class.attributes[@hash_key]
+          if hash_field_attributes.present?
+            hash_field_type = hash_field_attributes[:type]
+            if Dynamoid::Fields::PERMITTED_KEY_TYPES.include?(hash_field_type)
+              @hash_key_schema = {
+                @hash_key => @dynamoid_class.dynamo_type(hash_field_type)
+              }
+            else
+              errors.add(:hash_key, 'Index :hash_key is not a valid key type')
+            end
+          else
+            errors.add(:hash_key, "No such field #{@hash_key} defined on table")
+          end
+        end
+    end
+  end
+end