google-cloud-firestore 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e83411cc86b2d8999f2ea7771cc243f032b9119c03885427aa57b007c3695406
-  data.tar.gz: 2ba1894414f95466c521ac6159dcfeedfb713727049171226a0eaecb2b041a71
+  metadata.gz: d1e7097a28daa16ef5b2de8684c5b052b6409b792a4e7f382f878c47745dbf1a
+  data.tar.gz: 35dae74e7a063ad5e456420633c50b60ea0731b2fcafdde0e6ceab25b10bea25
 SHA512:
-  metadata.gz: ee5186f01ad3ec6adf7508a043793306c622f77b5a4552f91a787d52860e57e8e65c99561d8995cd7dd3a424801ac7e56b36174e6a9139179bed3ac708391966
-  data.tar.gz: 0c2037885a4d5b12151f346f181de0f632e6c2c399e095899cd9567ad484ac954463c757740c0306639473edf69115a1e8fc37e1914727cbef11d90241aaef9c
+  metadata.gz: 23da24a3a861701b5156d1851be1eba45770565319e86d66e098f3a59156490ec16a7457d52fa55d0c216df653d2e1873a6212b5df3b23c67f576d40d706bd53
+  data.tar.gz: 9aef0214f2cf6a9db195be9b27dbb50f087b8d25be9041419a9d14d018f910aad449140848a0d49aa0223961672361b18e47a1f60b0e6eeeedd3752a88c2ac3a

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release History
 
+### 2.1.0 / 2020-09-10
+
+#### Features
+
+* Add Query#limit_to_last
+
 ### 2.0.0 / 2020-08-06
 
 This is a major update that removes the "low-level" client interface code, and

data/lib/google/cloud/firestore/query.rb

@@ -62,6 +62,10 @@ module Google
         # @private The parent path for the query.
         attr_accessor :parent_path
 
+        ##
+        # @private The type for limit queries.
+        attr_reader :limit_type
+
         ##
         # @private The Google::Cloud::Firestore::V1::StructuredQuery object.
         attr_accessor :query
@@ -118,7 +122,7 @@ module Google
             new_query.select.fields << field_ref
           end
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
 
         ##
@@ -154,7 +158,7 @@ module Google
 
           new_query.from.last.all_descendants = true
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
 
         ##
@@ -190,7 +194,7 @@ module Google
 
           new_query.from.last.all_descendants = false
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
 
         ##
@@ -246,7 +250,7 @@ module Google
           new_filter = filter field.formatted_string, operator, value
           add_filters_to_query new_query, new_filter
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
 
         ##
@@ -298,9 +302,8 @@ module Google
         #   end
         #
         def order field, direction = :asc
-          if query_has_cursors?
-            raise "cannot call order after calling " \
-                  "start_at, start_after, end_before, or end_at"
+          if query_has_cursors? || limit_type == :last
+            raise "cannot call order after calling limit_to_last, start_at, start_after, end_before, or end_at"
           end
 
           new_query = @query.dup
@@ -315,7 +318,7 @@ module Google
             direction: order_direction(direction)
           )
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
         alias order_by order
 
@@ -348,12 +351,13 @@ module Google
 
           new_query.offset = num
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
 
         ##
-        # Limits a query to return a fixed number of results. If the current
-        # query already has a limit set, this will overwrite it.
+        # Limits a query to return only the first matching documents.
+        #
+        # If the current query already has a limit set, this will overwrite it.
         #
         # @param [Integer] num The maximum number of results to return.
         #
@@ -368,19 +372,83 @@ module Google
         #   cities_col = firestore.col "cities"
         #
         #   # Create a query
-        #   query = cities_col.offset(10).limit(5)
+        #   query = cities_col.order(:name, :desc).offset(10).limit(5)
         #
         #   query.get do |city|
         #     puts "#{city.document_id} has #{city[:population]} residents."
         #   end
         #
         def limit num
