google-cloud-firestore 2.5.1 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d0f9ea11dcd132795aca2ffe91250ca03fce477e6fdcb3aafc7e9d01560b172
-  data.tar.gz: 3701797b2412e82cdf227fe9d162291e53e2aaf4a1c3cc8d37d18ea0a9795f1c
+  metadata.gz: 3141b004673c1db562f162d9218ac680c0693e4d91a8eb48b7d17f444646e74a
+  data.tar.gz: 4ab2bb6f69da5f8ad2e53464ae3712647b3642d49a465dc5f75d1dbc923979f5
 SHA512:
-  metadata.gz: e8ce0745147c89e081b94f08a3753bc0a234f1a2e9a5eb9eb15cfc798abbb01e5970fb354db0ff6b71096353dabe2a023e8cba7d5d4c909f20793f953473044d
-  data.tar.gz: 489e87876e77584f429472f12c157b0c1412d336190b3a8a88e706e262c3d0409b4b00c55207ebd6cab15f0a6ae7b1ad45177c8dfcc87408cd96384db1a11038
+  metadata.gz: fd5dccbe067d6fea81556aae40b9fc9de2ca75fc389c919335217371d84578b68ad7c9854c84831bb368dd58982849c06f044cef0c864be586cdace0ea48994a
+  data.tar.gz: 7a7f0ee2a3259f2a65119b0b31dbf781d7336f7c530301f4c7f0a7fdf95fea8a7773caa4ed172c9ce8c5ff9f9fe80dab830f37ef1e6d204ae7d770fdf9c066c0

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Release History
 
+### 2.6.0 / 2021-06-15
+
+#### Features
+
+* Add support for Query Partitions
+  * Add CollectionGroup
+  * Update Client#col_group to return CollectionGroup (subclass of Query)
+  * Add QueryPartition
+  * Add QueryPartition::List
+  * Add Query#to_json and Query.from_json
+
 ### 2.5.1 / 2021-04-19
 
 #### Bug Fixes

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

@@ -20,6 +20,7 @@ require "google/cloud/firestore/field_value"
 require "google/cloud/firestore/collection_reference"
 require "google/cloud/firestore/document_reference"
 require "google/cloud/firestore/document_snapshot"
+require "google/cloud/firestore/collection_group"
 require "google/cloud/firestore/batch"
 require "google/cloud/firestore/transaction"
 
@@ -139,7 +140,7 @@ module Google
         alias collection col
 
         ##
-        # Creates and returns a new Query that includes all documents in the
+        # Creates and returns a new collection group that includes all documents in the
         # database that are contained in a collection or subcollection with the
         # given collection_id.
         #
@@ -147,7 +148,7 @@ module Google
         #   over. Every collection or subcollection with this ID as the last
         #   segment of its path will be included. Cannot contain a slash (`/`).
         #
-        # @return [Query] The created Query.
+        # @return [CollectionGroup] The created collection group.
         #
         # @example
         #   require "google/cloud/firestore"
@@ -155,9 +156,9 @@ module Google
         #   firestore = Google::Cloud::Firestore.new
         #
         #   # Get the cities collection group query
-        #   query = firestore.col_group "cities"
+        #   col_group = firestore.col_group "cities"
         #
-        #   query.get do |city|
+        #   col_group.get do |city|
         #     puts "#{city.document_id} has #{city[:population]} residents."
         #   end
         #
@@ -166,15 +167,8 @@ module Google
             raise ArgumentError, "Invalid collection_id: '#{collection_id}', " \
               "must not contain '/'."
           end
-          query = Google::Cloud::Firestore::V1::StructuredQuery.new(
-            from: [
-              Google::Cloud::Firestore::V1::StructuredQuery::CollectionSelector.new(
-                collection_id: collection_id, all_descendants: true
-              )
-            ]
-          )
-
-          Query.start query, service.documents_path, self
+
+          CollectionGroup.from_collection_id service.documents_path, collection_id, self
         end
         alias collection_group col_group
 

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

