google-cloud-firestore 2.4.0 → 2.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e39fbfebed5714a9eeb9fe9e1e22e8bf0ac29e16b34c1683b0e35bd9bde3d754
-  data.tar.gz: d7a8363434c9e48dc134acbc863020e89d89bcc0af7c95148e4a9f0542a3554c
+  metadata.gz: 91324b3d891244579ee53512847340a286c4cf1727c9a4eb5086966355029c93
+  data.tar.gz: ad3b9d4907e71877a82d72a3d3f7c55952c45e0ea53ecb8becd8bc7569ef4bb9
 SHA512:
-  metadata.gz: 8cd46477f0486ab53708fdae544736b1f7909de2cf707d63cef4c84b017bd360e4e14b4946a62b280614c29374bf063bbaee3f82171e04f7e916db6bc1ccbcec
-  data.tar.gz: 5d8b3303a2aa4f097ce1af9781d308a577f3fcb1054d356982ca9141b9b99cdecbdbc76315d4ed3f97a80825449a7ae06b90407a3a5cbecb282a20cbe38a42e7
+  metadata.gz: b2f11c5888b49916f5383f1a7b46c190e35897e79d376e48f6ef950246fd91179b9f33a05aec1fb932ff72fe262174fca1b5ed4c8d4f8a4e1f3f69b5302bdbaf
+  data.tar.gz: 24bd04f73584eeac0840fc0619c4003284c6193202763e751dd1bbf4c02539f4a44486587953cf90c5bd133377d02d8c871669affeaa9a22e2fa863c6f718f17

data/AUTHENTICATION.md

@@ -95,7 +95,8 @@ client = Google::Cloud::Firestore.new
 
 ### Configuration
 
-The **Project ID** and **Credentials JSON** can be configured instead of placing them in environment variables or providing them as arguments.
+The **Project ID** and the path to the **Credentials JSON** file can be configured
+instead of placing them in environment variables or providing them as arguments.
 
 ```ruby
 require "google/cloud/firestore"

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Release History
 
+### 2.6.1 / 2021-07-08
+
+#### Documentation
+
+* Update AUTHENTICATION.md in handwritten packages
+
+### 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
+
+* Add GRPC::Unknown to retryable errors in Watch::Listener
+
+### 2.5.0 / 2021-03-10
+
+#### Features
+
+* Drop support for Ruby 2.4 and add support for Ruby 3.0
+
+### 2.4.1 / 2021-01-06
+
+#### Bug Fixes
+
+* Replace usage of Write.transform with Write.update_transforms
+
 ### 2.4.0 / 2020-11-19
 
 #### Features

data/CONTRIBUTING.md

@@ -24,7 +24,7 @@ be able to accept your pull requests.
 In order to use the google-cloud-firestore console and run the project's tests,
 there is a small amount of setup:
 
-1. Install Ruby. google-cloud-firestore requires Ruby 2.4+. You may choose to
+1. Install Ruby. google-cloud-firestore requires Ruby 2.5+. You may choose to
    manage your Ruby and gem installations with [RVM](https://rvm.io/),
    [rbenv](https://github.com/rbenv/rbenv), or
    [chruby](https://github.com/postmodern/chruby).
@@ -45,7 +45,7 @@ there is a small amount of setup:
 
    ```sh
    $ cd google-cloud-firestore/
