aws-record 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: ded98837103b96b4599121d600cc139054de43637168121bae6a35302ba24ac8
-  data.tar.gz: 14c7d413a0b108fffd9c118aa05234b7e6d33852121e8b6828e88db6cadd45d7
+SHA1:
+  metadata.gz: c0d7d527489fd1a7848279570aefbe37aeee9297
+  data.tar.gz: f3234598e3f895c93184a7b283a7064853ad3707
 SHA512:
-  metadata.gz: 722b31cd37b441f33cc9993596b7fb92dc360bc280a00d9da9f03419a792669419bd9fa58006e59f09a027bde88444d795951902e3181aa697644a89baf09b17
-  data.tar.gz: bd7399265054c4483039e432fb4804713428151b3cef0f8e661132e9cf30d0c6876ed5611b09fcd6063c50b0f1baa31976cbfede27aba042457a9df3ac6cdffa
+  metadata.gz: afd2c0b89fac562aeaee2fb0f67f25cee31700b29639e52a8281babd769a45b8da8bf2cedf86d396904e1103b4f9e2722445a13bada7cab446c443b460b8e42b
+  data.tar.gz: f0dfc0620149bbf63d2b5334dc441f2370e220278a3893f5b84b1e68a6a74acfcfec9f36e67cb4d31696add5e4795a567a4444d4b05f685dcbfbe8dbfbe0df98

data/lib/aws-record.rb

@@ -28,6 +28,7 @@ require_relative 'aws-record/record/table_config'
 require_relative 'aws-record/record/table_migration'
 require_relative 'aws-record/record/version'
 require_relative 'aws-record/record/transactions'
+require_relative 'aws-record/record/buildable_search'
 require_relative 'aws-record/record/marshalers/string_marshaler'
 require_relative 'aws-record/record/marshalers/boolean_marshaler'
 require_relative 'aws-record/record/marshalers/integer_marshaler'

data/lib/aws-record/record/buildable_search.rb

