| // Copyright 2017 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 |
| // |
| // http://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. |
| |
| // DO NOT EDIT doc.go. Modify internal/doc.template, then run make -C internal. |
| |
| /* |
| Package firestore provides a client for reading and writing to a Cloud Firestore |
| database. |
| |
| See https://cloud.google.com/firestore/docs for an introduction |
| to Cloud Firestore and additional help on using the Firestore API. |
| |
| Note: you can't use both Cloud Firestore and Cloud Datastore in the same |
| project. |
| |
| Creating a Client |
| |
| To start working with this package, create a client with a project ID: |
| |
| [NewClient] |
| |
| CollectionRefs and DocumentRefs |
| |
| In Firestore, documents are sets of key-value pairs, and collections are groups of |
| documents. A Firestore database consists of a hierarchy of alternating collections |
| and documents, referred to by slash-separated paths like |
| "States/California/Cities/SanFrancisco". |
| |
| This client is built around references to collections and documents. CollectionRefs |
| and DocumentRefs are lightweight values that refer to the corresponding database |
| entities. Creating a ref does not involve any network traffic. |
| |
| [refs] |
| |
| Reading |
| |
| Use DocumentRef.Get to read a document. The result is a DocumentSnapshot. |
| Call its Data method to obtain the entire document contents as a map. |
| |
| [docref.Get] |
| |
| You can also obtain a single field with DataAt, or extract the data into a struct |
| with DataTo. With the type definition |
| |
| [structDef] |
| |
| we can extract the document's data into a value of type State: |
| |
| [DataTo] |
| |
| Note that this client supports struct tags beginning with "firestore:" that work like |
| the tags of the encoding/json package, letting you rename fields, ignore them, or |
| omit their values when empty. |
| |
| To retrieve multiple documents from their references in a single call, use |
| Client.GetAll. |
| |
| [GetAll] |
| |
| Writing |
| |
| For writing individual documents, use the methods on DocumentReference. |
| Create creates a new document. |
| |
| [docref.Create] |
| |
| The first return value is a WriteResult, which contains the time |
| at which the document was updated. |
| |
| Create fails if the document exists. Another method, Set, either replaces an existing |
| document or creates a new one. |
| |
| [docref.Set] |
| |
| To update some fields of an existing document, use Update. It takes a list of |
| paths to update and their corresponding values. |
| |
| [docref.Update] |
| |
| Use DocumentRef.Delete to delete a document. |
| |
| [docref.Delete] |
| |
| Preconditions |
| |
| You can condition Deletes or Updates on when a document was last changed. Specify |
| these preconditions as an option to a Delete or Update method. The check and the |
| write happen atomically with a single RPC. |
| |
| [LUT-precond] |
| |
| Here we update a doc only if it hasn't changed since we read it. |
| You could also do this with a transaction. |
| |
| To perform multiple writes at once, use a WriteBatch. Its methods chain |
| for convenience. |
| |
| WriteBatch.Commit sends the collected writes to the server, where they happen |
| atomically. |
| |
| [WriteBatch] |
| |
| Queries |
| |
| You can use SQL to select documents from a collection. Begin with the collection, and |
| build up a query using Select, Where and other methods of Query. |
| |
| [Query] |
| |
| Call the Query's Documents method to get an iterator, and use it like |
| the other Google Cloud Client iterators. |
| |
| [Documents] |
| |
| To get all the documents in a collection, you can use the collection itself |
| as a query. |
| |
| [CollQuery] |
| |
| Transactions |
| |
| Use a transaction to execute reads and writes atomically. All reads must happen |
| before any writes. Transaction creation, commit, rollback and retry are handled for |
| you by the Client.RunTransaction method; just provide a function and use the |
| read and write methods of the Transaction passed to it. |
| |
| [Transaction] |
| |
| Authentication |
| |
| See examples of authorization and authentication at |
| https://godoc.org/cloud.google.com/go#pkg-examples. |
| */ |
| package firestore |