@@ -0,0 +1,136 @@
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "google/cloud/firestore/v1"
+require "google/cloud/firestore/query"
+require "google/cloud/firestore/query_partition"
+
+module Google
+  module Cloud
+    module Firestore
+      ##
+      # # CollectionGroup
+      #
+      # A collection group object is used for adding documents, getting
+      # document references, and querying for documents, including with partitions.
+      #
+      # See {Client#col_group} and {Query}.
+      #
+      # @example
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #
+      #   # Get a collection group
+      #   col_group = firestore.col_group "cities"
+      #
+      #   # Get and print all city documents
+      #   col_group.get do |city|
+      #     puts "#{city.document_id} has #{city[:population]} residents."
+      #   end
+      #
+      class CollectionGroup < Query
+        ##
+        # Partitions a query by returning partition cursors that can be used to run the query in parallel. The returned
+        # partition cursors are split points that can be used as starting/end points for the query results.
+        #
+        # @param [Integer] partition_count The desired maximum number of partition points. The number must be strictly
+        #   positive. The actual number of partitions returned may be fewer.
+        #
+        # @return [Array<QueryPartition>] An ordered array of query partitions.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   col_group = firestore.col_group "cities"
+        #
+        #   partitions = col_group.partitions 3
+        #
+        #   queries = partitions.map(&:to_query)
+        #
+        def partitions partition_count
+          ensure_service!
+
+          raise ArgumentError, "partition_count must be > 0" unless partition_count.positive?
+
+          # Partition queries require explicit ordering by __name__.
+          query_with_default_order = order "__name__"
+          # Since we are always returning an extra partition (with en empty endBefore cursor), we reduce the desired
+          # partition count by one.
+          partition_count -= 1
+
+          grpc_partitions = if partition_count.positive?
+                              # Retrieve all pages, since cursor order is not guaranteed and they must be sorted.
+                              list_all partition_count, query_with_default_order
+                            else
+                              [] # Ensure that a single, empty QueryPartition is returned.
+                            end
+          cursor_values = grpc_partitions.map do |cursor|
+            # Convert each cursor to a (single-element) array of Google::Cloud::Firestore::DocumentReference.
+            cursor.values.map do |value|
+              Convert.value_to_raw value, client
+            end
+          end
+          # Sort the values of the returned cursor, which right now should only contain a single reference value (which
+          # needs to be sorted one component at a time).
+          cursor_values.sort! do |a, b|
+            a.first <=> b.first
+          end
+
+          start_at = nil
+          results = cursor_values.map do |end_before|
+            partition = QueryPartition.new query_with_default_order, start_at, end_before
+            start_at = end_before
+            partition
+          end
+          # Always add a final QueryPartition with an empty end_before value.
+          results << QueryPartition.new(query_with_default_order, start_at, nil)
+          results
+        end
+
+        ##
+        # @private New Collection group object from a path.
+        def self.from_collection_id parent_path, collection_id, client
+          query = Google::Cloud::Firestore::V1::StructuredQuery.new(
+            from: [
+              Google::Cloud::Firestore::V1::StructuredQuery::CollectionSelector.new(
+                collection_id: collection_id,
+                all_descendants: true
+              )
+            ]
+          )
+          CollectionGroup.new query, parent_path, client
+        end
+
+        protected
+
+        def list_all partition_count, query_with_default_order
+          grpc_partitions = []
+          token = nil
+          loop do
+            grpc = service.partition_query parent_path, query_with_default_order.query, partition_count, token: token
+            grpc_partitions += Array(grpc.partitions)
+            token = grpc.next_page_token
+            token = nil if token == ""
+            break unless token
+          end
+          grpc_partitions
+        end
+      end
+    end
+  end
+end

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

@@ -14,9 +14,9 @@
 
 
 require "google/cloud/firestore/v1"
+require "google/cloud/firestore/query"
 require "google/cloud/firestore/document_reference"
 require "google/cloud/firestore/document_snapshot"
-require "google/cloud/firestore/query"
 require "google/cloud/firestore/generate"
 require "google/cloud/firestore/collection_reference_list"
 
@@ -47,6 +47,13 @@ module Google
         # @private The firestore client object.
         attr_accessor :client
 
+        ##
+        # @private Creates a new CollectionReference.
+        def initialize query, path, client
+          super query, nil, client # Pass nil parent_path arg since this class implements #parent_path
+          @path = path
+        end
+
         ##
         # The collection identifier for the collection resource.
         #
@@ -257,11 +264,7 @@ module Google
             ]
           )
 
-          new.tap do |c|
-            c.client = client
-            c.instance_variable_set :@path, path
-            c.instance_variable_set :@query, query
-          end
+          CollectionReference.new query, path, client
         end
 
         protected

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

@@ -18,6 +18,7 @@ require "google/cloud/firestore/document_snapshot"
 require "google/cloud/firestore/collection_reference"
 require "google/cloud/firestore/document_listener"
 require "google/cloud/firestore/document_reference/list"
+require "google/cloud/firestore/resource_path"
 
 module Google
   module Cloud
@@ -459,6 +460,12 @@ module Google
 
         # @!endgroup
 
+        # @private
+        def <=> other
+          return nil unless other.is_a? self.class
+          ResourcePath.from_path(path) <=> ResourcePath.from_path(other.path)
+        end
+
         ##
         # @private New DocumentReference object from a path.
         def self.from_path path, client

data/lib/google/cloud/firestore/document_reference/list.rb

@@ -109,7 +109,7 @@ module Google
           #
           # @return [Enumerator]
           #