@@ -0,0 +1,232 @@
+module Aws
+  module Record
+    class BuildableSearch
+      SUPPORTED_OPERATIONS = [:query, :scan]
+
+      # This should never be called directly, rather it is called by the
+      # #build_query or #build_scan methods of your aws-record model class.
+      def initialize(opts)
+        operation = opts[:operation]
+        model = opts[:model]
+        if SUPPORTED_OPERATIONS.include?(operation)
+          @operation = operation
+        else
+          raise ArgumentError.new("Unsupported operation: #{operation}")
+        end
+        @model = model
+        @params = {}
+        @next_name = "BUILDERA"
+        @next_value = "buildera"
+      end
+
+      # If you are querying or scanning on an index, you can specify it with
+      # this builder method. Provide the symbol of your index as defined on your
+      # model class.
+      def on_index(index)
+        @params[:index_name] = index
+        self
+      end
+
+      # If true, will perform your query or scan as a consistent read. If false,
+      # the query or scan is eventually consistent.
+      def consistent_read(b)
+        @params[:consistent_read] = b
+        self
+      end
+
+      # For the scan operation, you can split your scan into multiple segments
+      # to be scanned in parallel. If you wish to do this, you can use this
+      # builder method to provide the :total_segments of your parallel scan and
+      # the :segment number of this scan.
+      def parallel_scan(opts)
+        unless @operation == :scan
+          raise ArgumentError.new("parallel_scan is only supported for scans")
+        end
+        unless opts[:total_segments] && opts[:segment]
+          raise ArgumentError.new("Must specify :total_segments and :segment in a parallel scan.")
+        end
+        @params[:total_segments] = opts[:total_segments]
+        @params[:segment] = opts[:segment]
+        self
+      end
+
+      # For a query operation, you can use this to set if you query is in
+      # ascending or descending order on your range key. By default, a query is
+      # run in ascending order.
+      def scan_ascending(b)
+        unless @operation == :query
+          raise ArgumentError.new("scan_ascending is only supported for queries.")
+        end
+        @params[:scan_index_forward] = b
+        self
+      end
+
+      # If you have an exclusive start key for your query or scan, you can
+      # provide it with this builder method. You should not use this if you are
+      # querying or scanning without a set starting point, as the
+      # {Aws::Record::ItemCollection} class handles pagination automatically
+      # for you.
+      def exclusive_start_key(key)
+        @params[:exclusive_start_key] = key
+        self
+      end
+
+      # Provide a key condition expression for your query using a substitution
+      # expression.
+      #
+      # @example Building a simple query with a key expression:
+      #   # Example model class
+      #   class ExampleTable
+      #     include Aws::Record
+      #     string_attr  :uuid, hash_key: true
+      #     integer_attr :id,   range_key: true
+      #     string_attr  :body
+      #   end
+      #
+      #   q = ExampleTable.build_query.key_expr(
+      #         ":uuid = ? AND :id > ?", "smpl-uuid", 100
+      #       ).complete!
+      #   q.to_a # You can use this like any other query result in aws-record
+      def key_expr(statement_str, *subs)
+        unless @operation == :query
+          raise ArgumentError.new("key_expr is only supported for queries.")
+        end
+        names = @params[:expression_attribute_names]
+        if names.nil?
+          @params[:expression_attribute_names] = {}
+          names = @params[:expression_attribute_names]
+        end
+        values = @params[:expression_attribute_values]
+        if values.nil?
+          @params[:expression_attribute_values] = {}
+          values = @params[:expression_attribute_values]
+        end
+        _key_pass(statement_str, names)
+        _apply_values(statement_str, subs, values)
+        @params[:key_condition_expression] = statement_str
+        self
+      end
+
+      # Provide a filter expression for your query or scan using a substitution
+      # expression.
+      #
+      # @example Building a simple scan:
+      #   # Example model class
+      #   class ExampleTable
+      #     include Aws::Record
+      #     string_attr  :uuid, hash_key: true
+      #     integer_attr :id,   range_key: true
+      #     string_attr  :body
+      #   end
+      #
+      #   scan = ExampleTable.build_scan.filter_expr(
+      #     "contains(:body, ?)",
+      #     "bacon"
+      #   ).complete!
+      # 
+      def filter_expr(statement_str, *subs)
+        names = @params[:expression_attribute_names]
+        if names.nil?
+          @params[:expression_attribute_names] = {}
+          names = @params[:expression_attribute_names]
+        end
+        values = @params[:expression_attribute_values]
+        if values.nil?
+          @params[:expression_attribute_values] = {}
+          values = @params[:expression_attribute_values]
+        end
+        _key_pass(statement_str, names)
+        _apply_values(statement_str, subs, values)
+        @params[:filter_expression] = statement_str
+        self
+      end
+
+      # Allows you to define a projection expression for the values returned by
+      # a query or scan. See
+      # {https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ProjectionExpressions.html the Amazon DynamoDB Developer Guide}
+      # for more details on projection expressions. You can use the symbols from
+      # your aws-record model class in a projection expression. Keys are always
+      # retrieved.
+      #
+      # @example Scan with a projection expression:
+      #   # Example model class
+      #   class ExampleTable
+      #     include Aws::Record
+      #     string_attr  :uuid, hash_key: true
+      #     integer_attr :id,   range_key: true
+      #     string_attr  :body
+      #     map_attr     :metadata
+      #   end
+      #
+      #   scan = ExampleTable.build_scan.projection_expr(
+      #     ":body"
+      #   ).complete!
+      def projection_expr(statement_str)
+        names = @params[:expression_attribute_names]
+        if names.nil?
+          @params[:expression_attribute_names] = {}
+          names = @params[:expression_attribute_names]
+        end
+        _key_pass(statement_str, names)
+        @params[:projection_expression] = statement_str
+        self
+      end
+
+      # Allows you to set a page size limit on each query or scan request.
+      def limit(size)
+        @params[:limit] = size
+        self
+      end
+
+      # You must call this method at the end of any query or scan you build.
+      #
+      # @return [Aws::Record::ItemCollection] The item collection lazy
+      #   enumerable.
+      def complete!
+        @model.send(@operation, @params)
+      end
+
+      private
+      def _key_pass(statement, names)
+        statement.gsub!(/:(\w+)/) do |match|
+          key = match.gsub!(':','').to_sym 
+          key_name = @model.attributes.storage_name_for(key)
+          if key_name
+            sub_name = _next_name
+            raise "Substitution collision!" if names[sub_name]
+            names[sub_name] = key_name
+            sub_name
+          else
+            raise "No such key #{key}"
+          end
+        end
+      end
+
+      def _apply_values(statement, subs, values)
+        count = 0
+        statement.gsub!(/[?]/) do |match|
+          sub_value = _next_value
+          raise "Substitution collision!" if values[sub_value]
+          values[sub_value] = subs[count]
+          count += 1
+          sub_value
+        end
+        unless count == subs.size
+          raise "Expected #{count} values in the substitution set, but found #{subs.size}"
+        end
+      end
+
+      def _next_name
+        ret = "#" + @next_name
+        @next_name.next!
+        ret
+      end
+
+      def _next_value
+        ret = ":" + @next_value
+        @next_value.next!
+        ret
+      end
+    end
+  end
+end