+          if limit_type == :last
+            raise "cannot call limit after calling limit_to_last"
+          end
+
           new_query = @query.dup
           new_query ||= StructuredQuery.new
 
           new_query.limit = Google::Protobuf::Int32Value.new value: num
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: :first
+        end
+
+        ##
+        # Limits a query to return only the last matching documents.
+        #
+        # You must specify at least one "order by" clause for limitToLast queries.
+        # (See {#order}.)
+        #
+        # Results for `limit_to_last` queries are only available once all documents
+        # are received. Hence, `limit_to_last` queries cannot be streamed using
+        # {#listen}.
+        #
+        # @param [Integer] num The maximum number of results to return.
+        #
+        # @return [Query] New query with `limit_to_last` called on it.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   cities_col = firestore.col "cities"
+        #
+        #   # Create a query
+        #   query = cities_col.order(:name, :desc).limit_to_last(5)
+        #
+        #   query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        def limit_to_last num
+          new_query = @query.dup
+
+          if new_query.nil? || new_query.order_by.nil? || new_query.order_by.empty?
+            raise "specify at least one order clause before calling limit_to_last"
+          end
+
+          if limit_type != :last # Don't reverse order_by more than once.
+            # Reverse the order_by directions since we want the last results.
+            new_query.order_by.each do |order|
+              order.direction = order.direction.to_sym == :DESCENDING ? :ASCENDING : :DESCENDING
+            end
+
+            # Swap the cursors to match the reversed query ordering.
+            new_end_at = new_query.start_at.dup
+            new_start_at = new_query.end_at.dup
+            if new_end_at
+              new_end_at.before = !new_end_at.before
+              new_query.end_at = new_end_at
+            end
+            if new_start_at
+              new_start_at.before = !new_start_at.before
+              new_query.start_at = new_start_at
+            end
+          end
+
+          new_query.limit = Google::Protobuf::Int32Value.new value: num
+
+          Query.start new_query, parent_path, client, limit_type: :last
         end
 
         ##
@@ -477,6 +545,10 @@ module Google
         def start_at *values
           raise ArgumentError, "must provide values" if values.empty?
 
+          if limit_type == :last
+            raise "cannot call start_at after calling limit_to_last"
+          end
+
           new_query = @query.dup
           new_query ||= StructuredQuery.new
 
@@ -484,7 +556,7 @@ module Google
           cursor.before = true
           new_query.start_at = cursor
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
 
         ##
@@ -581,6 +653,11 @@ module Google
         def start_after *values
           raise ArgumentError, "must provide values" if values.empty?
 
+          if limit_type == :last
+            raise "cannot call start_after after calling limit_to_last"
+          end
+
+
           new_query = @query.dup
           new_query ||= StructuredQuery.new
 
@@ -588,7 +665,7 @@ module Google
           cursor.before = false
           new_query.start_at = cursor
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
 
         ##
@@ -685,6 +762,11 @@ module Google
         def end_before *values
           raise ArgumentError, "must provide values" if values.empty?
 
+          if limit_type == :last
+            raise "cannot call end_before after calling limit_to_last"
+          end
+
+
           new_query = @query.dup
           new_query ||= StructuredQuery.new
 
@@ -692,7 +774,7 @@ module Google
           cursor.before = true
           new_query.end_at = cursor
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
 
         ##
@@ -789,6 +871,11 @@ module Google
         def end_at *values
           raise ArgumentError, "must provide values" if values.empty?
 
+          if limit_type == :last
+            raise "cannot call end_at after calling limit_to_last"
+          end
+
+
           new_query = @query.dup
           new_query ||= StructuredQuery.new
 
@@ -796,7 +883,7 @@ module Google
           cursor.before = false
           new_query.end_at = cursor
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
 
         ##
@@ -828,6 +915,10 @@ module Google
           return enum_for :get unless block_given?
 
           results = service.run_query parent_path, @query
+
+          # Reverse the results for Query#limit_to_last queries since that method reversed the order_by directions.
+          results = results.to_a.reverse if limit_type == :last
+
           results.each do |result|
             next if result.document.nil?
             yield DocumentSnapshot.from_query_result result, client
@@ -870,11 +961,12 @@ module Google
 
         ##
         # @private Start a new Query.
-        def self.start query, parent_path, client
+        def self.start query, parent_path, client, limit_type: nil
           query ||= StructuredQuery.new
           Query.new.tap do |q|
             q.instance_variable_set :@query, query
             q.instance_variable_set :@parent_path, parent_path
+            q.instance_variable_set :@limit_type, limit_type
             q.instance_variable_set :@client, client
           end
         end

data/lib/google/cloud/firestore/version.rb

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Firestore
-      VERSION = "2.0.0".freeze
+      VERSION = "2.1.0".freeze
     end
   end
 end

data/lib/google/cloud/firestore/watch/inventory.rb

@@ -127,6 +127,8 @@ module Google
           end
 
           def current_docs
+            # Reverse the results for Query#limit_to_last queries since that method reversed the order_by directions.
+            return @tree.keys.reverse if @query&.limit_type == :last
             @tree.keys
           end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-firestore
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Google Inc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-06 00:00:00.000000000 Z
+date: 2020-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core