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.
See https://godoc.org/cloud.google.com/go for authentication, timeouts,
connection pooling and similar aspects of this package.
Note: you can't use both Cloud Firestore and Cloud Datastore in the same
project.
To start working with this package, create a client with a project ID:
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.
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.
You can also obtain a single field with DataAt, or extract the data into a struct
with DataTo. With the type definition
we can extract the document's data into a value of type State:
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.
For writing individual documents, use the methods on DocumentReference.
Create creates a new document.
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.
To update some fields of an existing document, use Update. It takes a list of
paths to update and their corresponding values.
Use DocumentRef.Delete to delete a document.
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.
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.
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.
Supported operators include '<', '<=', '>', '>=', '==', 'in', 'array-contains', and
'array-contains-any'.
Call the Query's Documents method to get an iterator, and use it like
the other Google Cloud Client iterators.
To get all the documents in a collection, you can use the collection itself
as a query.
You can partition the documents of a Collection Group allowing for smaller subqueries.
You can also Serialize/Deserialize queries making it possible to run/stream the
queries elsewhere; another process or machine for instance.
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.
This package supports the Cloud Firestore emulator, which is useful for testing and
development. Environment variables are used to indicate that Firestore traffic should be
directed to the emulator instead of the production Firestore service.
To install and run the emulator and its environment variables, see the documentation
at https://cloud.google.com/sdk/gcloud/reference/beta/emulators/firestore/. Once the
emulator is running, set FIRESTORE_EMULATOR_HOST to the API endpoint.