-          # @example Iterating each document reference by passing a block:
+          # @example Iterating each document reference by passing a block or proc:
           #   require "google/cloud/firestore"
           #
           #   firestore = Google::Cloud::Firestore.new

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

@@ -27,9 +27,14 @@ module Google
       #
       #   firestore = Google::Cloud::Firestore.new
       #
-      #   user_snap = firestore.doc("users/frank").get
+      #   # Get a document reference
+      #   nyc_ref = firestore.doc "cities/NYC"
       #
-      #   # TODO
+      #   # Set the population to increment by 1.
+      #   increment_value = Google::Cloud::Firestore::FieldValue.increment 1
+      #
+      #   nyc_ref.update({ name: "New York City",
+      #                    population: increment_value })
       #
       class FieldValue
         ##

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

@@ -17,6 +17,7 @@ require "google/cloud/firestore/v1"
 require "google/cloud/firestore/document_snapshot"
 require "google/cloud/firestore/query_listener"
 require "google/cloud/firestore/convert"
+require "json"
 
 module Google
   module Cloud
@@ -74,6 +75,16 @@ module Google
         # @private The firestore client object.
         attr_accessor :client
 
+        ##
+        # @private Creates a new Query.
+        def initialize query, parent_path, client, limit_type: nil
+          query ||= StructuredQuery.new
+          @query = query
+          @parent_path = parent_path
+          @limit_type = limit_type
+          @client = client
+        end
+
         ##
         # Restricts documents matching the query to return only data for the
         # provided fields.
@@ -962,16 +973,71 @@ module Google
         end
         alias on_snapshot listen
 
+        ##
+        # Serializes the instance to a JSON text string. See also {Query.from_json}.
+        #
+        # @return [String] A JSON text string.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #   query = firestore.col(:cities).select(:population)
+        #
+        #   json = query.to_json
+        #
+        #   new_query = Google::Cloud::Firestore::Query.from_json json, firestore
+        #
+        #   new_query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        def to_json options = nil
+          query_json = Google::Cloud::Firestore::V1::StructuredQuery.encode_json query
+          {
+            "query" => JSON.parse(query_json),
+            "parent_path" => parent_path,
+            "limit_type" => limit_type
+          }.to_json options
+        end
+
+        ##
+        # Deserializes a JSON text string serialized from this class and returns it as a new instance. See also
+        # {#to_json}.
+        #
+        # @param [String] json A JSON text string serialized using {#to_json}.
+        # @param [Google::Cloud::Firestore::Client] client A connected client instance.
+        #
+        # @return [Query] A new query equal to the original query used to create the JSON text string.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #   query = firestore.col(:cities).select(:population)
+        #
+        #   json = query.to_json
+        #
+        #   new_query = Google::Cloud::Firestore::Query.from_json json, firestore
+        #
+        #   new_query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        def self.from_json json, client
+          raise ArgumentError, "client is required" unless client
+
+          json = JSON.parse json
+          query_json = json["query"]
+          raise ArgumentError, "Field 'query' is required" unless query_json
+          query = Google::Cloud::Firestore::V1::StructuredQuery.decode_json query_json.to_json
+          start query, json["parent_path"], client, limit_type: json["limit_type"]&.to_sym
+        end
+
         ##
         # @private Start a new Query.
         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
+          new query, parent_path, client, limit_type: limit_type
         end
 
         protected
@@ -1094,11 +1160,14 @@ module Google
             return snapshot_to_cursor values.first, query
           end
 
+          # The *values param in start_at, start_after, etc. will wrap an array argument in an array, so unwrap it here.
+          values = values.first if values.count == 1 && values.first.is_a?(Array)
+
           # pair values with their field_paths to ensure correct formatting
           order_field_paths = order_by_field_paths query
           if values.count > order_field_paths.count
             # raise if too many values provided for the cursor
-            raise ArgumentError, "too many values"
+            raise ArgumentError, "There cannot be more cursor values than order by fields"
           end
 
           values = values.zip(order_field_paths).map do |value, field_path|
@@ -1130,7 +1199,6 @@ module Google
               snapshot[field_path]
             end
           end
-
           values_to_cursor values, query
         end
 

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

