google-cloud-firestore 0.24.0 → 0.24.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00fbe5394269dbb40b8e8927b0d143313a9e6b455896bd92480a5eacb101aee0
-  data.tar.gz: 6d367282da3a195148e3fbf8b12aa1c9ac8072a173701c4c74a5cd4d6b0e8a13
+  metadata.gz: 8fccde9d0d32a88be624c95255dcdcbede69be371428e9f5dc3d7e6e4b59b541
+  data.tar.gz: a761abb15eb952a1f555746f8fe2a0ebe2e821954c4f65e55711a270c2c903de
 SHA512:
-  metadata.gz: 58a61fa56539fd6c0ca97d25646b6ece469ae060f0a88f7e43e7c9e0bab59aebe26aa8033e0f7b89c410f2b6e5a1a19b6e154264e255feaf8f1794c03018ca50
-  data.tar.gz: 64080bb166add40d86a2541277c45b77f297115b3b805a458fea896a2dedc873bfbfc0a7d9a6b4501303721a4f03e99016bad64ec998a4dedbdfde547fbfeae5
+  metadata.gz: 54d896bf21cffe74009963af0d9a2eebbe187e4e27f1ba4dff85ecc933790e506fb0d3f5729dfc7600dbe3c9a10f14f9729b1e7d494c5944534b1a4444fff33c
+  data.tar.gz: 162b854a6bdfe533535b4626b0b3a3669b8c8aa159c21279bb42ec333da840e87d6d32d147e350c5f335aa62a8b883e21491ba46498d9afd1ff1ff84b8d6ae50

data/AUTHENTICATION.md

