Este documento explica como definir, adicionar ou atualizar documentos individuais no Cloud Firestore. Para gravar dados em massa, consulte Transações e gravações em lote.
Visão geral
É possível gravar dados no Cloud Firestore de uma das seguintes maneiras:
- Definir os dados de um documento em uma coleção especificando explicitamente um identificador de documento.
- Adicionar um novo documento a uma coleção. Nesse caso, o Cloud Firestore gera automaticamente o identificador do documento.
- Criar um documento vazio com um identificador gerado automaticamente e atribuir dados a ele posteriormente.
Antes de começar
Antes de inicializar o Cloud Firestore para definir, adicionar ou atualizar dados, você precisa:
- Criar um banco de dados do Cloud Firestore. Para mais informações, consulte Começar a usar o Cloud Firestore.
- Se você usar as bibliotecas de cliente da Web ou para dispositivos móveis, faça a autenticação com regras de segurança. Para mais informações, consulte Primeiros passos com as regras de segurança.
- Se você usar as bibliotecas de cliente do servidor ou a API REST, faça a autenticação com o Identity and Access Management (IAM, na sigla em inglês). Para mais informações, consulte Segurança de bibliotecas de cliente do servidor.
Inicializar o Cloud Firestore
Inicialize uma instância do Cloud Firestore:
import { initializeApp } from "firebase/app"; import { getFirestore } from "firebase/firestore"; // TODO: Replace the following with your app's Firebase project configuration // See: https://support.google.com/firebase/answer/7015592 const firebaseConfig = {FIREBASE_CONFIGURATION }; // Initialize Firebase const app = initializeApp(firebaseConfig); // Initialize Cloud Firestore and get a reference to the service const db = getFirestore(app);
Substitua FIREBASE_CONFIGURATION pelo
firebaseConfig
do seu app da Web.
Para manter os dados se o dispositivo perder a conexão, consulte a documentação Ativar dados off-line.
import firebase from "firebase/app"; import "firebase/firestore"; // TODO: Replace the following with your app's Firebase project configuration // See: https://support.google.com/firebase/answer/7015592 const firebaseConfig = {FIREBASE_CONFIGURATION }; // Initialize Firebase firebase.initializeApp(firebaseConfig); // Initialize Cloud Firestore and get a reference to the service const db = firebase.firestore();
Substitua FIREBASE_CONFIGURATION pelo
firebaseConfig
do seu app da Web.
Para manter os dados se o dispositivo perder a conexão, consulte a documentação Ativar dados off-line.
import FirebaseCore import FirebaseFirestore
FirebaseApp.configure() let db = Firestore.firestore()
@import FirebaseCore; @import FirebaseFirestore; // Use Firebase library to configure APIs [FIRApp configure];
FIRFirestore *defaultFirestore = [FIRFirestore firestore];
// Access a Cloud Firestore instance from your Activity
val db = Firebase.firestore
// Access a Cloud Firestore instance from your Activity
FirebaseFirestore db = FirebaseFirestore.getInstance();
db = FirebaseFirestore.instance;
import com.google.auth.oauth2.GoogleCredentials; import com.google.cloud.firestore.Firestore; import com.google.firebase.FirebaseApp; import com.google.firebase.FirebaseOptions; // Use the application default credentials GoogleCredentials credentials = GoogleCredentials.getApplicationDefault(); FirebaseOptions options = new FirebaseOptions.Builder() .setCredentials(credentials) .setProjectId(projectId) .build(); FirebaseApp.initializeApp(options); Firestore db = FirestoreClient.getFirestore();
Para usar o SDK Admin do Firebase no seu próprio servidor, use uma conta de serviço.
Acesse IAM e administrador > Contas de serviço no console do Google Cloud. Gere uma nova chave privada e salve o arquivo JSON. Em seguida, use o arquivo para inicializar o SDK:
import com.google.auth.oauth2.GoogleCredentials; import com.google.cloud.firestore.Firestore; import com.google.firebase.FirebaseApp; import com.google.firebase.FirebaseOptions; // Use a service account InputStream serviceAccount = new FileInputStream("path/to/serviceAccount.json "); GoogleCredentials credentials = GoogleCredentials.fromStream(serviceAccount); FirebaseOptions options = new FirebaseOptions.Builder() .setCredentials(credentials) .build(); FirebaseApp.initializeApp(options); Firestore db = FirestoreClient.getFirestore();
import firebase_admin from firebase_admin import firestore # Application Default credentials are automatically created. app = firebase_admin.initialize_app() db = firestore.client()
Uma credencial padrão do aplicativo também pode ser usada para inicializar o SDK.
import firebase_admin from firebase_admin import credentials from firebase_admin import firestore # Use the application default credentials. cred = credentials.ApplicationDefault() firebase_admin.initialize_app(cred) db = firestore.client()
Para usar o SDK Admin do Firebase no seu próprio servidor, use uma conta de serviço.
Acesse IAM e administrador > Contas de serviço no console do Google Cloud. Gere uma nova chave privada e salve o arquivo JSON. Em seguida, use o arquivo para inicializar o SDK:
import firebase_admin from firebase_admin import credentials from firebase_admin import firestore # Use a service account. cred = credentials.Certificate('path/to/serviceAccount.json') app = firebase_admin.initialize_app(cred) db = firestore.client()
import firebase_admin from firebase_admin import firestore_async # Application Default credentials are automatically created. app = firebase_admin.initialize_app() db = firestore_async.client()
Uma credencial padrão do aplicativo também pode ser usada para inicializar o SDK.
import firebase_admin from firebase_admin import credentials from firebase_admin import firestore_async # Use the application default credentials. cred = credentials.ApplicationDefault() firebase_admin.initialize_app(cred) db = firestore_async.client()
Para usar o SDK Admin do Firebase no seu próprio servidor, use uma conta de serviço.
Acesse IAM e administrador > Contas de serviço no console do Google Cloud. Gere uma nova chave privada e salve o arquivo JSON. Em seguida, use o arquivo para inicializar o SDK:
import firebase_admin from firebase_admin import credentials from firebase_admin import firestore_async # Use a service account. cred = credentials.Certificate('path/to/serviceAccount.json') app = firebase_admin.initialize_app(cred) db = firestore_async.client()
// Make sure the call to `Create()` happens some time before you call Firestore::GetInstance(). App::Create(); Firestore* db = Firestore::GetInstance();
-
Inicializar o Cloud Functions
const { initializeApp, applicationDefault, cert } = require('firebase-admin/app'); const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
initializeApp(); const db = getFirestore();
-
Inicializar o Google Cloud
const { initializeApp, applicationDefault, cert } = require('firebase-admin/app'); const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
initializeApp({ credential: applicationDefault() }); const db = getFirestore();
-
Inicializar no seu próprio servidor
Para usar o SDK Admin do Firebase no seu próprio servidor, ou em qualquer outro ambiente com Node.js, use uma conta de serviço. Acesse IAM e administrador > Contas de serviço no console do Google Cloud. Gere uma nova chave privada e salve o arquivo JSON. Em seguida, use o arquivo para inicializar o SDK:
const { initializeApp, applicationDefault, cert } = require('firebase-admin/app'); const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
const serviceAccount = require('./path/to/serviceAccountKey.json'); initializeApp({ credential: cert(serviceAccount) }); const db = getFirestore();
import ( "log" firebase "firebase.google.com/go" "google.golang.org/api/option" ) // Use the application default credentials ctx := context.Background() conf := &firebase.Config{ProjectID: projectID} app, err := firebase.NewApp(ctx, conf) if err != nil { log.Fatalln(err) } client, err := app.Firestore(ctx) if err != nil { log.Fatalln(err) } defer client.Close()
Para usar o SDK Admin do Firebase no seu próprio servidor, use uma conta de serviço.
Acesse IAM e administrador > Contas de serviço no console do Google Cloud. Gere uma nova chave privada e salve o arquivo JSON. Em seguida, use o arquivo para inicializar o SDK:
import ( "log" firebase "firebase.google.com/go" "google.golang.org/api/option" ) // Use a service account ctx := context.Background() sa := option.WithCredentialsFile("path/to/serviceAccount.json") app, err := firebase.NewApp(ctx, nil, sa) if err != nil { log.Fatalln(err) } client, err := app.Firestore(ctx) if err != nil { log.Fatalln(err) } defer client.Close()
PHP
Para mais informações sobre como instalar e criar um cliente do Cloud Firestore, consulte Bibliotecas de cliente do Cloud Firestore.
using Firebase.Firestore; using Firebase.Extensions;
FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
C#
Para mais informações sobre como instalar e criar um cliente Cloud Firestore, consulte Bibliotecas de cliente Cloud Firestore.
Definir um documento
Para criar ou substituir um único documento, use os métodos set()
a seguir específicos da linguagem:
Use o método setDoc()
.
import { doc, setDoc } from "firebase/firestore"; // Add a new document in collection "cities" await setDoc(doc(db, "cities", "LA"), { name: "Los Angeles", state: "CA", country: "USA" });
Use o método set()
.
// Add a new document in collection "cities" db.collection("cities").doc("LA").set({ name: "Los Angeles", state: "CA", country: "USA" }) .then(() => { console.log("Document successfully written!"); }) .catch((error) => { console.error("Error writing document: ", error); });
Use o método setData()
.
// Add a new document in collection "cities" do { try await db.collection("cities").document("LA").setData([ "name": "Los Angeles", "state": "CA", "country": "USA" ]) print("Document successfully written!") } catch { print("Error writing document: \(error)") }
Use o método setData:
.
// Add a new document in collection "cities" [[[self.db collectionWithPath:@"cities"] documentWithPath:@"LA"] setData:@{ @"name": @"Los Angeles", @"state": @"CA", @"country": @"USA" } completion:^(NSError * _Nullable error) { if (error != nil) { NSLog(@"Error writing document: %@", error); } else { NSLog(@"Document successfully written!"); } }];
Use o método set()
.
val city = hashMapOf( "name" to "Los Angeles", "state" to "CA", "country" to "USA", ) db.collection("cities").document("LA") .set(city) .addOnSuccessListener { Log.d(TAG, "DocumentSnapshot successfully written!") } .addOnFailureListener { e -> Log.w(TAG, "Error writing document", e) }
Use o método set()
.
Map<String, Object> city = new HashMap<>(); city.put("name", "Los Angeles"); city.put("state", "CA"); city.put("country", "USA"); db.collection("cities").document("LA") .set(city) .addOnSuccessListener(new OnSuccessListener<Void>() { @Override public void onSuccess(Void aVoid) { Log.d(TAG, "DocumentSnapshot successfully written!"); } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { Log.w(TAG, "Error writing document", e); } });
Use o método set()
.
final city = <String, String>{ "name": "Los Angeles", "state": "CA", "country": "USA" }; db .collection("cities") .doc("LA") .set(city) .onError((e, _) => print("Error writing document: $e"));
Use o método set()
.
Use o método set()
.
Use o método set()
.
Use o método Set()
.
// Add a new document in collection 'cities' db->Collection("cities") .Document("LA") .Set({{"name", FieldValue::String("Los Angeles")}, {"state", FieldValue::String("CA")}, {"country", FieldValue::String("USA")}}) .OnCompletion([](const Future<void>& future) { if (future.error() == Error::kErrorOk) { std::cout << "DocumentSnapshot successfully written!" << std::endl; } else { std::cout << "Error writing document: " << future.error_message() << std::endl; } });
Use o método set()
.
Use o método Set()
.
Use o método set()
.
PHP
Para mais informações sobre como instalar e criar um cliente do Cloud Firestore, consulte Bibliotecas de cliente do Cloud Firestore.
Use o método SetAsync()
.
DocumentReference docRef = db.Collection("cities").Document("LA"); Dictionary<string, object> city = new Dictionary<string, object> { { "Name", "Los Angeles" }, { "State", "CA" }, { "Country", "USA" } }; docRef.SetAsync(city).ContinueWithOnMainThread(task => { Debug.Log("Added data to the LA document in the cities collection."); });
Use o método SetAsync()
:
Use o método set()
.
Se o documento não existir, ele será criado. Se o documento existir, o conteúdo dele será substituído pelos dados recém-fornecidos da seguinte forma, a menos que você especifique que os dados devem ser incorporados ao documento existente:
import { doc, setDoc } from "firebase/firestore"; const cityRef = doc(db, 'cities', 'BJ'); setDoc(cityRef, { capital: true }, { merge: true });
var cityRef = db.collection('cities').doc('BJ'); var setWithMerge = cityRef.set({ capital: true }, { merge: true });
// Update one field, creating the document if it does not exist. db.collection("cities").document("BJ").setData([ "capital": true ], merge: true)
// Write to the document reference, merging data with existing // if the document already exists [[[self.db collectionWithPath:@"cities"] documentWithPath:@"BJ"] setData:@{ @"capital": @YES } merge:YES completion:^(NSError * _Nullable error) { // ... }];
// Update one field, creating the document if it does not already exist. val data = hashMapOf("capital" to true) db.collection("cities").document("BJ") .set(data, SetOptions.merge())
// Update one field, creating the document if it does not already exist. Map<String, Object> data = new HashMap<>(); data.put("capital", true); db.collection("cities").document("BJ") .set(data, SetOptions.merge());
// Update one field, creating the document if it does not already exist. final data = {"capital": true}; db.collection("cities").doc("BJ").set(data, SetOptions(merge: true));
db->Collection("cities").Document("BJ").Set( {{"capital", FieldValue::Boolean(true)}}, SetOptions::Merge());
PHP
Para mais informações sobre como instalar e criar um cliente do Cloud Firestore, consulte Bibliotecas de cliente do Cloud Firestore.
DocumentReference docRef = db.Collection("cities").Document("LA"); Dictionary<string, object> update = new Dictionary<string, object> { { "capital", false } }; docRef.SetAsync(update, SetOptions.MergeAll);
Se você não tiver certeza de que o documento existe, ignore a opção de mesclar novos dados com qualquer documento atual para evitar a substituição de documentos inteiros. Para documentos com mapas, se você especificar um conjunto com um campo que contém um mapa vazio, o campo do mapa do documento de destino será substituído.
Tipos de dados
O Cloud Firestore permite gravar uma variedade de tipos de dados em um documento, incluindo strings, booleanos, números, datas, nulos, além de matrizes e objetos aninhados. Não importa o tipo de número que você usa no código, o Cloud Firestore sempre armazena números como "double".
import { doc, setDoc, Timestamp } from "firebase/firestore"; const docData = { stringExample: "Hello world!", booleanExample: true, numberExample: 3.14159265, dateExample: Timestamp.fromDate(new Date("December 10, 1815")), arrayExample: [5, true, "hello"], nullExample: null, objectExample: { a: 5, b: { nested: "foo" } } }; await setDoc(doc(db, "data", "one"), docData);
var docData = { stringExample: "Hello world!", booleanExample: true, numberExample: 3.14159265, dateExample: firebase.firestore.Timestamp.fromDate(new Date("December 10, 1815")), arrayExample: [5, true, "hello"], nullExample: null, objectExample: { a: 5, b: { nested: "foo" } } }; db.collection("data").doc("one").set(docData).then(() => { console.log("Document successfully written!"); });
let docData: [String: Any] = [ "stringExample": "Hello world!", "booleanExample": true, "numberExample": 3.14159265, "dateExample": Timestamp(date: Date()), "arrayExample": [5, true, "hello"], "nullExample": NSNull(), "objectExample": [ "a": 5, "b": [ "nested": "foo" ] ] ] do { try await db.collection("data").document("one").setData(docData) print("Document successfully written!") } catch { print("Error writing document: \(error)") }
NSDictionary *docData = @{ @"stringExample": @"Hello world!", @"booleanExample": @YES, @"numberExample": @3.14, @"dateExample": [FIRTimestamp timestampWithDate:[NSDate date]], @"arrayExample": @[@5, @YES, @"hello"], @"nullExample": [NSNull null], @"objectExample": @{ @"a": @5, @"b": @{ @"nested": @"foo" } } }; [[[self.db collectionWithPath:@"data"] documentWithPath:@"one"] setData:docData completion:^(NSError * _Nullable error) { if (error != nil) { NSLog(@"Error writing document: %@", error); } else { NSLog(@"Document successfully written!"); } }];
val docData = hashMapOf( "stringExample" to "Hello world!", "booleanExample" to true, "numberExample" to 3.14159265, "dateExample" to Timestamp(Date()), "listExample" to arrayListOf(1, 2, 3), "nullExample" to null, ) val nestedData = hashMapOf( "a" to 5, "b" to true, ) docData["objectExample"] = nestedData db.collection("data").document("one") .set(docData) .addOnSuccessListener { Log.d(TAG, "DocumentSnapshot successfully written!") } .addOnFailureListener { e -> Log.w(TAG, "Error writing document", e) }
Map<String, Object> docData = new HashMap<>(); docData.put("stringExample", "Hello world!"); docData.put("booleanExample", true); docData.put("numberExample", 3.14159265); docData.put("dateExample", new Timestamp(new Date())); docData.put("listExample", Arrays.asList(1, 2, 3)); docData.put("nullExample", null); Map<String, Object> nestedData = new HashMap<>(); nestedData.put("a", 5); nestedData.put("b", true); docData.put("objectExample", nestedData); db.collection("data").document("one") .set(docData) .addOnSuccessListener(new OnSuccessListener<Void>() { @Override public void onSuccess(Void aVoid) { Log.d(TAG, "DocumentSnapshot successfully written!"); } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { Log.w(TAG, "Error writing document", e); } });
final docData = { "stringExample": "Hello world!", "booleanExample": true, "numberExample": 3.14159265, "dateExample": Timestamp.now(), "listExample": [1, 2, 3], "nullExample": null }; final nestedData = { "a": 5, "b": true, }; docData["objectExample"] = nestedData; db .collection("data") .doc("one") .set(docData) .onError((e, _) => print("Error writing document: $e"));
MapFieldValue doc_data{ {"stringExample", FieldValue::String("Hello world!")}, {"booleanExample", FieldValue::Boolean(true)}, {"numberExample", FieldValue::Double(3.14159265)}, {"dateExample", FieldValue::Timestamp(Timestamp::Now())}, {"arrayExample", FieldValue::Array({FieldValue::Integer(1), FieldValue::Integer(2), FieldValue::Integer(3)})}, {"nullExample", FieldValue::Null()}, {"objectExample", FieldValue::Map( {{"a", FieldValue::Integer(5)}, {"b", FieldValue::Map( {{"nested", FieldValue::String("foo")}})}})}, }; db->Collection("data").Document("one").Set(doc_data).OnCompletion( [](const Future<void>& future) { if (future.error() == Error::kErrorOk) { std::cout << "DocumentSnapshot successfully written!" << std::endl; } else { std::cout << "Error writing document: " << future.error_message() << std::endl; } });
PHP
Para mais informações sobre como instalar e criar um cliente do Cloud Firestore, consulte Bibliotecas de cliente do Cloud Firestore.
DocumentReference docRef = db.Collection("data").Document("one"); Dictionary<string, object> docData = new Dictionary<string, object> { { "stringExample", "Hello World" }, { "booleanExample", false }, { "numberExample", 3.14159265 }, { "nullExample", null }, { "arrayExample", new List<object>() { 5, true, "Hello" } }, { "objectExample", new Dictionary<string, object> { { "a", 5 }, { "b", true }, } }, }; docRef.SetAsync(docData);
Objetos personalizados
Geralmente, usar os objetos Map
ou Dictionary
para representar seus documentos não
é muito conveniente. Por isso, o Cloud Firestore aceita a gravação de documentos com classes
personalizadas. O Cloud Firestore converte os objetos em tipos de dados
compatíveis.
Usando classes personalizadas, é possível reescrever o exemplo inicial da seguinte maneira:
class City { constructor (name, state, country ) { this.name = name; this.state = state; this.country = country; } toString() { return this.name + ', ' + this.state + ', ' + this.country; } } // Firestore data converter const cityConverter = { toFirestore: (city) => { return { name: city.name, state: city.state, country: city.country }; }, fromFirestore: (snapshot, options) => { const data = snapshot.data(options); return new City(data.name, data.state, data.country); } };
class City { constructor (name, state, country ) { this.name = name; this.state = state; this.country = country; } toString() { return this.name + ', ' + this.state + ', ' + this.country; } } // Firestore data converter var cityConverter = { toFirestore: function(city) { return { name: city.name, state: city.state, country: city.country }; }, fromFirestore: function(snapshot, options){ const data = snapshot.data(options); return new City(data.name, data.state, data.country); } };
public struct City: Codable { let name: String let state: String? let country: String? let isCapital: Bool? let population: Int64? enum CodingKeys: String, CodingKey { case name case state case country case isCapital = "capital" case population } }
// This isn't supported in Objective-C.
data class City( val name: String? = null, val state: String? = null, val country: String? = null, @field:JvmField // use this annotation if your Boolean field is prefixed with 'is' val isCapital: Boolean? = null, val population: Long? = null, val regions: List<String>? = null, )
Cada classe personalizada precisa ter um construtor público que não aceita argumentos. Além disso, a classe precisa incluir um getter público para cada propriedade.
public class City { private String name; private String state; private String country; private boolean capital; private long population; private List<String> regions; public City() {} public City(String name, String state, String country, boolean capital, long population, List<String> regions) { // ... } public String getName() { return name; } public String getState() { return state; } public String getCountry() { return country; } public boolean isCapital() { return capital; } public long getPopulation() { return population; } public List<String> getRegions() { return regions; } }
class City { final String? name; final String? state; final String? country; final bool? capital; final int? population; final List<String>? regions; City({ this.name, this.state, this.country, this.capital, this.population, this.regions, }); factory City.fromFirestore( DocumentSnapshot<Map<String, dynamic>> snapshot, SnapshotOptions? options, ) { final data = snapshot.data(); return City( name: data?['name'], state: data?['state'], country: data?['country'], capital: data?['capital'], population: data?['population'], regions: data?['regions'] is Iterable ? List.from(data?['regions']) : null, ); } Map<String, dynamic> toFirestore() { return { if (name != null) "name": name, if (state != null) "state": state, if (country != null) "country": country, if (capital != null) "capital": capital, if (population != null) "population": population, if (regions != null) "regions": regions, }; } }
// This is not yet supported.
// Node.js uses JavaScript objects
PHP
Para mais informações sobre como instalar e criar um cliente do Cloud Firestore, consulte Bibliotecas de cliente do Cloud Firestore.
[FirestoreData] public class City { [FirestoreProperty] public string Name { get; set; } [FirestoreProperty] public string State { get; set; } [FirestoreProperty] public string Country { get; set; } [FirestoreProperty] public bool Capital { get; set; } [FirestoreProperty] public long Population { get; set; } }
// This isn't supported in Ruby
import { doc, setDoc } from "firebase/firestore"; // Set with cityConverter const ref = doc(db, "cities", "LA").withConverter(cityConverter); await setDoc(ref, new City("Los Angeles", "CA", "USA"));
// Set with cityConverter db.collection("cities").doc("LA") .withConverter(cityConverter) .set(new City("Los Angeles", "CA", "USA"));
let city = City(name: "Los Angeles", state: "CA", country: "USA", isCapital: false, population: 5000000) do { try db.collection("cities").document("LA").setData(from: city) } catch let error { print("Error writing city to Firestore: \(error)") }
// This isn't supported in Objective-C.
val city = City( "Los Angeles", "CA", "USA", false, 5000000L, listOf("west_coast", "socal"), ) db.collection("cities").document("LA").set(city)
City city = new City("Los Angeles", "CA", "USA", false, 5000000L, Arrays.asList("west_coast", "sorcal")); db.collection("cities").document("LA").set(city);
final city = City( name: "Los Angeles", state: "CA", country: "USA", capital: false, population: 5000000, regions: ["west_coast", "socal"], ); final docRef = db .collection("cities") .withConverter( fromFirestore: City.fromFirestore, toFirestore: (City city, options) => city.toFirestore(), ) .doc("LA"); await docRef.set(city);
// This is not yet supported.
// Node.js uses JavaScript objects
// This isn't supported in PHP.
DocumentReference docRef = db.Collection("cities").Document("LA"); City city = new City { Name = "Los Angeles", State = "CA", Country = "USA", Capital = false, Population = 3900000L }; docRef.SetAsync(city);
// This isn't supported in Ruby.
Adicionar um documento
Ao usar set()
para criar um documento, especifique um ID para
o documento, conforme mostrado no exemplo a seguir:
import { doc, setDoc } from "firebase/firestore"; await setDoc(doc(db, "cities", "new-city-id"), data);
db.collection("cities").doc("new-city-id").set(data);
db.collection("cities").document("new-city-id").setData(data)
[[[self.db collectionWithPath:@"cities"] documentWithPath:@"new-city-id"] setData:data];
db.collection("cities").document("new-city-id").set(data)
db.collection("cities").document("new-city-id").set(data);
db.collection("cities").doc("new-city-id").set({"name": "Chicago"});
db->Collection("cities").Document("SF").Set({/*some data*/});
PHP
Para mais informações sobre como instalar e criar um cliente do Cloud Firestore, consulte Bibliotecas de cliente do Cloud Firestore.
db.Collection("cities").Document("new-city-id").SetAsync(city);
Se não houver um ID significativo para o documento, o Cloud Firestore poderá
gerar um automaticamente para você. É possível chamar os seguintes métodos
add()
específicos da linguagem:
Use o método addDoc()
.
import { collection, addDoc } from "firebase/firestore"; // Add a new document with a generated id. const docRef = await addDoc(collection(db, "cities"), { name: "Tokyo", country: "Japan" }); console.log("Document written with ID: ", docRef.id);
Use o método add()
.
// Add a new document with a generated id. db.collection("cities").add({ name: "Tokyo", country: "Japan" }) .then((docRef) => { console.log("Document written with ID: ", docRef.id); }) .catch((error) => { console.error("Error adding document: ", error); });
Use o método addDocument()
.
// Add a new document with a generated id. do { let ref = try await db.collection("cities").addDocument(data: [ "name": "Tokyo", "country": "Japan" ]) print("Document added with ID: \(ref.documentID)") } catch { print("Error adding document: \(error)") }
Use o método addDocumentWithData:
.
// Add a new document with a generated id. __block FIRDocumentReference *ref = [[self.db collectionWithPath:@"cities"] addDocumentWithData:@{ @"name": @"Tokyo", @"country": @"Japan" } completion:^(NSError * _Nullable error) { if (error != nil) { NSLog(@"Error adding document: %@", error); } else { NSLog(@"Document added with ID: %@", ref.documentID); } }];
Use o método add()
.
// Add a new document with a generated id. val data = hashMapOf( "name" to "Tokyo", "country" to "Japan", ) db.collection("cities") .add(data) .addOnSuccessListener { documentReference -> Log.d(TAG, "DocumentSnapshot written with ID: ${documentReference.id}") } .addOnFailureListener { e -> Log.w(TAG, "Error adding document", e) }
Use o método add()
.
// Add a new document with a generated id. Map<String, Object> data = new HashMap<>(); data.put("name", "Tokyo"); data.put("country", "Japan"); db.collection("cities") .add(data) .addOnSuccessListener(new OnSuccessListener<DocumentReference>() { @Override public void onSuccess(DocumentReference documentReference) { Log.d(TAG, "DocumentSnapshot written with ID: " + documentReference.getId()); } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { Log.w(TAG, "Error adding document", e); } });
Use o método add()
.
// Add a new document with a generated id. final data = {"name": "Tokyo", "country": "Japan"}; db.collection("cities").add(data).then((documentSnapshot) => print("Added Data with ID: ${documentSnapshot.id}"));
Use o método add()
.
Use o método add()
.
Use o método add()
.
Use o método Add()
.
db->Collection("cities").Add({/*some data*/});
Use o método add()
.
Use o método Add()
.
Use o método add()
.
PHP
Para mais informações sobre como instalar e criar um cliente do Cloud Firestore, consulte Bibliotecas de cliente do Cloud Firestore.
Use o método AddAsync()
.
Dictionary<string, object> city = new Dictionary<string, object> { { "Name", "Tokyo" }, { "Country", "Japan" } }; db.Collection("cities").AddAsync(city).ContinueWithOnMainThread(task => { DocumentReference addedDocRef = task.Result; Debug.Log(String.Format("Added document with ID: {0}.", addedDocRef.Id)); });
Use o método AddAsync()
:
Use o método add()
.
Em alguns casos, pode ser útil criar uma referência de documento com um ID gerado automaticamente, para usá-la mais tarde. Para este caso de uso, chame
doc()
da seguinte maneira:
import { collection, doc, setDoc } from "firebase/firestore"; // Add a new document with a generated id const newCityRef = doc(collection(db, "cities")); // later... await setDoc(newCityRef, data);
// Add a new document with a generated id. var newCityRef = db.collection("cities").doc(); // later... newCityRef.set(data);
let newCityRef = db.collection("cities").document() // later... newCityRef.setData([ // ... ])
FIRDocumentReference *newCityRef = [[self.db collectionWithPath:@"cities"] documentWithAutoID]; // later... [newCityRef setData:@{ /* ... */ }];
val data = HashMap<String, Any>() val newCityRef = db.collection("cities").document() // Later... newCityRef.set(data)
Map<String, Object> data = new HashMap<>(); DocumentReference newCityRef = db.collection("cities").document(); // Later... newCityRef.set(data);
// Add a new document with a generated id. final data = <String, dynamic>{}; final newCityRef = db.collection("cities").doc(); // Later... newCityRef.set(data);
DocumentReference new_city_ref = db->Collection("cities").Document();
PHP
Para mais informações sobre como instalar e criar um cliente do Cloud Firestore, consulte Bibliotecas de cliente do Cloud Firestore.
DocumentReference addedDocRef = db.Collection("cities").Document(); Debug.Log(String.Format("Added document with ID: {0}.", addedDocRef.Id)); addedDocRef.SetAsync(city).ContinueWithOnMainThread(task => { Debug.Log(String.Format( "Added data to the {0} document in the cities collection.", addedDocRef.Id)); });
No back-end, .add(...)
e .doc().set(...)
são equivalentes, então você pode usar
qualquer uma das opções.
Atualizar um documento
Para atualizar alguns campos de um documento sem substituir o documento inteiro, use
os métodos update()
a seguir específicos da linguagem:
Use o método updateDoc()
.
import { doc, updateDoc } from "firebase/firestore"; const washingtonRef = doc(db, "cities", "DC"); // Set the "capital" field of the city 'DC' await updateDoc(washingtonRef, { capital: true });
Use o método update()
.
var washingtonRef = db.collection("cities").doc("DC"); // Set the "capital" field of the city 'DC' return washingtonRef.update({ capital: true }) .then(() => { console.log("Document successfully updated!"); }) .catch((error) => { // The document probably doesn't exist. console.error("Error updating document: ", error); });
Use o método updateData()
.
let washingtonRef = db.collection("cities").document("DC") // Set the "capital" field of the city 'DC' do { try await washingtonRef.updateData([ "capital": true ]) print("Document successfully updated") } catch { print("Error updating document: \(error)") }
Use o método updateData:
.
FIRDocumentReference *washingtonRef = [[self.db collectionWithPath:@"cities"] documentWithPath:@"DC"]; // Set the "capital" field of the city [washingtonRef updateData:@{ @"capital": @YES } completion:^(NSError * _Nullable error) { if (error != nil) { NSLog(@"Error updating document: %@", error); } else { NSLog(@"Document successfully updated"); } }];
Use o método update()
.
val washingtonRef = db.collection("cities").document("DC") // Set the "isCapital" field of the city 'DC' washingtonRef .update("capital", true) .addOnSuccessListener { Log.d(TAG, "DocumentSnapshot successfully updated!") } .addOnFailureListener { e -> Log.w(TAG, "Error updating document", e) }
Use o método update()
.
DocumentReference washingtonRef = db.collection("cities").document("DC"); // Set the "isCapital" field of the city 'DC' washingtonRef .update("capital", true) .addOnSuccessListener(new OnSuccessListener<Void>() { @Override public void onSuccess(Void aVoid) { Log.d(TAG, "DocumentSnapshot successfully updated!"); } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { Log.w(TAG, "Error updating document", e); } });
Use o método update()
.
final washingtonRef = db.collection("cites").doc("DC"); washingtonRef.update({"capital": true}).then( (value) => print("DocumentSnapshot successfully updated!"), onError: (e) => print("Error updating document $e"));
Use o método update()
.
Use o método update()
.
Use o método update()
.
Use o método Update()
.
DocumentReference washington_ref = db->Collection("cities").Document("DC"); // Set the "capital" field of the city "DC". washington_ref.Update({{"capital", FieldValue::Boolean(true)}});
Use o método update()
.
Use o método Update()
.
Use o método update()
.
PHP
Para mais informações sobre como instalar e criar um cliente do Cloud Firestore, consulte Bibliotecas de cliente do Cloud Firestore.
Use o método UpdateAsync()
.
DocumentReference cityRef = db.Collection("cities").Document("new-city-id"); Dictionary<string, object> updates = new Dictionary<string, object> { { "Capital", false } }; cityRef.UpdateAsync(updates).ContinueWithOnMainThread(task => { Debug.Log( "Updated the Capital field of the new-city-id document in the cities collection."); }); // You can also update a single field with: cityRef.UpdateAsync("Capital", false);
Use o método UpdateAsync()
:
Use o método update()
.
Carimbo de data/hora do servidor
É possível configurar um campo no documento como um carimbo de data/hora do servidor que detecta quando o servidor recebe a atualização.
import { updateDoc, serverTimestamp } from "firebase/firestore"; const docRef = doc(db, 'objects', 'some-id'); // Update the timestamp field with the value from the server const updateTimestamp = await updateDoc(docRef, { timestamp: serverTimestamp() });
var docRef = db.collection('objects').doc('some-id'); // Update the timestamp field with the value from the server var updateTimestamp = docRef.update({ timestamp: firebase.firestore.FieldValue.serverTimestamp() });
do { try await db.collection("objects").document("some-id").updateData([ "lastUpdated": FieldValue.serverTimestamp(), ]) print("Document successfully updated") } catch { print("Error updating document: \(error)") }
[[[self.db collectionWithPath:@"objects"] documentWithPath:@"some-id"] updateData:@{ @"lastUpdated": [FIRFieldValue fieldValueForServerTimestamp] } completion:^(NSError * _Nullable error) { if (error != nil) { NSLog(@"Error updating document: %@", error); } else { NSLog(@"Document successfully updated"); } }];
// If you're using custom Kotlin objects in Android, add an @ServerTimestamp // annotation to a Date field for your custom object classes. This indicates // that the Date field should be treated as a server timestamp by the object mapper. val docRef = db.collection("objects").document("some-id") // Update the timestamp field with the value from the server val updates = hashMapOf<String, Any>( "timestamp" to FieldValue.serverTimestamp(), ) docRef.update(updates).addOnCompleteListener { }
// If you're using custom Java objects in Android, add an @ServerTimestamp // annotation to a Date field for your custom object classes. This indicates // that the Date field should be treated as a server timestamp by the object mapper. DocumentReference docRef = db.collection("objects").document("some-id"); // Update the timestamp field with the value from the server Map<String,Object> updates = new HashMap<>(); updates.put("timestamp", FieldValue.serverTimestamp()); docRef.update(updates).addOnCompleteListener(new OnCompleteListener<Void>() { // ... // ...
final docRef = db.collection("objects").doc("some-id"); final updates = <String, dynamic>{ "timestamp": FieldValue.serverTimestamp(), }; docRef.update(updates).then( (value) => print("DocumentSnapshot successfully updated!"), onError: (e) => print("Error updating document $e"));
DocumentReference doc_ref = db->Collection("objects").Document("some-id"); doc_ref.Update({{"timestamp", FieldValue::ServerTimestamp()}}) .OnCompletion([](const Future<void>& future) { // ... });
PHP
Para mais informações sobre como instalar e criar um cliente do Cloud Firestore, consulte Bibliotecas de cliente do Cloud Firestore.
DocumentReference cityRef = db.Collection("cities").Document("new-city-id"); cityRef.UpdateAsync("Timestamp", FieldValue.ServerTimestamp) .ContinueWithOnMainThread(task => { Debug.Log( "Updated the Timestamp field of the new-city-id document in the cities " + "collection."); });
Ao atualizar vários campos de carimbo de data/hora em uma transação, cada campo recebe o mesmo valor de carimbo de data/hora do servidor.
Atualizar campos em objetos aninhados
Se o documento contiver objetos aninhados, será possível usar notação por pontos para
se referir a campos aninhados no documento quando chamar update()
:
import { doc, setDoc, updateDoc } from "firebase/firestore"; // Create an initial document to update. const frankDocRef = doc(db, "users", "frank"); await setDoc(frankDocRef, { name: "Frank", favorites: { food: "Pizza", color: "Blue", subject: "recess" }, age: 12 }); // To update age and favorite color: await updateDoc(frankDocRef, { "age": 13, "favorites.color": "Red" });
// Create an initial document to update. var frankDocRef = db.collection("users").doc("frank"); frankDocRef.set({ name: "Frank", favorites: { food: "Pizza", color: "Blue", subject: "recess" }, age: 12 }); // To update age and favorite color: db.collection("users").doc("frank").update({ "age": 13, "favorites.color": "Red" }) .then(() => { console.log("Document successfully updated!"); });
// Create an initial document to update. let frankDocRef = db.collection("users").document("frank") do { try await frankDocRef.setData([ "name": "Frank", "favorites": [ "food": "Pizza", "color": "Blue", "subject": "recess" ], "age": 12 ]) // To update age and favorite color: try await frankDocRef.updateData([ "age": 13, "favorites.color": "Red" ]) print("Document successfully updated") } catch { print("Error updating document: \(error)") }
// Create an initial document to update. FIRDocumentReference *frankDocRef = [[self.db collectionWithPath:@"users"] documentWithPath:@"frank"]; [frankDocRef setData:@{ @"name": @"Frank", @"favorites": @{ @"food": @"Pizza", @"color": @"Blue", @"subject": @"recess" }, @"age": @12 }]; // To update age and favorite color: [frankDocRef updateData:@{ @"age": @13, @"favorites.color": @"Red", } completion:^(NSError * _Nullable error) { if (error != nil) { NSLog(@"Error updating document: %@", error); } else { NSLog(@"Document successfully updated"); } }];
// Assume the document contains: // { // name: "Frank", // favorites: { food: "Pizza", color: "Blue", subject: "recess" } // age: 12 // } // // To update age and favorite color: db.collection("users").document("frank") .update( mapOf( "age" to 13, "favorites.color" to "Red", ), )
// Assume the document contains: // { // name: "Frank", // favorites: { food: "Pizza", color: "Blue", subject: "recess" } // age: 12 // } // // To update age and favorite color: db.collection("users").document("frank") .update( "age", 13, "favorites.color", "Red" );
// Assume the document contains: // { // name: "Frank", // favorites: { food: "Pizza", color: "Blue", subject: "recess" } // age: 12 // } db .collection("users") .doc("frank") .update({"age": 13, "favorites.color": "Red"});
// Assume the document contains: // { // name: "Frank", // favorites: { food: "Pizza", color: "Blue", subject: "recess" } // age: 12 // } // // To update age and favorite color: db->Collection("users").Document("frank").Update({ {"age", FieldValue::Integer(13)}, {"favorites.color", FieldValue::String("red")}, });
PHP
Para mais informações sobre como instalar e criar um cliente do Cloud Firestore, consulte Bibliotecas de cliente do Cloud Firestore.
DocumentReference frankDocRef = db.Collection("users").Document("frank"); Dictionary<string, object> initialData = new Dictionary<string, object> { { "Name", "Frank" }, { "Age", 12 } }; Dictionary<string, object> favorites = new Dictionary<string, object> { { "Food", "Pizza" }, { "Color", "Blue" }, { "Subject", "Recess" }, }; initialData.Add("Favorites", favorites); frankDocRef.SetAsync(initialData).ContinueWithOnMainThread(task => { // Update age and favorite color Dictionary<string, object> updates = new Dictionary<string, object> { { "Age", 13 }, { "Favorites.Color", "Red" }, }; // Asynchronously update the document return frankDocRef.UpdateAsync(updates); }).ContinueWithOnMainThread(task => { Debug.Log( "Updated the age and favorite color fields of the Frank document in " + "the users collection."); });
A notação por pontos permite que você atualize um único campo aninhado sem substituir outros campos aninhados. Se você atualizar um campo aninhado sem a notação por pontos, todo o campo do mapa será substituído, conforme mostrado no exemplo a seguir:
// Create our initial doc db.collection("users").doc("frank").set({ name: "Frank", favorites: { food: "Pizza", color: "Blue", subject: "Recess" }, age: 12 }).then(function() { console.log("Frank created"); }); // Update the doc without using dot notation. // Notice the map value for favorites. db.collection("users").doc("frank").update({ favorites: { food: "Ice Cream" } }).then(function() { console.log("Frank food updated"); }); /* Ending State, favorite.color and favorite.subject are no longer present: /users /frank { name: "Frank", favorites: { food: "Ice Cream", }, age: 12 } */
Atualizar elementos em uma matriz
Se o documento contiver um campo de matriz, use arrayUnion()
e arrayRemove()
para adicionar e remover elementos. arrayUnion()
adiciona elementos a uma matriz, mas apenas elementos que ainda não estejam presentes. arrayRemove()
remove todas as instâncias de cada elemento especificado.
import { doc, updateDoc, arrayUnion, arrayRemove } from "firebase/firestore"; const washingtonRef = doc(db, "cities", "DC"); // Atomically add a new region to the "regions" array field. await updateDoc(washingtonRef, { regions: arrayUnion("greater_virginia") }); // Atomically remove a region from the "regions" array field. await updateDoc(washingtonRef, { regions: arrayRemove("east_coast") });
var washingtonRef = db.collection("cities").doc("DC"); // Atomically add a new region to the "regions" array field. washingtonRef.update({ regions: firebase.firestore.FieldValue.arrayUnion("greater_virginia") }); // Atomically remove a region from the "regions" array field. washingtonRef.update({ regions: firebase.firestore.FieldValue.arrayRemove("east_coast") });
let washingtonRef = db.collection("cities").document("DC") // Atomically add a new region to the "regions" array field. washingtonRef.updateData([ "regions": FieldValue.arrayUnion(["greater_virginia"]) ]) // Atomically remove a region from the "regions" array field. washingtonRef.updateData([ "regions": FieldValue.arrayRemove(["east_coast"]) ])
FIRDocumentReference *washingtonRef = [[self.db collectionWithPath:@"cities"] documentWithPath:@"DC"]; // Atomically add a new region to the "regions" array field. [washingtonRef updateData:@{ @"regions": [FIRFieldValue fieldValueForArrayUnion:@[@"greater_virginia"]] }]; // Atomically remove a new region to the "regions" array field. [washingtonRef updateData:@{ @"regions": [FIRFieldValue fieldValueForArrayRemove:@[@"east_coast"]] }];
val washingtonRef = db.collection("cities").document("DC") // Atomically add a new region to the "regions" array field. washingtonRef.update("regions", FieldValue.arrayUnion("greater_virginia")) // Atomically remove a region from the "regions" array field. washingtonRef.update("regions", FieldValue.arrayRemove("east_coast"))
DocumentReference washingtonRef = db.collection("cities").document("DC"); // Atomically add a new region to the "regions" array field. washingtonRef.update("regions", FieldValue.arrayUnion("greater_virginia")); // Atomically remove a region from the "regions" array field. washingtonRef.update("regions", FieldValue.arrayRemove("east_coast"));
final washingtonRef = db.collection("cities").doc("DC"); // Atomically add a new region to the "regions" array field. washingtonRef.update({ "regions": FieldValue.arrayUnion(["greater_virginia"]), }); // Atomically remove a region from the "regions" array field. washingtonRef.update({ "regions": FieldValue.arrayRemove(["east_coast"]), });
// This is not yet supported.
// Not supported yet
PHP
Para mais informações sobre como instalar e criar um cliente do Cloud Firestore, consulte Bibliotecas de cliente do Cloud Firestore.
// This is not yet supported in the Unity SDK
// Not supported yet
Aumentar um valor numérico
É possível aumentar ou diminuir um valor de campo numérico conforme mostrado no exemplo a seguir. Uma operação de incremento aumenta ou diminui o valor atual de um campo de acordo com o valor especificado.
import { doc, updateDoc, increment } from "firebase/firestore"; const washingtonRef = doc(db, "cities", "DC"); // Atomically increment the population of the city by 50. await updateDoc(washingtonRef, { population: increment(50) });
var washingtonRef = db.collection('cities').doc('DC'); // Atomically increment the population of the city by 50. washingtonRef.update({ population: firebase.firestore.FieldValue.increment(50) });
let washingtonRef = db.collection("cities").document("DC") // Atomically increment the population of the city by 50. // Note that increment() with no arguments increments by 1. washingtonRef.updateData([ "population": FieldValue.increment(Int64(50)) ])
FIRDocumentReference *washingtonRef = [[self.db collectionWithPath:@"cities"] documentWithPath:@"DC"]; // Atomically increment the population of the city by 50. // Note that increment() with no arguments increments by 1. [washingtonRef updateData:@{ @"population": [FIRFieldValue fieldValueForIntegerIncrement:50] }];
val washingtonRef = db.collection("cities").document("DC") // Atomically increment the population of the city by 50. washingtonRef.update("population", FieldValue.increment(50))
DocumentReference washingtonRef = db.collection("cities").document("DC"); // Atomically increment the population of the city by 50. washingtonRef.update("population", FieldValue.increment(50));
var washingtonRef = db.collection('cities').doc('DC'); // Atomically increment the population of the city by 50. washingtonRef.update( {"population": FieldValue.increment(50)}, );
// This is not yet supported.
PHP
Para mais informações sobre como instalar e criar um cliente do Cloud Firestore, consulte Bibliotecas de cliente do Cloud Firestore.
// This is not yet supported in the Unity SDK.
As operações de incremento são úteis para implementar contadores. Atualizar um único documento com muita rapidez pode gerar contenção ou erros. Se você precisar atualizar o contador com uma taxa muito alta, consulte a página Contadores distribuídos.