google-cloud-firestore 0.23.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c249cbd2bcfd378c5ab77ce2b5e717f629e741ca8c30b259897cfcd87ca732a
-  data.tar.gz: 90d335ef83762a548eefdc4ed2a35ea5c5c830a1069bd7b969e67a704496cf3b
+  metadata.gz: 00fbe5394269dbb40b8e8927b0d143313a9e6b455896bd92480a5eacb101aee0
+  data.tar.gz: 6d367282da3a195148e3fbf8b12aa1c9ac8072a173701c4c74a5cd4d6b0e8a13
 SHA512:
-  metadata.gz: 4f8c8534c873bf3b86e8bccce74529c69ffebb5ba14e377ad60e0b32ae319ae22d8b96ff3eece237786952d169f49210168f3243a220e963b363d740c84aa54f
-  data.tar.gz: e0ae957a20ae64ae3c26cc6f379c12080fb8d71cf6b30bc0e4717787e7fadf785dcd5694a5d2422477639cb971da33715f21dae5f20613f490dd8a3ab5d9b1ba
+  metadata.gz: 58a61fa56539fd6c0ca97d25646b6ece469ae060f0a88f7e43e7c9e0bab59aebe26aa8033e0f7b89c410f2b6e5a1a19b6e154264e255feaf8f1794c03018ca50
+  data.tar.gz: 64080bb166add40d86a2541277c45b77f297115b3b805a458fea896a2dedc873bfbfc0a7d9a6b4501303721a4f03e99016bad64ec998a4dedbdfde547fbfeae5

data/.yardopts

@@ -1,9 +1,17 @@
 --no-private
 --title=Google Cloud Firestore API
---exclude lib/google/firestore/v1beta1
+--exclude _pb\.rb$
 --markup markdown
 --markup-provider redcarpet
+--main OVERVIEW.md
 
 ./lib/**/*.rb
 -
-README.md
+OVERVIEW.md
+AUTHENTICATION.md
+LOGGING.md
+CONTRIBUTING.md
+TROUBLESHOOTING.md
+CHANGELOG.md
+CODE_OF_CONDUCT.md
+LICENSE

data/README.md

