cassie 1.0.0.beta.1 → 1.0.0.beta.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2b8f581ee400104d561a3c3bb12ef2cdb95c0f98
-  data.tar.gz: 931dc3e000852e1ad9a0773aecbc54c0617badbf
+  metadata.gz: df9c9472bd40950a8fb5cae45a95ab79661276f6
+  data.tar.gz: 79a9cad9af8d1410c73937f4c8ff52da630f40b5
 SHA512:
-  metadata.gz: be2ee76d1ede47feeac24b9295cbc2e137bb2807bc45049ca7ca98feb7939a6975a83865cf4eed881871effd7487fa6ed40864765df37298a9e217a0e0e15631
-  data.tar.gz: 0ec6179d4534a0ac5dd35e737f4b231c6f4ef1d6026a56cc524ee5e348323797fd9b15d82d0365c5b192a3a651cdde49d2676e3011179aa6e6be711106d99972
+  metadata.gz: 1a331744722854ba71c48f432b41a1e19c54ee3ba15f40cd44922ba0be832d591ed31895faf8c371cb22b952bbf2e6aec1303c86b390bb08e2ae01bdf56887e6
+  data.tar.gz: 59939300bfc14cb906015dee1fa13dafa72050011853f33a82cb1a11bd6bb42b293905529750bd9dd56e4e4bc0bed2e39806b3439b7b6ecb68a94a0e7a9251fe

data/lib/cassie/queries/README.md

@@ -1,6 +1,6 @@
 # Cassie Queries
 
-`cassie` query classes provide query interface that is
+`cassie` query classes aim to provide a query interface that is
 
 * Easy to use
 * Easy to understand (and thus maintain)
@@ -9,7 +9,7 @@
 
 ### Usage
 
-What you might expect to see:
+You might expect to see class methods allowing queries to be built like such:
 
 ```
 Cassie.insert(:users_by_username,
@@ -22,7 +22,7 @@ Queries defined on the fly like this tend to create debt for an application in t
   * resist documentation
   * resist refactoring
 
-Your application queries represent behavior, `cassie` queries are structured to help you create query classes that are reusable, testable and maintainable, so you can sleep better at night.
+Your application queries represent distinct application behavior, `cassie` queries are designed to help you create query classes that are reusable, testable and maintainable (so you can sleep better at night).
 
 ```ruby
 # Some PORO user model
@@ -200,8 +200,74 @@ task :interesting_task do
 
   InterestingWorker.new.perform
 end
