1// Copyright 2017 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15// DO NOT EDIT doc.go. Modify internal/doc.template, then run make -C internal. 16 17/* 18Package firestore provides a client for reading and writing to a Cloud Firestore 19database. 20 21See https://cloud.google.com/firestore/docs for an introduction 22to Cloud Firestore and additional help on using the Firestore API. 23 24Note: you can't use both Cloud Firestore and Cloud Datastore in the same 25project. 26 27Creating a Client 28 29To start working with this package, create a client with a project ID: 30 31[NewClient] 32 33CollectionRefs and DocumentRefs 34 35In Firestore, documents are sets of key-value pairs, and collections are groups of 36documents. A Firestore database consists of a hierarchy of alternating collections 37and documents, referred to by slash-separated paths like 38"States/California/Cities/SanFrancisco". 39 40This client is built around references to collections and documents. CollectionRefs 41and DocumentRefs are lightweight values that refer to the corresponding database 42entities. Creating a ref does not involve any network traffic. 43 44[refs] 45 46Reading 47 48Use DocumentRef.Get to read a document. The result is a DocumentSnapshot. 49Call its Data method to obtain the entire document contents as a map. 50 51[docref.Get] 52 53You can also obtain a single field with DataAt, or extract the data into a struct 54with DataTo. With the type definition 55 56[structDef] 57 58we can extract the document's data into a value of type State: 59 60[DataTo] 61 62Note that this client supports struct tags beginning with "firestore:" that work like 63the tags of the encoding/json package, letting you rename fields, ignore them, or 64omit their values when empty. 65 66To retrieve multiple documents from their references in a single call, use 67Client.GetAll. 68 69[GetAll] 70 71Writing 72 73For writing individual documents, use the methods on DocumentReference. 74Create creates a new document. 75 76[docref.Create] 77 78The first return value is a WriteResult, which contains the time 79at which the document was updated. 80 81Create fails if the document exists. Another method, Set, either replaces an existing 82document or creates a new one. 83 84[docref.Set] 85 86To update some fields of an existing document, use Update. It takes a list of 87paths to update and their corresponding values. 88 89[docref.Update] 90 91Use DocumentRef.Delete to delete a document. 92 93[docref.Delete] 94 95Preconditions 96 97You can condition Deletes or Updates on when a document was last changed. Specify 98these preconditions as an option to a Delete or Update method. The check and the 99write happen atomically with a single RPC. 100 101[LUT-precond] 102 103Here we update a doc only if it hasn't changed since we read it. 104You could also do this with a transaction. 105 106To perform multiple writes at once, use a WriteBatch. Its methods chain 107for convenience. 108 109WriteBatch.Commit sends the collected writes to the server, where they happen 110atomically. 111 112[WriteBatch] 113 114Queries 115 116You can use SQL to select documents from a collection. Begin with the collection, and 117build up a query using Select, Where and other methods of Query. 118 119[Query] 120 121Call the Query's Documents method to get an iterator, and use it like 122the other Google Cloud Client iterators. 123 124[Documents] 125 126To get all the documents in a collection, you can use the collection itself 127as a query. 128 129[CollQuery] 130 131Transactions 132 133Use a transaction to execute reads and writes atomically. All reads must happen 134before any writes. Transaction creation, commit, rollback and retry are handled for 135you by the Client.RunTransaction method; just provide a function and use the 136read and write methods of the Transaction passed to it. 137 138[Transaction] 139 140Authentication 141 142See examples of authorization and authentication at 143https://godoc.org/cloud.google.com/go#pkg-examples. 144*/ 145package firestore 146