@@ -11,7 +11,7 @@ steps:
 
 1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
 2. [Enable the Google Cloud Firestore API.](https://console.cloud.google.com/apis/api/firestore)
-3. [Setup Authentication.](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud/master/guides/authentication)
+3. [Setup Authentication.](https://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-firestore/latest/file.AUTHENTICATION)
 
 ### Installation
 ```
@@ -28,7 +28,7 @@ $ gem install google-cloud-firestore
 
 ## Enabling Logging
 
-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 shown below, or a [`Google::Cloud::Logging::Logger`](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest/google/cloud/logging/logger) that will write logs to [Stackdriver Logging](https://cloud.google.com/logging/). See [grpc/logconfig.rb](https://github.com/grpc/grpc/blob/master/src/ruby/lib/grpc/logconfig.rb) and the gRPC [spec_helper.rb](https://github.com/grpc/grpc/blob/master/src/ruby/spec/spec_helper.rb) for additional information.
+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 shown below, or a [`Google::Cloud::Logging::Logger`](https://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-logging/latest/Google/Cloud/Logging/Logger) that will write logs to [Stackdriver Logging](https://cloud.google.com/logging/). See [grpc/logconfig.rb](https://github.com/grpc/grpc/blob/master/src/ruby/lib/grpc/logconfig.rb) and the gRPC [spec_helper.rb](https://github.com/grpc/grpc/blob/master/src/ruby/spec/spec_helper.rb) for additional information.
 
 Configuring a Ruby stdlib logger:
 
@@ -59,5 +59,5 @@ and later. Older versions of Ruby _may_ still work, but are unsupported and not
 recommended. See https://www.ruby-lang.org/en/downloads/branches/ for details
 about the Ruby support schedule.
 
-[Client Library Documentation]: https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-firestore/latest/google/firestore/v1beta1
-[Product Documentation]: https://cloud.google.com/firestore
+[Client Library Documentation]: https://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-firestore/latest
+[Product Documentation]: https://cloud.google.com/firestore

data/lib/google-cloud-firestore.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 ##
 # This file is here to be autorequired by bundler, so that the .firestore and
 # #firestore methods can be available, but the library and all dependencies
@@ -29,8 +30,8 @@ module Google
     # Creates a new object for connecting to the Firestore service.
     # Each call creates a new connection.
     #
-    # For more information on connecting to Google Cloud see the [Authentication
-    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    # For more information on connecting to Google Cloud see the
+    # {file:AUTHENTICATION.md Authentication Guide}.
     #
     # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
     #   set of resources and operations that the connection can access. See
@@ -69,8 +70,8 @@ module Google
     # Creates a new object for connecting to the Firestore service.
     # Each call creates a new connection.
     #
-    # For more information on connecting to Google Cloud see the [Authentication
-    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    # For more information on connecting to Google Cloud see the
+    # {file:AUTHENTICATION.md Authentication Guide}.
     #
     # @param [String] project_id Identifier for a Firestore project. If not
     #   present, the default project for the credentials is used.

data/lib/google/cloud/firestore.rb

@@ -29,509 +29,7 @@ module Google
     # databases, as a NoSQL database it differs from them in the way it
     # describes relationships between data objects.
     #
-    # For more information about Cloud Firestore, read the [Cloud
-    # Firestore Documentation](https://cloud.google.com/firestore/docs/).
-    #
-    # The goal of google-cloud is to provide an API that is comfortable to
-    # Rubyists. Authentication is handled by {Google::Cloud#firestore}. You can
-    # provide the project and credential information to connect to the Cloud
-    # Firestore service, or if you are running on Google Compute Engine this
-    # configuration is taken care of for you. You can read more about the
-    # options for connecting in the [Authentication
-    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
-    #
-    # ## Enabling Logging
-    #
-    # 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 shown below, or a
-    # [`Google::Cloud::Logging::Logger`](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest/google/cloud/logging/logger)
-    # that will write logs to [Stackdriver
-    # Logging](https://cloud.google.com/logging/). See
-    # [grpc/logconfig.rb](https://github.com/grpc/grpc/blob/master/src/ruby/lib/grpc/logconfig.rb)
-    # and the gRPC
-    # [spec_helper.rb](https://github.com/grpc/grpc/blob/master/src/ruby/spec/spec_helper.rb)
-    # for additional information.
-    #
-    # Configuring a Ruby stdlib logger:
-    #
-    # ```ruby
-    # require "logger"
-    #
-    # module MyLogger
-    #   LOGGER = Logger.new $stderr, level: Logger::WARN
-    #   def logger
-    #     LOGGER
-    #   end
-    # end
-    #
-    # # Define a gRPC module-level logger method before grpc/logconfig.rb loads.
-    # module GRPC
-    #   extend MyLogger
-    # end
-    # ```
-    #
-    # ## Adding data
-    #
-    # Cloud Firestore stores data in Documents, which are stored in Collections.
-    # Cloud Firestore creates collections and documents implicitly the first
-    # time you add data to the document. (For more information, see [Adding Data
-    # to Cloud Firestore](https://cloud.google.com/firestore/docs/manage-data/add-data).
-    #
-    # To create or overwrite a single document, use {Firestore::Client#doc} to
-    # obtain a document reference. (This does not create a document in Cloud
-    # Firestore.) Then, call {Firestore::DocumentReference#set} to create the
-    # document or overwrite an existing document:
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # # Get a document reference
-    # nyc_ref = firestore.doc "cities/NYC"
-    #
-    # nyc_ref.set({ name: "New York City" }) # Document created
-    # ```
-    #
-    # When you use this combination of `doc` and `set` to create a new document,
-    # you must specify an ID for the document. (In the example above, the ID is
-    # "NYC".) However, if you do not have a meaningful ID for the document, you
-    # may omit the ID from a call to {Firestore::CollectionReference#doc}, and
-    # Cloud Firestore will auto-generate an ID for you.
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # # Get a collection reference
-    # cities_col = firestore.col "cities"
-    #
-    # # Get a document reference with data
-    # random_ref = cities_col.doc
-    # random_ref.set({ name: "New York City" })
-    #
-    # # The document ID is randomly generated
-    # random_ref.document_id #=> "RANDOMID123XYZ"
-    # ```
-    #
-    # You can perform both of the operations shown above, auto-generating
-    # an ID and creating the document, in a single call to
-    # {Firestore::CollectionReference#add}.
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # # Get a collection reference
-    # cities_col = firestore.col "cities"
-    #
-    # # Get a document reference with data
-    # random_ref = cities_col.add({ name: "New York City" })
-    #
-    # # The document ID is randomly generated
-    # random_ref.document_id #=> "RANDOMID123XYZ"
-    # ```
-    #
-    # You can also use `add` to create an empty document:
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # # Get a collection reference
-    # cities_col = firestore.col "cities"
-    #
-    # # Create a document without data
-    # random_ref = cities_col.add
-    #
-    # # The document ID is randomly generated
-    # random_ref.document_id #=> "RANDOMID123XYZ"
-    # ```
-    #
-    # ## Retrieving collection references
-    #
-    # Collections are simply named containers for documents. A collection
-    # contains documents and nothing else. It can't directly contain raw fields
-    # with values, and it can't contain other collections. You do not need to
-    # "create" or "delete" collections. After you create the first document in a
-    # collection, the collection exists. If you delete all of the documents in a
-    # collection, it no longer exists. (For more information, see [Cloud
-    # Firestore Data Model](https://cloud.google.com/firestore/docs/data-model).
-    #
-    # Use {Firestore::Client#cols} to list the root-level collections:
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # # Get the root collections
-    # firestore.cols.each do |col|
-    #   puts col.collection_id
-    # end
-    # ```
-    #
-    # Retrieving a reference to a single root-level collection is similar:
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # # Get the cities collection
-    # cities_col = firestore.col "cities"
-    # ```
-    #
-    # To list the collections in a document, first get the document reference,
-    # then use {Firestore::DocumentReference#cols}:
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # # Get a document reference
-    # nyc_ref = firestore.doc "cities/NYC"
-    #
-    # nyc_ref.cols.each do |col|
-    #   puts col.collection_id
-    # end
-    # ```
-    #
-    # Again, retrieving a reference to a single collection is similar::
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # # Get a document reference
-    # nyc_ref = firestore.doc "cities/NYC"
-    #
-    # # Get precincts sub-collection
-    # precincts_col = nyc_ref.col "precincts"
-    # ```
-    #
-    # ## Reading data
-    #
-    # You can retrieve a snapshot of the data in a single document with
-    # {Firestore::DocumentReference#get}, which returns an instance of
-    # {Firestore::DocumentSnapshot}:
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # # Get a document reference
-    # nyc_ref = firestore.doc "cities/NYC"
-    #
-    # nyc_snap = nyc_ref.get
-    # nyc_snap[:population] #=> 1000000
-    # ```
-    # In the example above, {Firestore::DocumentSnapshot#[]} is used to access a
-    # top-level field. To access nested fields, use {Firestore::FieldPath}:
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # user_snap = firestore.doc("users/frank").get
-    #
-    # nested_field_path = firestore.field_path :favorites, :food
-    # user_snap.get(nested_field_path) #=> "Pizza"
-    # ```
-    #
-    # Or, use {Firestore::Client#get_all} to retrieve a list of document
-    # snapshots (data):
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # # Get and print city documents
-    # cities = ["cities/NYC", "cities/SF", "cities/LA"]
-    # firestore.get_all(cities).each do |city|
-    #   puts "#{city.document_id} has #{city[:population]} residents."
-    # end
-    # ```
-    #
-    # To retrieve all of the document snapshots in a collection, use
-    # {Firestore::CollectionReference#get}:
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # # Get a collection reference
-    # cities_col = firestore.col "cities"
-    #
-    # # Get and print all city documents
-    # cities_col.get do |city|
-    #   puts "#{city.document_id} has #{city[:population]} residents."
-    # end
-    # ```
-    #
-    # The example above is actually a simple query without filters. Let's look
-    # at some other queries for Cloud Firestore.
-    #
-    # ## Querying data
-    #
-    # Use {Firestore::Query#where} to filter queries on a field:
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # # Get a collection reference
-    # cities_col = firestore.col "cities"
-    #
-    # # Create a query
-    # query = cities_col.where(:population, :>=, 1000000)
-    #
-    # query.get do |city|
-    #   puts "#{city.document_id} has #{city[:population]} residents."
-    # end
-    # ```
-    #
-    # You can order the query results with {Firestore::Query#order}:
-    #
-    # ```ruby
-    # 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)
-    #
-    # query.get do |city|
-    #   puts "#{city.document_id} has #{city[:population]} residents."
-    # end
-    # ```
-    #
-    # Query methods may be chained, as in this example using
-    # {Firestore::Query#limit} and  {Firestore::Query#offset} to perform
-    # pagination:
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # # Get a collection reference
-    # cities_col = firestore.col "cities"
-    #
-    # # Create a query
-    # query = cities_col.limit(5).offset(10)
-    #
-    # query.get do |city|
-    #   puts "#{city.document_id} has #{city[:population]} residents."
-    # end
-    # ```
-    #
-    # See [Managing Indexes in Cloud
-    # Firestore](https://cloud.google.com/firestore/docs/query-data/indexing) to
-    # ensure the best performance for your queries.
-    #
-    # ## Updating data
-    #
-    # You can use {Firestore::DocumentReference#set} to completely overwrite an
-    # existing document:
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # # Get a document reference
-    # nyc_ref = firestore.doc "cities/NYC"
-    #
-    # nyc_ref.set({ name: "New York City" })
-    # ```
-    #
-    # Or, to selectively update only the fields appearing in your `data`
-    # argument, set the `merge` option to `true`:
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # # Get a document reference
-    # nyc_ref = firestore.doc "cities/NYC"
-    #
-    # nyc_ref.set({ name: "New York City" }, merge: true)
-    # ```
-    #
-    # Use {Firestore::DocumentReference#update} to directly update a
-    # deeply-nested field with a {Firestore::FieldPath}:
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # user_ref = firestore.doc "users/frank"
-    #
-    # nested_field_path = firestore.field_path :favorites, :food
-    # user_ref.update({ nested_field_path => "Pasta" })
-    # ```
-    #
-    # ### Listening for changes
-    #
-    # You can listen to a document reference or a collection reference/query for
-    # changes. The current document snapshot or query results snapshot will be
-    # yielded first, and each time the contents change.
-    #
-    # You can use {Firestore::DocumentReference#listen} to be notified of
-    # changes to a single document:
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # # Get a document reference
-    # nyc_ref = firestore.doc "cities/NYC"
-    #
-    # listener = nyc_ref.listen do |snapshot|
-    #   puts "The population of #{snapshot[:name]} "
-    #   puts "is #{snapshot[:population]}."
-    # end
-    #
-    # # When ready, stop the listen operation and close the stream.
-    # listener.stop
-    # ```
-    #
-    # You can use {Firestore::Query#listen} to be notified of changes to any
-    # document contained in the query:
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # # Create a query
-    # query = firestore.col(:cities).order(:population, :desc)
-    #
-    # listener = query.listen do |snapshot|
-    #   puts "The query snapshot has #{snapshot.docs.count} documents "
-    #   puts "and has #{snapshot.changes.count} changes."
-    # end
-    #
-    # # When ready, stop the listen operation and close the stream.
-    # listener.stop
-    # ```
-    #
-    # ## Using transactions and batched writes
-    #
-    # Cloud Firestore supports atomic operations for reading and writing data.
-    # In a set of atomic operations, either all of the operations succeed, or
-    # none of them are applied. There are two types of atomic operations in
-    # Cloud Firestore: A transaction is a set of read and write operations on
-    # one or more documents, while a batched write is a set of only write
-    # operations on one or more documents. (For more information, see
-    # [Transactions and Batched Writes](https://cloud.google.com/firestore/docs/manage-data/transactions).
-    #
-    # ### Transactions
-    #
-    # A transaction consists of any number of read operations followed by any
-    # number of write operations. (Read operations must always come before write
-    # operations.) In the case of a concurrent update by another client, Cloud
-    # Firestore runs the entire transaction again. Therefore, transaction blocks
-    # should be idempotent and should not not directly modify application state.
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # city = firestore.col("cities").doc("SF")
-    # city.set({ name: "San Francisco",
-    #            state: "CA",
-    #            country: "USA",
-    #            capital: false,
-    #            population: 860000 })
-    #
-    # firestore.transaction do |tx|
-    #   new_population = tx.get(city).data[:population] + 1
-    #   tx.update(city, { population: new_population })
-    # end
-    # ```
-    #
-    # ### Batched writes
-    #
-    # If you do not need to read any documents in your operation set, you can
-    # execute multiple write operations as a single batch. A batch of writes
-    # completes atomically and can write to multiple documents. Batched writes
-    # are also useful for migrating large data sets to Cloud Firestore.
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # firestore.batch do |b|
-    #   # Set the data for NYC
-    #   b.set("cities/NYC", { name: "New York City" })
-    #
-    #   # Update the population for SF
-    #   b.update("cities/SF", { population: 1000000 })
-    #
-    #   # Delete LA
-    #   b.delete("cities/LA")
-    # end
-    # ```
-    #
-    # ## Deleting data
-    #
-    # Use {Firestore::DocumentReference#delete} to delete a document from Cloud
-    # Firestore:
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # # Get a document reference
-    # nyc_ref = firestore.doc "cities/NYC"
-    #
-    # nyc_ref.delete
-    # ```
-    #
-    # To delete specific fields from a document, use the
-    # {Firestore::Client.field_delete} method when you update a document:
-    #
-    # ```ruby
-    # require "google/cloud/firestore"
-    #
-    # firestore = Google::Cloud::Firestore.new
-    #
-    # # Get a document reference
-    # nyc_ref = firestore.doc "cities/NYC"
-    #
-    # nyc_ref.update({ name: "New York City",
-    #                  trash: firestore.field_delete })
-    # ```
-    #
-    # To delete an entire collection or sub-collection in Cloud Firestore,
-    # retrieve all the documents within the collection or sub-collection and
-    # delete them. If you have larger collections, you may want to delete the
-    # documents in smaller batches to avoid out-of-memory errors. Repeat the
-    # process until you've deleted the entire collection or sub-collection.
+    # See {file:OVERVIEW.md Firestore Overview}.
     #
     module Firestore
       ##
@@ -539,8 +37,7 @@ module Google
       # Each call creates a new connection.
       #
       # For more information on connecting to Google Cloud see the
-      # [Authentication
-      # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+      # {file:AUTHENTICATION.md Authentication Guide}.
       #
       # @param [String] project_id Identifier for a Firestore project. If not
       #   present, the default project for the credentials is used.