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