|
- // 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
|