@@ -0,0 +1,178 @@
+# Authentication
+
+In general, the google-cloud-firestore library uses [Service
+Account](https://cloud.google.com/iam/docs/creating-managing-service-accounts)
+credentials to connect to Google Cloud services. When running on Compute Engine
+the credentials will be discovered automatically. When running on other
+environments, the Service Account credentials can be specified by providing the
+path to the [JSON
+keyfile](https://cloud.google.com/iam/docs/managing-service-account-keys) for
+the account (or the JSON itself) in environment variables. Additionally, Cloud
+SDK credentials can also be discovered automatically, but this is only
+recommended during development.
+
+## Project and Credential Lookup
+
+The google-cloud-firestore library aims to make authentication as simple as
+possible, and provides several mechanisms to configure your system without
+providing **Project ID** and **Service Account Credentials** directly in code.
+
+**Project ID** is discovered in the following order:
+
+1. Specify project ID in method arguments
+2. Specify project ID in configuration
+3. Discover project ID in environment variables
+4. Discover GCE project ID
+
+**Credentials** are discovered in the following order:
+
+1. Specify credentials in method arguments
+2. Specify credentials in configuration
+3. Discover credentials path in environment variables
+4. Discover credentials JSON in environment variables
+5. Discover credentials file in the Cloud SDK's path
+6. Discover GCE credentials
+
+### Google Cloud Platform environments
+
+While running on Google Cloud Platform environments such as Google Compute
+Engine, Google App Engine and Google Kubernetes Engine, no extra work is needed.
+The **Project ID** and **Credentials** and are discovered automatically. Code
+should be written as if already authenticated. Just be sure when you [set up the
+GCE instance][gce-how-to], you add the correct scopes for the APIs you want to
+access. For example:
+
+  * **All APIs**
+    * `https://www.googleapis.com/auth/cloud-platform`
+    * `https://www.googleapis.com/auth/cloud-platform.read-only`
+  * **BigQuery**
+    * `https://www.googleapis.com/auth/bigquery`
+    * `https://www.googleapis.com/auth/bigquery.insertdata`
+  * **Compute Engine**
+    * `https://www.googleapis.com/auth/compute`
+  * **Datastore**
+    * `https://www.googleapis.com/auth/datastore`
+    * `https://www.googleapis.com/auth/userinfo.email`
+  * **DNS**
+    * `https://www.googleapis.com/auth/ndev.clouddns.readwrite`
+  * **Pub/Sub**
+    * `https://www.googleapis.com/auth/pubsub`
+  * **Storage**
+    * `https://www.googleapis.com/auth/devstorage.full_control`
+    * `https://www.googleapis.com/auth/devstorage.read_only`
+    * `https://www.googleapis.com/auth/devstorage.read_write`
+
+### Environment Variables
+
+The **Project ID** and **Credentials JSON** can be placed in environment
+variables instead of declaring them directly in code. Each service has its own
+environment variable, allowing for different service accounts to be used for
+different services. (See the READMEs for the individual service gems for
+details.) The path to the **Credentials JSON** file can be stored in the
+environment variable, or the **Credentials JSON** itself can be stored for
+environments such as Docker containers where writing files is difficult or not
+encouraged.
+
+The environment variables that Firestore checks for project ID are:
+
+1. `FIRESTORE_PROJECT`
+2. `GOOGLE_CLOUD_PROJECT`
+
+The environment variables that Firestore checks for credentials are configured on {Google::Cloud::Firestore::V1beta1::Credentials}:
+
+1. `FIRESTORE_CREDENTIALS` - Path to JSON file, or JSON contents
+2. `FIRESTORE_KEYFILE` - Path to JSON file, or JSON contents
+3. `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents
+4. `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents
+5. `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file
+
+```ruby
+require "google/cloud/firestore"
+
+ENV["FIRESTORE_PROJECT"]     = "my-project-id"
+ENV["FIRESTORE_CREDENTIALS"] = "path/to/keyfile.json"
+
+firestore = 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.
+
+```ruby
+require "google/cloud/firestore"
+
+Google::Cloud::Firestore.configure do |config|
+  config.project_id  = "my-project-id"
+  config.credentials = "path/to/keyfile.json"
+end
+
+firestore = Google::Cloud::Firestore.new
+```
+
+### Cloud SDK
+
+This option allows for an easy way to authenticate during development. If
+credentials are not provided in code or in environment variables, then Cloud SDK
+credentials are discovered.
+
+To configure your system for this, simply:
+
+1. [Download and install the Cloud SDK](https://cloud.google.com/sdk)
+2. Authenticate using OAuth 2.0 `$ gcloud auth login`
+3. Write code as if already authenticated.
+
+**NOTE:** This is _not_ recommended for running in production. The Cloud SDK
+*should* only be used during development.
+
+[gce-how-to]: https://cloud.google.com/compute/docs/authentication#using
+[dev-console]: https://console.cloud.google.com/project
+
+[enable-apis]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/enable-apis.png
+
+[create-new-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account.png
+[create-new-service-account-existing-keys]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account-existing-keys.png
+[reuse-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/reuse-service-account.png
+
+## Creating a Service Account
+
+Google Cloud requires a **Project ID** and **Service Account Credentials** to
+connect to the APIs. You will use the **Project ID** and **JSON key file** to
+connect to most services with google-cloud-firestore.
+
+If you are not running this client on Google Compute Engine, you need a Google
+Developers service account.
+
+1. Visit the [Google Developers Console][dev-console].
+1. Create a new project or click on an existing project.
+1. Activate the slide-out navigation tray and select **API Manager**. From
+   here, you will enable the APIs that your application requires.
+
+   ![Enable the APIs that your application requires][enable-apis]
+
+   *Note: You may need to enable billing in order to use these services.*
+
+1. Select **Credentials** from the side navigation.
+
+   You should see a screen like one of the following.
+
+   ![Create a new service account][create-new-service-account]
+
+   ![Create a new service account With Existing Keys][create-new-service-account-existing-keys]
+
+   Find the "Add credentials" drop down and select "Service account" to be
+   guided through downloading a new JSON key file.
+
+   If you want to re-use an existing service account, you can easily generate a
+   new key file. Just select the account you wish to re-use, and click "Generate
+   new JSON key":
+
+   ![Re-use an existing service account][reuse-service-account]
+
+   The key file you download will be used by this library to authenticate API
+   requests and should be stored in a secure location.
+
+## Troubleshooting
+
+If you're having trouble authenticating you can ask for help by following the
+{file:TROUBLESHOOTING.md Troubleshooting Guide}.

data/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Release History
+
+### 0.24.1 / 2018-09-12
+
+* Add missing documentation files to package.
+
+### 0.24.0 / 2018-09-10
+
+* Add array_union and array_delete FieldValue configuration.
+* Add array-contains as an operator to the Query#where method.
+* Update documentation.
+
+### 0.23.0 / 2018-08-17
+
+* Add Firestore Watch
+  * A document reference or a collection reference/query can now be
+    listened to for changes.
+  * The following methods were added:
+    * DocumentReference#listen
+    * Query#listen
+  * The following classes were added:
+    * DocumentSnapshot
+    * DocumentChange
+    * DocumentListener
+    * QuerySnapshot
+    * QueryListener
+* Support DocumentSnapshot objects as cursors.
+* Fix mapping of geo Hash to GeoPoint resource.
+* Query#select is no longer additive, it now replaces any previously
+  selected fields.
+* Documentation updates.
+
+### 0.22.0 / 2018-07-05
+
+* Remove Base64 encoding for BYTES values, as it is unnecessary for gRPC endpoints.
+* Add documentation for enabling gRPC logging.
+
+### 0.21.1 / 2018-05-24
+
+* Fix bug where some DocumentReference/DocumentSnapshot actions
+  were failing due to a bad object configuration.
+* Updates to documentation and code examples.
+
+### 0.21.0 / 2018-02-27
+
+* Add Shared Configuration.
+
+### 0.20.0 / 2018-01-10
+
+* First release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,40 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct. By adopting this Code of Conduct, project
+maintainers commit themselves to fairly and consistently applying these
+principles to every aspect of managing this project. Project maintainers who do
+not follow or enforce the Code of Conduct may be permanently removed from the
+project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by opening an issue or contacting one or more of the project
+maintainers.
+
+This Code of Conduct is adapted from the [Contributor
+Covenant](http://contributor-covenant.org), version 1.2.0, available at
+[http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/)

data/CONTRIBUTING.md

@@ -0,0 +1,188 @@
+# Contributing to Google Cloud Firestore
+
+1. **Sign one of the contributor license agreements below.**
+2. Fork the repo, develop and test your code changes.
+3. Send a pull request.
+
+## Contributor License Agreements
+
+Before we can accept your pull requests you'll need to sign a Contributor
+License Agreement (CLA):
+
+- **If you are an individual writing original source code** and **you own the
+  intellectual property**, then you'll need to sign an [individual
+  CLA](https://developers.google.com/open-source/cla/individual).
+- **If you work for a company that wants to allow you to contribute your work**,
+  then you'll need to sign a [corporate
+  CLA](https://developers.google.com/open-source/cla/corporate).
+
+You can sign these electronically (just scroll to the bottom). After that, we'll
+be able to accept your pull requests.
+
+## Setup
+
+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.3+. 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).
+
+2. Install [Bundler](http://bundler.io/).
+
+   ```sh
+   $ gem install bundler
+   ```
+
+3. Install the top-level project dependencies.
+
+   ```sh
+   $ bundle install
+   ```
+
+4. Install the Firestore dependencies.
+
+   ```sh
+   $ cd google-cloud-firestore/
+   $ bundle exec rake bundleupdate
+   ```
+
+## Console
+
+In order to run code interactively, you can automatically load
+google-cloud-firestore and its dependencies in IRB. This requires that your
+developer environment has already been configured by following the steps
+described in the {file:AUTHENTICATION.md Authentication Guide}. An IRB console
+can be created with:
+
+```sh
+$ cd google-cloud-firestore/
+$ bundle exec rake console
+```
+
+## Firestore Tests
+
+Tests are very important part of google-cloud-firestore. All contributions
+should include tests that ensure the contributed code behaves as expected.
+
+To run the unit tests, documentation tests, and code style checks together for a
+package:
+
+``` sh
+$ cd google-cloud-firestore/
+$ bundle exec rake ci
+```
+
+To run the command above, plus all acceptance tests, use `rake ci:acceptance` or
+its handy alias, `rake ci:a`.
+
+### Firestore Unit Tests
+
+
+The project uses the [minitest](https://github.com/seattlerb/minitest) library,
+including [specs](https://github.com/seattlerb/minitest#specs),
+[mocks](https://github.com/seattlerb/minitest#mocks) and
+[minitest-autotest](https://github.com/seattlerb/minitest-autotest).
+
+To run the Firestore unit tests:
+
+``` sh
+$ cd google-cloud-firestore/
+$ bundle exec rake test
+```
+
+### Firestore Documentation Tests
+
+The project tests the code examples in the gem's
+[YARD](https://github.com/lsegal/yard)-based documentation.
+
+The example testing functions in a way that is very similar to unit testing, and
+in fact the library providing it,
+[yard-doctest](https://github.com/p0deje/yard-doctest), is based on the
+project's unit test library, [minitest](https://github.com/seattlerb/minitest).
+
+To run the Firestore documentation tests:
+
+``` sh
+$ cd google-cloud-firestore/
+$ bundle exec rake doctest
+```
+
+If you add, remove or modify documentation examples when working on a pull
+request, you may need to update the setup for the tests. The stubs and mocks
+required to run the tests are located in `support/doctest_helper.rb`. Please
+note that much of the setup is matched by the title of the
+[`@example`](http://www.rubydoc.info/gems/yard/file/docs/Tags.md#example) tag.
+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
+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
+the KEYFILE location on your system.
+
+Before you can run the Firestore acceptance tests, you must first create indexes
+used in the tests.
+
+#### Running the Firestore acceptance tests
+
+To run the Firestore acceptance tests:
+
+``` sh
+$ cd google-cloud-firestore/
+$ bundle exec rake acceptance[\\{my-project-id},\\{/path/to/keyfile.json}]
+```
+
+Or, if you prefer you can store the values in the `GCLOUD_TEST_PROJECT` and
+`GCLOUD_TEST_KEYFILE` environment variables:
+
+``` sh
+$ cd google-cloud-firestore/
+$ export GCLOUD_TEST_PROJECT=\\{my-project-id}
+$ export GCLOUD_TEST_KEYFILE=\\{/path/to/keyfile.json}
+$ bundle exec rake acceptance
+```
+
+If you want to use a different project and credentials for acceptance tests, you
+can use the more specific `FIRESTORE_TEST_PROJECT`  and `FIRESTORE_TEST_KEYFILE`
+environment variables:
+
+``` sh
+$ cd google-cloud-firestore/
+$ export FIRESTORE_TEST_PROJECT=\\{my-project-id}
+$ export FIRESTORE_TEST_KEYFILE=\\{/path/to/keyfile.json}
+$ bundle exec rake acceptance
+```
+
+## Coding Style
+
+Please follow the established coding style in the library. The style is is
+largely based on [The Ruby Style
+Guide](https://github.com/bbatsov/ruby-style-guide) with a few exceptions based
+on seattle-style:
+
+* Avoid parenthesis when possible, including in method definitions.
+* Always use double quotes strings. ([Option
+  B](https://github.com/bbatsov/ruby-style-guide#strings))
+
+You can check your code against these rules by running Rubocop like so:
+
+```sh
+$ cd google-cloud-firestore/
+$ bundle exec rake rubocop
+```
+
+## Code of Conduct
+
+Please note that this project is released with a Contributor Code of Conduct. By
+participating in this project you agree to abide by its terms. See
+{file:CODE_OF_CONDUCT.md Code of Conduct} for more information.

data/LOGGING.md

@@ -0,0 +1,32 @@
+# Enabling gRPC 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
+```

data/OVERVIEW.md

@@ -0,0 +1,491 @@
+# Cloud Firestore
+
+Cloud Firestore is a NoSQL document database built for automatic scaling, high
+performance, and ease of application development. While the Cloud Firestore
+interface has many of the same features as traditional 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.new Firestore.new}. 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 {file:AUTHENTICATION.md Authentication Guide}.
+
+## 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
+{Google::Cloud::Firestore::Client#doc Client#doc} to obtain a document
+reference. (This does not create a document in Cloud Firestore.) Then, call
+{Google::Cloud::Firestore::DocumentReference#set 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 {Google::Cloud::Firestore::CollectionReference#doc
+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
+{Google::Cloud::Firestore::CollectionReference#add 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 {Google::Cloud::Firestore::Client#cols 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 {Google::Cloud::Firestore::DocumentReference#cols 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
+{Google::Cloud::Firestore::DocumentReference#get DocumentReference#get}, which
+returns an instance of {Google::Cloud::Firestore::DocumentSnapshot
+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, {Google::Cloud::Firestore::DocumentSnapshot#[]
+DocumentSnapshot#[]} is used to access a top-level field. To access nested
+fields, use {Google::Cloud::Firestore::FieldPath 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 {Google::Cloud::Firestore::Client#get_all 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
+{Google::Cloud::Firestore::CollectionReference#get 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 {Google::Cloud::Firestore::Query#where 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 {Google::Cloud::Firestore::Query#order
+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
+{Google::Cloud::Firestore::Query#limit Query#limit} and
+{Google::Cloud::Firestore::Query#offset 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 {Google::Cloud::Firestore::DocumentReference#set
+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 {Google::Cloud::Firestore::DocumentReference#update
+DocumentReference#update} to directly update a deeply-nested field with a
+{Google::Cloud::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 {Google::Cloud::Firestore::DocumentReference#listen
+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 {Google::Cloud::Firestore::Query#listen 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 {Google::Cloud::Firestore::DocumentReference#delete
+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
+{Google::Cloud::Firestore::Client.field_delete 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.
+
+## Additional information
+
+Google Firestore can be configured to use gRPC's logging. To learn more, see the
+{file:LOGGING.md Logging guide}.

data/TROUBLESHOOTING.md

@@ -0,0 +1,37 @@
+# Troubleshooting
+
+## Where can I get more help?
+
+### Ask the Community
+
+If you have a question about how to use a Google Cloud client library in your
+project or are stuck in the Developer's console and don't know where to turn,
+it's possible your questions have already been addressed by the community.
+
+First, check out the appropriate tags on StackOverflow:
+  - [`google-cloud-platform+ruby+firestore`][so-ruby]
+
+Next, try searching through the issues on GitHub:
+
+  - [`api:firestore` issues][gh-search-ruby]
+
+Still nothing?
+
+### Ask the Developers
+
+If you're experiencing a bug with the code, or have an idea for how it can be
+improved, *please* create a new issue on GitHub so we can talk about it.
+
+  - [New issue][gh-ruby]
+
+Or, you can ask questions on the [Google Cloud Platform Slack][slack-ruby]. You
+can use the "ruby" channel for general Ruby questions, or use the
+"google-cloud-ruby" channel if you have questions about this gem in particular.
+
+[so-ruby]: http://stackoverflow.com/questions/tagged/google-cloud-platform+ruby+firestore
+
+[gh-search-ruby]: https://github.com/googlecloudplatform/google-cloud-ruby/issues?q=label%3A%22api%3A+firestore%22
+
+[gh-ruby]: https://github.com/googlecloudplatform/google-cloud-ruby/issues/new
+
+[slack-ruby]: https://gcp-slack.appspot.com/

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

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-firestore
 version: !ruby/object:Gem::Version
-  version: 0.24.0
+  version: 0.24.1
 platform: ruby
 authors:
 - Google Inc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-09-10 00:00:00.000000000 Z
+date: 2018-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -214,8 +214,14 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".yardopts"
+- AUTHENTICATION.md
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
 - LICENSE
-- README.md
+- LOGGING.md
+- OVERVIEW.md
+- TROUBLESHOOTING.md
 - lib/google-cloud-firestore.rb
 - lib/google/cloud/firestore.rb
 - lib/google/cloud/firestore/batch.rb

data/README.md

@@ -1,63 +0,0 @@
-# Ruby Client for Google Cloud Firestore API ([Beta](https://github.com/GoogleCloudPlatform/google-cloud-ruby#versioning))
-
-[Google Cloud Firestore API][Product Documentation]:
-
-- [Client Library Documentation][]
-- [Product Documentation][]
-
-## Quick Start
-In order to use this library, you first need to go through the following
-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-firestore/latest/file.AUTHENTICATION)
-
-### Installation
-```
-$ gem install google-cloud-firestore
-```
-
-### Next Steps
-- Read the [Client Library Documentation][] for Google Cloud Firestore API
-  to see other available methods on the client.
-- Read the [Google Cloud Firestore API Product documentation][Product Documentation]
-  to learn more about the product and see How-to Guides.
-- View this [repository's main README](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/master/README.md)
-  to see the full list of Cloud APIs that we cover.
-
-## 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
-```
-
-## Supported Ruby Versions
-
-This library is supported on Ruby 2.3+.
-
-Google provides official support for Ruby versions that are actively supported
-by Ruby Core—that is, Ruby versions that are either in normal maintenance or
-in security maintenance, and not end of life. Currently, this means Ruby 2.3
-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
-[Product Documentation]: https://cloud.google.com/firestore