-   $ bundle exec rake bundleupdate
+   $ bundle install
    ```
 
 ## Console
@@ -119,15 +119,14 @@ If you alter an example's title, you may encounter breaking tests.
 ### Firestore Acceptance Tests
 
 The Firestore acceptance tests interact with the live service API. Follow the
-instructions in the {file:AUTHENTICATION.md Authentication guide} for enabling
+instructions in the {file:AUTHENTICATION.md Authentication Guide} for enabling
 the Firestore API. Occasionally, some API features may not yet be generally
 available, making it difficult for some contributors to successfully run the
 entire acceptance test suite. However, please ensure that you do successfully
 run acceptance tests for any code areas covered by your pull request.
 
 To run the acceptance tests, first create and configure a project in the Google
-Developers Console, as described in the {file:AUTHENTICATION.md Authentication
-guide}. Be sure to download the JSON KEY file. Make note of the PROJECT_ID and
+Developers Console, as described in the {file:AUTHENTICATION.md Authentication Guide}. Be sure to download the JSON KEY file. Make note of the PROJECT_ID and
 the KEYFILE location on your system.
 
 Before you can run the Firestore acceptance tests, you must first create indexes

data/LOGGING.md

@@ -3,7 +3,7 @@
 To enable logging for this library, set the logger for the underlying
 [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library. The logger
 that you set may be a Ruby stdlib
-[`Logger`](https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html) as
+[`Logger`](https://ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger.html) as
 shown below, or a
 [`Google::Cloud::Logging::Logger`](https://googleapis.dev/ruby/google-cloud-logging/latest)
 that will write logs to [Stackdriver

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

@@ -119,7 +119,7 @@ module Google
 
           doc_path = coalesce_doc_path_argument doc
 
-          @writes << Convert.writes_for_create(doc_path, data)
+          @writes << Convert.write_for_create(doc_path, data)
 
           nil
         end
@@ -218,7 +218,7 @@ module Google
 
           doc_path = coalesce_doc_path_argument doc
 
-          @writes << Convert.writes_for_set(doc_path, data, merge: merge)
+          @writes << Convert.write_for_set(doc_path, data, merge: merge)
 
           nil
         end
@@ -322,8 +322,7 @@ module Google
 
           doc_path = coalesce_doc_path_argument doc
 
-          @writes << Convert.writes_for_update(doc_path, data,
-                                               update_time: update_time)
+          @writes << Convert.write_for_update(doc_path, data, update_time: update_time)
 
           nil
         end

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"
 
@@ -100,11 +101,11 @@ module Google
         #     puts col.collection_id
         #   end
         #
-        def cols
+        def cols &block
           ensure_service!
           grpc = service.list_collections "#{path}/documents"
           cols_enum = CollectionReferenceList.from_grpc(grpc, self, "#{path}/documents").all
-          cols_enum.each { |c| yield c } if block_given?
+          cols_enum.each(&block) if block_given?
           cols_enum
         end
         alias collections cols
@@ -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
 
@@ -256,7 +250,7 @@ module Google
           ensure_service!
 
           unless block_given?
-            return enum_for :get_all, docs, field_mask: field_mask
+            return enum_for :get_all, *docs, field_mask: field_mask
           end
 
           doc_paths = Array(docs).flatten.map do |doc_path|
@@ -634,9 +628,9 @@ module Google
             commit_return = transaction.commit
             # Conditional return value, depending on truthy commit_response
             commit_response ? commit_return : transaction_return
-          rescue Google::Cloud::UnavailableError => err
+          rescue Google::Cloud::UnavailableError => e
             # Re-raise if retried more than the max
-            raise err if backoff[:current] > backoff[:max]
+            raise e if backoff[:current] > backoff[:max]
 
             # Sleep with incremental backoff before restarting
             sleep backoff[:delay]
@@ -649,18 +643,18 @@ module Google
             transaction = Transaction.from_client \
               self, previous_transaction: transaction.transaction_id
             retry
-          rescue Google::Cloud::InvalidArgumentError => err
+          rescue Google::Cloud::InvalidArgumentError => e
             # Return if a previous call was retried but ultimately succeeded
-            return nil if backoff[:current] > 0
+            return nil if backoff[:current].positive?
 
             # Re-raise error.
-            raise err
-          rescue StandardError => err
+            raise e
+          rescue StandardError => e
             # Rollback transaction when handling unexpected error
             transaction.rollback rescue nil
 
             # Re-raise error.
-            raise err
+            raise e
           end
         end
 

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/collection_reference_list.rb

@@ -90,17 +90,17 @@ module Google
         #     collection_reference.collection_id
         #   end
         #
-        def all request_limit: nil
+        def all request_limit: nil, &block
           request_limit = request_limit.to_i if request_limit
           unless block_given?
             return enum_for :all, request_limit: request_limit
           end
           results = self
           loop do
-            results.each { |r| yield r }
+            results.each(&block)
             if request_limit
               request_limit -= 1
-              break if request_limit < 0
+              break if request_limit.negative?
             end
             break unless results.next?
             results = results.next