@@ -0,0 +1,80 @@
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+module Google
+  module Cloud
+    module Firestore
+      ##
+      # # QueryPartition
+      #
+      # Represents a split point that can be used in a query as a starting and/or end point for the query results.
+      #
+      # The cursors returned by {#start_at} and {#end_before} can only be used in a query that matches the constraint of
+      # the query that produced this partition.
+      #
+      # See {CollectionGroup#partitions} and {Query}.
+      #
+      # @!attribute [r] start_at
+      #   The cursor values that define the first result for this partition, or `nil` if this is the first partition.
+      #   Returns an array of values that represent a position, in the order they appear in the order by clause of the
+      #   query. Can contain fewer values than specified in the order by clause. Will be used in the query returned by
+      #   {#to_query}.
+      #   @return [Array<Object>, nil] Typically, the values are {DocumentReference} objects.
+      # @!attribute [r] end_before
+      #   The cursor values that define the first result after this partition, or `nil` if this is the last partition.
+      #   Returns an array of values that represent a position, in the order they appear in the order by clause of the
+      #   query.  Can contain fewer values than specified in the order by clause. Will be used in the query returned by
+      #   {#to_query}.
+      #   @return [Array<Object>, nil] Typically, the values are {DocumentReference} objects.
+      #
+      # @example
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #
+      #   col_group = firestore.col_group "cities"
+      #
+      #   partitions = col_group.partitions 3
+      #
+      #   queries = partitions.map(&:to_query)
+      #
+      class QueryPartition
+        attr_reader :start_at
+        attr_reader :end_before
+
+        ##
+        # @private New QueryPartition from query and Cursor
+        def initialize query, start_at, end_before
+          @query = query
+          @start_at = start_at
+          @end_before = end_before
+        end
+
+        ##
+        # Creates a new query that only returns the documents for this partition, using the cursor values from
+        # {#start_at} and {#end_before}.
+        #
+        # @return [Query] The query for the partition.
+        #
+        def to_query
+          base_query = @query
+          base_query = base_query.start_at start_at if start_at
+          base_query = base_query.end_before end_before if end_before
+          base_query
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+module Google
+  module Cloud
+    module Firestore
+      ##
+      # @private
+      #
+      # Represents a resource path to the Firestore API.
+      #
+      class ResourcePath
+        include Comparable
+
+        RESOURCE_PATH_RE = %r{^projects/([^/]*)/databases/([^/]*)(?:/documents/)?([\s\S]*)$}.freeze
+
+        attr_reader :project_id
+        attr_reader :database_id
+        attr_reader :segments
+
+        ##
+        # Creates a resource path object.
+        #
+        # @param [Array<String>] segments One or more strings representing the resource path.
+        #
+        # @return [ResourcePath] The resource path object.
+        #
+        def initialize project_id, database_id, segments
+          @project_id = project_id
+          @database_id = database_id
+          @segments = segments.split "/"
+        end
+
+        def <=> other
+          return nil unless other.is_a? ResourcePath
+          [project_id, database_id, segments] <=> [other.project_id, other.database_id, other.segments]
+        end
+
+        def self.from_path path
+          data = RESOURCE_PATH_RE.match path
+          new data[1], data[2], data[3]
+        end
+      end
+    end
+  end
+end

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

@@ -96,6 +96,20 @@ module Google
           )
         end
 
+        ##
+        # Returns Google::Cloud::Firestore::V1::PartitionQueryResponse
+        def partition_query parent, query_grpc, partition_count, token: nil, max: nil
+          request = Google::Cloud::Firestore::V1::PartitionQueryRequest.new(
+            parent: parent,
+            structured_query: query_grpc,
+            partition_count: partition_count,
+            page_token: token,
+            page_size: max
+          )
+          paged_enum = firestore.partition_query request
+          paged_enum.response
+        end
+
         def run_query path, query_grpc, transaction: nil
           run_query_req = {
             parent:           path,

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

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-firestore
 version: !ruby/object:Gem::Version
-  version: 2.5.1
+  version: 2.6.0
 platform: ruby
 authors:
 - Google Inc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-04-19 00:00:00.000000000 Z
+date: 2021-06-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -227,6 +227,7 @@ files:
 - lib/google/cloud/firestore.rb
 - lib/google/cloud/firestore/batch.rb
 - lib/google/cloud/firestore/client.rb
+- lib/google/cloud/firestore/collection_group.rb
 - lib/google/cloud/firestore/collection_reference.rb
 - lib/google/cloud/firestore/collection_reference_list.rb
 - lib/google/cloud/firestore/commit_response.rb
@@ -242,7 +243,9 @@ files:
 - lib/google/cloud/firestore/generate.rb
 - lib/google/cloud/firestore/query.rb
 - lib/google/cloud/firestore/query_listener.rb
+- lib/google/cloud/firestore/query_partition.rb
 - lib/google/cloud/firestore/query_snapshot.rb
+- lib/google/cloud/firestore/resource_path.rb
 - lib/google/cloud/firestore/service.rb
 - lib/google/cloud/firestore/transaction.rb
 - lib/google/cloud/firestore/version.rb
@@ -269,7 +272,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.13
+rubygems_version: 3.2.17
 signing_key: 
 specification_version: 4
 summary: API Client library for Google Cloud Firestore API