+```
+
+#### Finders
+
+To avoid confusion with ruby `Enumerable#find` and Rails' specific `find` functionality, Cassie::Query opts to use `fetch` and explict `fetch_first` or `fetch_first!` methods.
+
+##### `fetch`
+
+Executes the query; returns array of results.
+
+```
+UsersByResourceQuery.new.fetch(resource: some_resource)
+=> [#<User id=:123, username=:eprothro>, #<User id=:456, username=:tenderlove>]
+```
+
+##### `fetch_first` and `fetch_first!`
+
+Executes the query, temporarily limited to 1 result; returns a single result. Bang version raises if no result is found.
+
+```
+UsersByUsernameQuery.new.fetch_first(username: "eprothro").username
+=> "eprothro"
+```
+
+```
+UsersByUsernameQuery.new.fetch_first(username: "active record").username
+Cassie::Queries::RecordNotFound: CQL row does not exist
+```
+
+##### Batching
+
+Similar to [Rails Batching](http://guides.rubyonrails.org/v4.2/active_record_querying.html#retrieving-multiple-objects-in-batches), Cassie allows efficient batching of `SELECT` queries.
+
+###### `fetch_each`
+```
+UsersQuery.new.fetch_each do |user|
+  # hey look, only 1000 loaded at a time!
+end
+```
+
+```
+UsersQuery.new.fetch_each(batch_size: 500) do |user|
+  # hey look, only 500 loaded at a time!
+end
+```
+
+```
+UsersQuery.new.fetch_each.with_index do |user, index|
+  # hey look, Enumerator chaining!
+end
+```
+###### `fetch_in_batches`
+```
+UsersQuery.new.fetch_in_batches do |users_array|
+  # hey look, only 1000 loaded at a time!
+end
+```
 
+```
+UsersQuery.new.fetch_in_batches(batch_size: 500) do |users_array|
+  # hey look, only 500 loaded at a time!
+end
+```
 
+```
+UsersQuery.new.fetch_in_batches.with_index do |group, index|
+  # hey look, Enumerator chaining!
+end
 ```
 
 #### Object Mapping
@@ -211,11 +277,11 @@ For Selection Queries, resources are returned as structs by default for manipula
 UsersByUsernameQuery.new.fetch(username: "eprothro")
 => [#<Struct id=:123, username=:eprothro>]
 
-UsersByUsernameQuery.new.find(username: "eprothro").username
+UsersByUsernameQuery.new.fetch_first(username: "eprothro").username
 => "eprothro"
 ```
 
-Override `build_resource` to construct more useful objects
+Most application will want to override `build_resource` to construct more useful domain objects
 
 ```
 class UsersByUsernameQuery < Cassie::Query
@@ -235,7 +301,7 @@ UsersByUsernameQuery.new.find(username: "eprothro")
 => #<User:0x007fedec219cd8 @id=123, @username="eprothro">
 ```
 
-For Data Modification Queries (`insert`, `update`, `delete`), mapping binding values from an object is supported.
+For Data Modification Queries (`insert`, `update`, `delete`), mapping binding values from a domain object is supported.
 
 ```ruby
 class UpdateUserQuery < Cassandra::Query
@@ -252,7 +318,7 @@ class UpdateUserQuery < Cassandra::Query
   map_from :user
 ```
 
-Allowing you to pass an object to the modification method, and binding values will be retrieved from the object
+This allows a domain object to be passed to the modification method, where binding values will be retrieved from the object
 
 ```ruby
 user
@@ -264,6 +330,7 @@ UpdateUserQuery.new.update(user)
 (1.2ms) UPDATE users_by_id (phone, email, address, username) VALUES (?, ?, ?, ?) WHERE id = ?; [["+15555555555", "etp@example.com", nil, "etp", 6539]]
 </b></pre>
 
+
 #### Cursored paging
 
 Read about [cursored pagination](https://www.google.com/webhp?q=cursored%20paging#safe=off&q=cursor+paging) if unfamiliar with concept and how it optimizes paging through frequently updated data sets and I/O bandwidth.

data/lib/cassie/queries/statement/batches.rb

@@ -0,0 +1,56 @@
+require_relative 'relation'
+require_relative 'loading'
+require_relative 'batches'
+
+module Cassie::Queries::Statement
+  module Batches
+    extend ::ActiveSupport::Concern
+
+    included do
+      attr_reader :paging_state
+      attr_reader :stateless_page_size
+    end
+
+    def fetch_each
+    end
+
+    # Yields each batch of records that was found by the options as an array.
+    #
+    # If you do not provide a block to find_in_batches, it will return an Enumerator for chaining with other methods.
+    #
+    #  query.fetch_in_batches do |records|
+    #   puts "max score in group: #{records.max{ |a, b| a.score <=> b.score }}"
+    #  end
+    #
+    #  "max score in group: 26"
+    def fetch_in_batches(opts={})
+      return to_enum(:fetch_in_batches, opts) unless block_given?
+      opts[:batch_size] ||= 1000
+
+      # set cassandra internal
+      # stateless page size (independent from limit)
+      @stateless_page_size = opts[:batch_size]
+      @paging_state = nil
+      done = false
+
+      # use Cassandra internal paging
+      # but keep result within this query object
+      loop do
+        raise page_size_changed_error(opts[:batch_size]) if opts[:batch_size] != self.stateless_page_size
+        batch = fetch
+
+        @paging_state = result.paging_state
+        break if done
+        done = true if result.last_page?
+
+        yield batch
+      end
+    end
+
+    private
+
+    def page_size_changed_error(original_size)
+      Cassie::Queries::Statement::Invalid.new("Page size is no longer valid. It was #{original_size} when the batch was started, and is now #{self.page_size}. Continuing would cause unexpected results.")
+    end
+  end
+end

data/lib/cassie/queries/statement/callbacks.rb

@@ -14,7 +14,7 @@ module Cassie::Queries::Statement
     end
 
     def execute
-      run_callbacks :failure unless super
+      super || run_callbacks(:failure)
     end
   end
 end

data/lib/cassie/queries/statement/execution.rb

@@ -20,6 +20,8 @@ module Cassie::Queries::Statement
         #TODO: rework consistency module to be more
         #      abstract implementation for all execution options
         opts[:consistency] = consistency if consistency
+        opts[:paging_state] = paging_state if respond_to?(:paging_state) && paging_state
+        opts[:page_size] = stateless_page_size if respond_to?(:stateless_page_size) && stateless_page_size
       end
     end
 

data/lib/cassie/queries/statement/fetching.rb

@@ -1,5 +1,6 @@
 require_relative 'relation'
 require_relative 'loading'
+require_relative 'batches'
 
 class Cassie::Queries::RecordNotFound < StandardError; end
 
@@ -9,6 +10,7 @@ module Cassie::Queries::Statement
 
     included do
       include Loading
+      include Batches
     end
 
     # Returns array of rows or empty array
@@ -27,16 +29,16 @@ module Cassie::Queries::Statement
 
     # Returns first result or nil
     #
-    #   query.find(id: 1)
+    #   query.fetch_first(id: 1)
     #   => {id: 1, name: 'eprothro'}
     #
-    #   query.find(id: 2)
+    #   query.fetch_first(id: 2)
     #   => nil
-    def find(args={})
+    def fetch_first(args={})
       old_limit = defined?(@limit) ? @limit : nil
       self.limit = 1
 
-      fetch.first
+      fetch(args).first
     ensure
       if old_limit
         @limit = old_limit
@@ -47,13 +49,13 @@ module Cassie::Queries::Statement
 
     # Returns first result or raises RecordNotFound
     #
-    #   query.find!(id: 1)
+    #   query.fetch_first!(id: 1)
     #   => {id: 1, name: 'eprothro'}
     #
-    #   query.find!(id: 2)
+    #   query.fetch_first!(id: 2)
     #   RecordNotFound: RecordNotFound
-    def find!(args={})
-      find || raise(Cassie::Queries::RecordNotFound)
+    def fetch_first!(args={})
+      fetch_first || raise(Cassie::Queries::RecordNotFound.new('CQL row does not exist'))
     end
   end
 end

data/lib/cassie/queries/statement/loading.rb

@@ -18,7 +18,7 @@ module Cassie::Queries::Statement
     # When class doesn't override
     # simply return a struct with the row data
     def build_resource(row)
-      Struct.new(*row.keys).new(*row.values)
+      Struct.new(*row.keys.map(&:to_sym)).new(*row.values)
     end
   end
 end

data/lib/cassie/queries/statement.rb

@@ -13,6 +13,8 @@ require_relative 'statement/inserting'
 
 module Cassie::Queries
   module Statement
+    class Invalid < StandardError; end
+
     # https://cassandra.apache.org/doc/cql3/CQL.html#selectStmt
     extend ::ActiveSupport::Concern
 

data/lib/cassie/testing/fake/query.rb

@@ -6,5 +6,6 @@ module Cassie
 
   class FakeQuery < Cassie::Query
     include Cassie::Testing::Fake::SessionMethods
+
   end
 end

data/lib/cassie/testing/fake/result.rb

@@ -20,5 +20,13 @@ module Cassie::Testing::Fake
     def empty?
       rows.empty?
     end
+
+    def last_page?
+      true
+    end
+
+    def paging_state
+      'that state tho!'
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cassie
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta.1
+  version: 1.0.0.beta.3
 platform: ruby
 authors:
 - Evan Prothro
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-06 00:00:00.000000000 Z
+date: 2016-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cassandra-driver
@@ -132,6 +132,7 @@ files:
 - lib/cassie/queries/statement.rb
 - lib/cassie/queries/statement/assignment.rb
 - lib/cassie/queries/statement/assignments.rb
+- lib/cassie/queries/statement/batches.rb
 - lib/cassie/queries/statement/callbacks.rb
 - lib/cassie/queries/statement/conditions.rb
 - lib/cassie/queries/statement/consistency.rb