data/lib/aws-record/record/query.rb

@@ -102,6 +102,54 @@ module Aws
           scan_opts = opts.merge(table_name: table_name)
           ItemCollection.new(:scan, scan_opts, self, dynamodb_client)
         end
+
+        # This method allows you to build a query using the {Aws::Record::BuildableSearch} DSL.
+        #
+        # @example Building a simple query:
+        #   # Example model class
+        #   class ExampleTable
+        #     include Aws::Record
+        #     string_attr  :uuid, hash_key: true
+        #     integer_attr :id,   range_key: true
+        #     string_attr  :body
+        #   end
+        #
+        #   q = ExampleTable.build_query.key_expr(
+        #         ":uuid = ? AND :id > ?", "smpl-uuid", 100
+        #       ).scan_ascending(false).complete!
+        #   q.to_a # You can use this like any other query result in aws-record
+        def build_query
+          BuildableSearch.new(
+            operation: :query,
+            model: self
+          )
+        end
+
+        # This method allows you to build a scan using the {Aws::Record::BuildableSearch} DSL.
+        #
+        # @example Building a simple scan:
+        #   # Example model class
+        #   class ExampleTable
+        #     include Aws::Record
+        #     string_attr  :uuid, hash_key: true
+        #     integer_attr :id,   range_key: true
+        #     string_attr  :body
+        #   end
+        #
+        #   segment_2_scan = ExampleTable.build_scan.filter_expr(
+        #     "contains(:body, ?)",
+        #     "bacon"
+        #   ).scan_ascending(false).parallel_scan(
+        #     total_segments: 5,
+        #     segment: 2
+        #   ).complete!
+        #   segment_2_scan.to_a # You can use this like any other query result in aws-record
+        def build_scan
+          BuildableSearch.new(
+            operation: :scan,
+            model: self
+          )
+        end
       end
 
     end

data/lib/aws-record/record/version.rb

@@ -13,6 +13,6 @@
 
 module Aws
   module Record
-    VERSION = '2.3.0'
+    VERSION = '2.4.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aws-record
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.4.0
 platform: ruby
 authors:
 - Amazon Web Services
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-02-08 00:00:00.000000000 Z
+date: 2019-07-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-dynamodb
@@ -35,6 +35,7 @@ files:
 - lib/aws-record/record.rb
 - lib/aws-record/record/attribute.rb
 - lib/aws-record/record/attributes.rb
+- lib/aws-record/record/buildable_search.rb
 - lib/aws-record/record/dirty_tracking.rb
 - lib/aws-record/record/errors.rb
 - lib/aws-record/record/item_collection.rb
@@ -80,7 +81,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 2.5.2
 signing_key: 
 specification_version: 4
 summary: AWS Record library for Amazon DynamoDB