Adicione e atualize dados

Adicione e atualize dados

Este documento explica como definir, adicionar ou atualizar documentos individuais no Firestore. Para escrever dados em massa, consulte o artigo Transações e escritas em lote.

Vista geral

Pode escrever dados no Firestore de uma das seguintes formas:

• Definir os dados de um documento numa coleção, especificando explicitamente um identificador de documento.
• Adicione um novo documento a uma coleção. Neste caso, o Firestore gera automaticamente o identificador do documento.
• Crie um documento vazio com um identificador gerado automaticamente e atribua-lhe dados mais tarde.

Nota: embora os exemplos de código abranjam vários idiomas, o texto que explica os exemplos refere-se aos nomes dos métodos Web.

Antes de começar

Antes de poder inicializar o Firestore para definir, adicionar ou atualizar dados, tem de concluir os seguintes passos:

• Crie uma base de dados do Firestore. Para mais informações, consulte um dos inícios rápidos do Firestore.
• Se usar as bibliotecas de cliente Web ou para dispositivos móveis, autentique com regras de segurança. Para mais informações, consulte o artigo Começar a usar as regras de segurança.
• Se usar as bibliotecas cliente do servidor ou a API REST, faça a autenticação com a gestão de identidade e acesso (IAM). Para mais informações, consulte o artigo Segurança para bibliotecas de cliente do servidor.

Inicialize o Firestore

Inicialize uma instância do Firestore:

Versão Web 9

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 Firestore and get a reference to the service
const db = getFirestore(app);

Substitua FIREBASE_CONFIGURATION pelo firebaseConfig da sua app Web.

Para persistir os dados quando o dispositivo perde a ligação, consulte a documentação Ativar dados offline.

Versão Web 8

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 Firestore and get a reference to the service
const db = firebase.firestore();

Substitua FIREBASE_CONFIGURATION pelo firebaseConfig da sua app Web.

Para persistir os dados quando o dispositivo perde a ligação, consulte a documentação Ativar dados offline.

Swift

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

import FirebaseCore
import FirebaseFirestore

FirebaseApp.configure()

let db = Firestore.firestore()
AppDelegate.swift

Objective-C

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

@import FirebaseCore;
@import FirebaseFirestore;

// Use Firebase library to configure APIs
[FIRApp configure];
  

FIRFirestore *defaultFirestore = [FIRFirestore firestore];
AppDelegate.m

Kotlin
Android

// Access a Firestore instance from your Activity

val db = Firebase.firestore
DocSnippets.kt

Java
Android

// Access a Firestore instance from your Activity

FirebaseFirestore db = FirebaseFirestore.getInstance();
DocSnippets.java

Dart

db = FirebaseFirestore.instance;

Java

import com.google.cloud.firestore.Firestore;
import com.google.cloud.firestore.FirestoreOptions;

FirestoreOptions firestoreOptions =
    FirestoreOptions.getDefaultInstance().toBuilder()
        .setProjectId(projectId)
        .setCredentials(GoogleCredentials.getApplicationDefault())
        .build();
Firestore db = firestoreOptions.getService();
Quickstart.java

Python

from google.cloud import firestore

# The `project` parameter is optional and represents which project the client
# will act on behalf of. If not supplied, the client falls back to the default
# project inferred from the environment.
db = firestore.Client(project="my-project-id")
snippets.py

Python
(assíncrono)

from google.cloud import firestore

# The `project` parameter is optional and represents which project the client
# will act on behalf of. If not supplied, the client falls back to the default
# project inferred from the environment.
db = firestore.AsyncClient(project="my-project-id")
snippets.py

C++

// Make sure the call to `Create()` happens some time before you call Firestore::GetInstance().
App::Create();
Firestore* db = Firestore::GetInstance();
AppDelegate.mm

Node.js

const Firestore = require('@google-cloud/firestore');

const db = new Firestore({
  projectId: 'YOUR_PROJECT_ID',
  keyFilename: '/path/to/keyfile.json',
});

Go

import (
	"context"
	"flag"
	"fmt"
	"log"

	"google.golang.org/api/iterator"

	"cloud.google.com/go/firestore"
)

func createClient(ctx context.Context) *firestore.Client {
	// Sets your Google Cloud Platform project ID.
	projectID := "YOUR_PROJECT_ID"

	client, err := firestore.NewClient(ctx, projectID)
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}
	// Close client when done with
	// defer client.Close()
	return client
}
main.go

PHP

PHP

Para se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

use Google\Cloud\Firestore\FirestoreClient;

/**
 * Initialize Cloud Firestore with default project ID.
 */
function setup_client_create(string $projectId = null)
{
    // Create the Cloud Firestore client
    if (empty($projectId)) {
        // The `projectId` parameter is optional and represents which project the
        // client will act on behalf of. If not supplied, the client falls back to
        // the default project inferred from the environment.
        $db = new FirestoreClient();
        printf('Created Cloud Firestore client with default project ID.' . PHP_EOL);
    } else {
        $db = new FirestoreClient([
            'projectId' => $projectId,
        ]);
        printf('Created Cloud Firestore client with project ID: %s' . PHP_EOL, $projectId);
    }
}

Unity

using Firebase.Firestore;
using Firebase.Extensions;

FirebaseFirestore db = FirebaseFirestore.DefaultInstance;

C#

C#

Para se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

FirestoreDb db = FirestoreDb.Create(project);
Console.WriteLine("Created Cloud Firestore client with project ID: {0}", project);

Ruby

require "google/cloud/firestore"

# The `project_id` parameter is optional and represents which project the
# client will act on behalf of. If not supplied, the client falls back to the
# default project inferred from the environment.
firestore = Google::Cloud::Firestore.new project_id: project_id

puts "Created Cloud Firestore client with given project ID."
quickstart.rb

Defina um documento

Para criar ou substituir um único documento, use os seguintes métodos set() específicos do idioma:

Versão Web 9

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"
});
set_document.js

Versão Web 8

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);
});
test.firestore.js

Swift

Use o método setData():

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

// 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)")
}
ViewController.swift

Objective-C

Use o método setData::

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

// 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!");
  }
}];
ViewController.m

Kotlin
Android

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) }
DocSnippets.kt

Java
Android

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);
            }
        });
DocSnippets.java

Dart

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"));
firestore.dart

Java

Use o método set():

// Create a Map to store the data we want to set
Map<String, Object> docData = new HashMap<>();
docData.put("name", "Los Angeles");
docData.put("state", "CA");
docData.put("country", "USA");
docData.put("regions", Arrays.asList("west_coast", "socal"));
// Add a new document (asynchronously) in collection "cities" with id "LA"
ApiFuture<WriteResult> future = db.collection("cities").document("LA").set(docData);
// ...
// future.get() blocks on response
System.out.println("Update time : " + future.get().getUpdateTime());
ManageDataSnippets.java

Python

Use o método set():

data = {"name": "Los Angeles", "state": "CA", "country": "USA"}

# Add a new doc in collection 'cities' with ID 'LA'
db.collection("cities").document("LA").set(data)
snippets.py

Python
(assíncrono)

Use o método set():

data = {"name": "Los Angeles", "state": "CA", "country": "USA"}

# Add a new doc in collection 'cities' with ID 'LA'
await db.collection("cities").document("LA").set(data)
snippets.py

C++

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;
      }
    });
snippets.cpp

Node.js

Use o método set():

const data = {
  name: 'Los Angeles',
  state: 'CA',
  country: 'USA'
};

// Add a new document in collection "cities" with ID 'LA'
const res = await db.collection('cities').doc('LA').set(data);
index.js

Go

Use o método Set():

import (
	"context"
	"log"

	"cloud.google.com/go/firestore"
)

func addDocAsMap(ctx context.Context, client *firestore.Client) error {
	_, err := client.Collection("cities").Doc("LA").Set(ctx, map[string]interface{}{
		"name":    "Los Angeles",
		"state":   "CA",
		"country": "USA",
	})
	if err != nil {
		// Handle any errors in an appropriate way, such as returning them.
		log.Printf("An error has occurred: %s", err)
	}

	return err
}
save_data_set_from_map.go

PHP

Use o método set():

PHP

Para se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

$data = [
    'name' => 'Los Angeles',
    'state' => 'CA',
    'country' => 'USA'
];
$db->collection('samples/php/cities')->document('LA')->set($data);

Unity

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.");
});

C#

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" }
};
await docRef.SetAsync(city);
Program.cs

Ruby

Use o método set():

city_ref = firestore.doc "#{collection_path}/LA"

data = {
  name:    "Los Angeles",
  state:   "CA",
  country: "USA"
}

city_ref.set data
add_data.rb

Se o documento não existir, é criado. Se o documento existir, o respetivo conteúdo é substituído pelos dados fornecidos recentemente, a menos que especifique que os dados devem ser unidos no documento existente, da seguinte forma:

Versão Web 9

import { doc, setDoc } from "firebase/firestore"; 

const cityRef = doc(db, 'cities', 'BJ');
setDoc(cityRef, { capital: true }, { merge: true });
set_with_merge.js

Versão Web 8

Saiba mais acerca da API Web modular com eliminação de código não utilizado e das respetivas vantagens em relação à API com espaço de nomes.

var cityRef = db.collection('cities').doc('BJ');

var setWithMerge = cityRef.set({
    capital: true
}, { merge: true });
test.firestore.js

Swift

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

// Update one field, creating the document if it does not exist.
db.collection("cities").document("BJ").setData([ "capital": true ], merge: true)
ViewController.swift

Objective-C

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

// 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) {
       // ...
     }];
ViewController.m

Kotlin
Android

// 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())
DocSnippets.kt

Java
Android

// 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());
DocSnippets.java

Dart

// 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));
firestore.dart

Java

// asynchronously update doc, create the document if missing
Map<String, Object> update = new HashMap<>();
update.put("capital", true);

ApiFuture<WriteResult> writeResult =
    db.collection("cities").document("BJ").set(update, SetOptions.merge());
// ...
System.out.println("Update time : " + writeResult.get().getUpdateTime());
ManageDataSnippets.java

Python

city_ref = db.collection("cities").document("BJ")

city_ref.set({"capital": True}, merge=True)
snippets.py

Python
(assíncrono)

city_ref = db.collection("cities").document("BJ")

await city_ref.set({"capital": True}, merge=True)
snippets.py

C++

db->Collection("cities").Document("BJ").Set(
    {{"capital", FieldValue::Boolean(true)}}, SetOptions::Merge());
snippets.cpp

Node.js

const cityRef = db.collection('cities').doc('BJ');

const res = await cityRef.set({
  capital: true
}, { merge: true });
index.js

Go

import (
	"context"
	"log"

	"cloud.google.com/go/firestore"
)

func updateDocCreateIfMissing(ctx context.Context, client *firestore.Client) error {
	_, err := client.Collection("cities").Doc("BJ").Set(ctx, map[string]interface{}{
		"capital": true,
	}, firestore.MergeAll)

	if err != nil {
		// Handle any errors in an appropriate way, such as returning them.
		log.Printf("An error has occurred: %s", err)
	}

	return err
}
save_data_set_doc_upsert.go

PHP

PHP

Para se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

$cityRef = $db->collection('samples/php/cities')->document('BJ');
$cityRef->set([
    'capital' => true
], ['merge' => true]);

Unity

DocumentReference docRef = db.Collection("cities").Document("LA");
Dictionary<string, object> update = new Dictionary<string, object>
{
	{ "capital", false }
};
docRef.SetAsync(update, SetOptions.MergeAll);

C#

DocumentReference docRef = db.Collection("cities").Document("LA");
Dictionary<string, object> update = new Dictionary<string, object>
{
    { "capital", false }
};
await docRef.SetAsync(update, SetOptions.MergeAll);
Program.cs

Ruby

city_ref = firestore.doc "#{collection_path}/LA"
city_ref.set({ capital: false }, merge: true)
add_data.rb

Se não tiver a certeza de que o documento existe, transmita a opção para unir os novos dados com qualquer documento existente para evitar substituir documentos inteiros. Para documentos que contêm mapas, se especificar um conjunto com um campo que contém um mapa vazio, o campo de mapa do documento de destino é substituído.

Tipos de dados

O Firestore permite-lhe escrever vários tipos de dados num documento, incluindo strings, valores booleanos, números, datas, valores nulos e objetos e matrizes aninhados. O Firestore armazena sempre números como doubles, independentemente do tipo de número que usa no seu código.

Versão Web 9

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);
data_types.js

Versão Web 8

Saiba mais acerca da API Web modular com eliminação de código não utilizado e das respetivas vantagens em relação à API com espaço de nomes.

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!");
});
test.firestore.js

Swift

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

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)")
}
ViewController.swift

Objective-C

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

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!");
      }
    }];
ViewController.m

Kotlin
Android

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) }
DocSnippets.kt

Java
Android

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);
            }
        });
DocSnippets.java

Dart

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"));
firestore.dart

Java

Map<String, Object> docData = new HashMap<>();
docData.put("stringExample", "Hello, World");
docData.put("booleanExample", false);
docData.put("numberExample", 3.14159265);
docData.put("nullExample", null);

ArrayList<Object> arrayExample = new ArrayList<>();
Collections.addAll(arrayExample, 5L, true, "hello");
docData.put("arrayExample", arrayExample);

Map<String, Object> objectExample = new HashMap<>();
objectExample.put("a", 5L);
objectExample.put("b", true);

docData.put("objectExample", objectExample);

ApiFuture<WriteResult> future = db.collection("data").document("one").set(docData);
System.out.println("Update time : " + future.get().getUpdateTime());
ManageDataSnippets.java

Python

data = {
    "stringExample": "Hello, World!",
    "booleanExample": True,
    "numberExample": 3.14159265,
    "dateExample": datetime.datetime.now(tz=datetime.timezone.utc),
    "arrayExample": [5, True, "hello"],
    "nullExample": None,
    "objectExample": {"a": 5, "b": True},
}

db.collection("data").document("one").set(data)
snippets.py

Python
(assíncrono)

data = {
    "stringExample": "Hello, World!",
    "booleanExample": True,
    "numberExample": 3.14159265,
    "dateExample": datetime.datetime.now(tz=datetime.timezone.utc),
    "arrayExample": [5, True, "hello"],
    "nullExample": None,
    "objectExample": {"a": 5, "b": True},
}

await db.collection("data").document("one").set(data)
snippets.py

C++

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;
      }
    });
snippets.cpp

Node.js

const data = {
  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: true
  }
};

const res = await db.collection('data').doc('one').set(data);
index.js

Go

import (
	"context"
	"log"
	"time"

	"cloud.google.com/go/firestore"
)

func addDocDataTypes(ctx context.Context, client *firestore.Client) error {
	doc := make(map[string]interface{})
	doc["stringExample"] = "Hello world!"
	doc["booleanExample"] = true
	doc["numberExample"] = 3.14159265
	doc["dateExample"] = time.Now()
	doc["arrayExample"] = []interface{}{5, true, "hello"}
	doc["nullExample"] = nil
	doc["objectExample"] = map[string]interface{}{
		"a": 5,
		"b": true,
	}

	_, err := client.Collection("data").Doc("one").Set(ctx, doc)
	if err != nil {
		// Handle any errors in an appropriate way, such as returning them.
		log.Printf("An error has occurred: %s", err)
	}

	return err
}
save_data_set_from_map_nested.go

PHP

PHP

Para se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

$data = [
    'stringExample' => 'Hello World',
    'booleanExample' => true,
    'numberExample' => 3.14159265,
    'dateExample' => new Timestamp(new DateTime()),
    'arrayExample' => array(5, true, 'hello'),
    'nullExample' => null,
    'objectExample' => ['a' => 5, 'b' => true],
    'documentReferenceExample' => $db->collection('samples/php/data')->document('two'),
];
$db->collection('samples/php/data')->document('one')->set($data);
printf('Set multiple data-type data for the one document in the data collection.' . PHP_EOL);

Unity

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);

C#

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 object[] { 5, true, "Hello" } },
    { "objectExample", new Dictionary<string, object>
        {
            { "a", 5 },
            { "b", true},
        }
    }
};

await docRef.SetAsync(docData);
Program.cs

Ruby

doc_ref = firestore.doc "#{collection_path}/one"

data = {
  stringExample:  "Hello, World!",
  booleanExample: true,
  numberExample:  3.14159265,
  dateExample:    DateTime.now,
  arrayExample:   [5, true, "hello"],
  nullExample:    nil,
  objectExample:  {
    a: 5,
    b: true
  }
}

doc_ref.set data
add_data.rb

Objetos personalizados

A utilização de objetos Map ou Dictionary para representar os seus documentos é frequentemente inconveniente, pelo que o Firestore suporta a escrita de documentos com classes personalizadas. O Firestore converte os objetos em tipos de dados suportados.

Usando classes personalizadas, pode reescrever o exemplo inicial da seguinte forma:

Versão Web 9

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);
    }
};
city_custom_object.js

Versão Web 8

Saiba mais acerca da API Web modular com eliminação de código não utilizado e das respetivas vantagens em relação à API com espaço de nomes.

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);
    }
};
test.firestore.js

Swift

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

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
  }

}
ViewController.swift

Objective-C

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

// This isn't supported in Objective-C.
  

Kotlin
Android

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,
)
DocSnippets.kt

Java
Android

Cada classe personalizada tem de ter um construtor público que não receba argumentos. Além disso, a classe tem de 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;
    }

}
DocSnippets.java

Dart

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,
    };
  }
}
firestore_add_data_custom_objects_snippet.dart

Java

public City() {
  // Must have a public no-argument constructor
}

// Initialize all fields of a city
public City(
    String name,
    String state,
    String country,
    Boolean capital,
    Long population,
    List<String> regions) {
  this.name = name;
  this.state = state;
  this.country = country;
  this.capital = capital;
  this.population = population;
  this.regions = regions;
}
City.java

Python

class City:
    def __init__(self, name, state, country, capital=False, population=0, regions=[]):
        self.name = name
        self.state = state
        self.country = country
        self.capital = capital
        self.population = population
        self.regions = regions

    @staticmethod
    def from_dict(source):
        # ...

    def to_dict(self):
        # ...

    def __repr__(self):
        return f"City(\
                name={self.name}, \
                country={self.country}, \
                population={self.population}, \
                capital={self.capital}, \
                regions={self.regions}\
            )"

snippets.py

Python
(assíncrono)

class City:
    def __init__(self, name, state, country, capital=False, population=0, regions=[]):
        self.name = name
        self.state = state
        self.country = country
        self.capital = capital
        self.population = population
        self.regions = regions

    @staticmethod
    def from_dict(source):
        # ...

    def to_dict(self):
        # ...

    def __repr__(self):
        return f"City(\
                name={self.name}, \
                country={self.country}, \
                population={self.population}, \
                capital={self.capital}, \
                regions={self.regions}\
            )"

snippets.py

C++

// This is not yet supported.

Node.js

// Node.js uses JavaScript objects

Go

// City represents a city.
type City struct {
	Name       string   `firestore:"name,omitempty"`
	State      string   `firestore:"state,omitempty"`
	Country    string   `firestore:"country,omitempty"`
	Capital    bool     `firestore:"capital,omitempty"`
	Population int64    `firestore:"population,omitempty"`
	Density    int64    `firestore:"density,omitempty"`
	Regions    []string `firestore:"regions,omitempty"`
}
custom_type_definition.go

PHP

PHP

Para se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

class City
{
    /** @var string */
    public $name;
    /** @var string */
    public $state;
    /** @var string */
    public $country;
    /** @var bool */
    public $capital;
    /** @var int */
    public $population;
    /** @var array<string> */
    public $regions;

    /**
     * @param array<string> $regions
     */
    public function __construct(
        string $name,
        string $state,
        string $country,
        bool $capital = false,
        int $population = 0,
        array $regions = []
    ) {
        $this->name = $name;
        $this->state = $state;
        $this->country = $country;
        $this->capital = $capital;
        $this->population = $population;
        $this->regions = $regions;
    }

    /**
     * @param array<mixed> $source
     */
    public static function fromArray(array $source): City
    {
        // implementation of fromArray is excluded for brevity
        # ...
    }

    /**
     * @return array<mixed>
     */
    public function toArray(): array
    {
        // implementation of toArray is excluded for brevity
        # ...
    }

    public function __toString()
    {
        // implementation of __toString is excluded for brevity
        # ...
    }
}

Unity

[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; }
}

C#

[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; }
}
Program.cs

Ruby

// This isn't supported in Ruby

Versão Web 9

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_custom_object.js

Versão Web 8

Saiba mais acerca da API Web modular com eliminação de código não utilizado e das respetivas vantagens em relação à API com espaço de nomes.

// Set with cityConverter
db.collection("cities").doc("LA")
  .withConverter(cityConverter)
  .set(new City("Los Angeles", "CA", "USA"));
test.firestore.js

Swift

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

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)")
}
ViewController.swift

Objective-C

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

// This isn't supported in Objective-C.
  

Kotlin
Android

val city = City(
    "Los Angeles",
    "CA",
    "USA",
    false,
    5000000L,
    listOf("west_coast", "socal"),
)
db.collection("cities").document("LA").set(city)
DocSnippets.kt

Java
Android

City city = new City("Los Angeles", "CA", "USA",
        false, 5000000L, Arrays.asList("west_coast", "sorcal"));
db.collection("cities").document("LA").set(city);
DocSnippets.java

Dart

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);
firestore.dart

Java

City city =
    new City("Los Angeles", "CA", "USA", false, 3900000L, Arrays.asList("west_coast", "socal"));
ApiFuture<WriteResult> future = db.collection("cities").document("LA").set(city);
// block on response if required
System.out.println("Update time : " + future.get().getUpdateTime());
ManageDataSnippets.java

Python

city = City(name="Los Angeles", state="CA", country="USA")
db.collection("cities").document("LA").set(city.to_dict())
snippets.py

Python
(assíncrono)

city = City(name="Los Angeles", state="CA", country="USA")
await db.collection("cities").document("LA").set(city.to_dict())
snippets.py

C++

// This is not yet supported.

Node.js

// Node.js uses JavaScript objects

Go

import (
	"context"
	"log"

	"cloud.google.com/go/firestore"
)

func addDocAsEntity(ctx context.Context, client *firestore.Client) error {
	city := City{
		Name:    "Los Angeles",
		Country: "USA",
	}
	_, err := client.Collection("cities").Doc("LA").Set(ctx, city)
	if err != nil {
		// Handle any errors in an appropriate way, such as returning them.
		log.Printf("An error has occurred: %s", err)
	}

	return err
}
save_data_set_from_custom_type.go

PHP

// This isn't supported in PHP.

Unity

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);

C#

DocumentReference docRef = db.Collection("cities").Document("LA");
City city = new City
{
    Name = "Los Angeles",
    State = "CA",
    Country = "USA",
    Capital = false,
    Population = 3900000L
};
await docRef.SetAsync(city);
Program.cs

Ruby

// This isn't supported in Ruby.

Adicione um documento

Quando usa set() para criar um documento, tem de especificar um ID para o documento a criar, conforme mostrado no exemplo seguinte:

Versão Web 9

import { doc, setDoc } from "firebase/firestore"; 

await setDoc(doc(db, "cities", "new-city-id"), data);
cities_document_set.js

Versão Web 8

Saiba mais acerca da API Web modular com eliminação de código não utilizado e das respetivas vantagens em relação à API com espaço de nomes.

db.collection("cities").doc("new-city-id").set(data);
test.firestore.js

Swift

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

db.collection("cities").document("new-city-id").setData(data)
ViewController.swift

Objective-C

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

[[[self.db collectionWithPath:@"cities"] documentWithPath:@"new-city-id"]
    setData:data];
ViewController.m

Kotlin
Android

db.collection("cities").document("new-city-id").set(data)
DocSnippets.kt

Java
Android

db.collection("cities").document("new-city-id").set(data);
DocSnippets.java

Dart

db.collection("cities").doc("new-city-id").set({"name": "Chicago"});
firestore.dart

Java

db.collection("cities").document("new-city-id").set(data);
ManageDataSnippets.java

Python

db.collection("cities").document("new-city-id").set(data)
snippets.py

Python
(assíncrono)

await db.collection("cities").document("new-city-id").set(data)
snippets.py

C++

db->Collection("cities").Document("SF").Set({/*some data*/});
snippets.cpp

Node.js

await db.collection('cities').doc('new-city-id').set(data);
index.js

Go

import (
	"context"
	"log"

	"cloud.google.com/go/firestore"
)

func addDocWithID(ctx context.Context, client *firestore.Client) error {
	var data = make(map[string]interface{})

	_, err := client.Collection("cities").Doc("new-city-id").Set(ctx, data)
	if err != nil {
		// Handle any errors in an appropriate way, such as returning them.
		log.Printf("An error has occurred: %s", err)
	}

	return err
}
save_data_set_id_specified.go

PHP

PHP

Para se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

$db->collection('samples/php/cities')->document('new-city-id')->set($data);

Unity

db.Collection("cities").Document("new-city-id").SetAsync(city);

C#

await db.Collection("cities").Document("new-city-id").SetAsync(city);
Program.cs

Ruby

city_ref = firestore.doc "#{collection_path}/new-city-id"
city_ref.set data
add_data.rb

Se não existir um ID significativo para o documento, o Firestore pode gerar automaticamente um ID para si. Pode chamar os seguintes métodos add() específicos do idioma:

Versão Web 9

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);
add_document.js

Versão Web 8

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);
});
test.firestore.js

Swift

Use o método addDocument():

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

// 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)")
}
ViewController.swift

Objective-C

Use o método addDocumentWithData::

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

// 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);
      }
    }];
ViewController.m

Kotlin
Android

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)
    }
DocSnippets.kt

Java
Android

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);
            }
        });
DocSnippets.java

Dart

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}"));
firestore.dart

Java

Use o método add():

// Add document data with auto-generated id.
Map<String, Object> data = new HashMap<>();
data.put("name", "Tokyo");
data.put("country", "Japan");
ApiFuture<DocumentReference> addedDocRef = db.collection("cities").add(data);
System.out.println("Added document with ID: " + addedDocRef.get().getId());
ManageDataSnippets.java

Python

Use o método add():

city = {"name": "Tokyo", "country": "Japan"}
update_time, city_ref = db.collection("cities").add(city)
print(f"Added document with id {city_ref.id}")
snippets.py

Python
(assíncrono)

Use o método add():

city = City(name="Tokyo", state=None, country="Japan")
await db.collection("cities").add(city.to_dict())
snippets.py

C++

Use o método Add():

db->Collection("cities").Add({/*some data*/});
snippets.cpp

Node.js

Use o método add():

// Add a new document with a generated id.
const res = await db.collection('cities').add({
  name: 'Tokyo',
  country: 'Japan'
});

console.log('Added document with ID: ', res.id);
index.js

Go

Use o método Add():

import (
	"context"
	"log"

	"cloud.google.com/go/firestore"
)

func addDocWithoutID(ctx context.Context, client *firestore.Client) error {
	_, _, err := client.Collection("cities").Add(ctx, map[string]interface{}{
		"name":    "Tokyo",
		"country": "Japan",
	})
	if err != nil {
		// Handle any errors in an appropriate way, such as returning them.
		log.Printf("An error has occurred: %s", err)
	}

	return err
}
save_data_set_id_random_collection.go

PHP

Use o método add():

PHP

Para se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

$data = [
    'name' => 'Tokyo',
    'country' => 'Japan'
];
$addedDocRef = $db->collection('samples/php/cities')->add($data);
printf('Added document with ID: %s' . PHP_EOL, $addedDocRef->id());

Unity

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));
});

C#

Use o método AddAsync():

Dictionary<string, object> city = new Dictionary<string, object>
{
    { "Name", "Tokyo" },
    { "Country", "Japan" }
};
DocumentReference addedDocRef = await db.Collection("cities").AddAsync(city);
Console.WriteLine("Added document with ID: {0}.", addedDocRef.Id);
Program.cs

Ruby

Use o método add():

data = {
  name:    "Tokyo",
  country: "Japan"
}

cities_ref = firestore.col collection_path

added_doc_ref = cities_ref.add data
puts "Added document with ID: #{added_doc_ref.document_id}."
add_data.rb

Os exemplos mostram a adição de dados a uma coleção de nível superior, como cities. O Firestore também suporta subcoleções em documentos, como cities/LA/landmarks. Os mesmos métodos set(), add() e update() aplicam-se quando trabalha com subcoleções.

Importante: ao contrário dos "push IDs" na base de dados em tempo real do Firebase, os IDs gerados automaticamente do Firestore não oferecem qualquer ordenação automática. Se quiser ordenar os seus documentos por data de criação, armazene uma data/hora como um campo nos documentos.

Em alguns casos, pode ser útil criar uma referência de documento com um ID gerado automaticamente e, em seguida, usar a referência mais tarde. Para este exemplo de utilização, pode chamar doc() da seguinte forma:

Versão Web 9

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);
new_document.js

Versão Web 8

Saiba mais acerca da API Web modular com eliminação de código não utilizado e das respetivas vantagens em relação à API com espaço de nomes.

// Add a new document with a generated id.
var newCityRef = db.collection("cities").doc();

// later...
newCityRef.set(data);
test.firestore.js

Swift

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

let newCityRef = db.collection("cities").document()

// later...
newCityRef.setData([
  // ...
])
ViewController.swift

Objective-C

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

FIRDocumentReference *newCityRef = [[self.db collectionWithPath:@"cities"] documentWithAutoID];
// later...
[newCityRef setData:@{ /* ... */ }];
ViewController.m

Kotlin
Android

val data = HashMap<String, Any>()

val newCityRef = db.collection("cities").document()

// Later...
newCityRef.set(data)
DocSnippets.kt

Java
Android

Map<String, Object> data = new HashMap<>();

DocumentReference newCityRef = db.collection("cities").document();

// Later...
newCityRef.set(data);
DocSnippets.java

Dart

// Add a new document with a generated id.
final data = <String, dynamic>{};

final newCityRef = db.collection("cities").doc();

// Later...
newCityRef.set(data);
firestore.dart

Java

// Add document data after generating an id.
DocumentReference addedDocRef = db.collection("cities").document();
System.out.println("Added document with ID: " + addedDocRef.getId());

// later...
ApiFuture<WriteResult> writeResult = addedDocRef.set(data);
ManageDataSnippets.java

Python

new_city_ref = db.collection("cities").document()

# later...
new_city_ref.set(
    {
        # ...
    }
)
snippets.py

Python
(assíncrono)

new_city_ref = db.collection("cities").document()

# later...
await new_city_ref.set(
    {
        # ...
    }
)
snippets.py

C++

DocumentReference new_city_ref = db->Collection("cities").Document();
snippets.cpp

Node.js

const newCityRef = db.collection('cities').doc();

// Later...
const res = await newCityRef.set({
  // ...
});
index.js

Go

import (
	"context"
	"log"

	"cloud.google.com/go/firestore"
)

func addDocAfterAutoGeneratedID(ctx context.Context, client *firestore.Client) error {
	data := City{
		Name:    "Sydney",
		Country: "Australia",
	}

	ref := client.Collection("cities").NewDoc()

	// later...
	_, err := ref.Set(ctx, data)
	if err != nil {
		// Handle any errors in an appropriate way, such as returning them.
		log.Printf("An error has occurred: %s", err)
	}

	return err
}
save_data_set_id_random_document_ref.go

PHP

PHP

Para se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

$addedDocRef = $db->collection('samples/php/cities')->newDocument();
printf('Added document with ID: %s' . PHP_EOL, $addedDocRef->id());
$addedDocRef->set($data);

Unity

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));
});

C#

DocumentReference addedDocRef = db.Collection("cities").Document();
Console.WriteLine("Added document with ID: {0}.", addedDocRef.Id);
await addedDocRef.SetAsync(city);
Program.cs

Ruby

cities_ref = firestore.col collection_path

added_doc_ref = cities_ref.doc
puts "Added document with ID: #{added_doc_ref.document_id}."

added_doc_ref.set data
add_data.rb

No back-end, .add(...) e .doc().set(...) são equivalentes, pelo que pode usar qualquer uma das opções.

Atualize um documento

Para atualizar alguns campos de um documento sem substituir o documento inteiro, use os seguintes métodos update() específicos do idioma:

Versão Web 9

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
});
update_document.js

Versão Web 8

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);
});
test.firestore.js

Swift

Use o método updateData():

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

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)")
}
ViewController.swift

Objective-C

Use o método updateData::

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

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");
  }
}];
ViewController.m

Kotlin
Android

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) }
DocSnippets.kt

Java
Android

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);
            }
        });
DocSnippets.java

Dart

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"));
firestore.dart

Java

Use o método update():

// Update an existing document
DocumentReference docRef = db.collection("cities").document("DC");

// (async) Update one field
ApiFuture<WriteResult> future = docRef.update("capital", true);

// ...
WriteResult result = future.get();
System.out.println("Write result: " + result);
ManageDataSnippets.java

Python

Use o método update():

city_ref = db.collection("cities").document("DC")

# Set the capital field
city_ref.update({"capital": True})
snippets.py

Python
(assíncrono)

Use o método update():

city_ref = db.collection("cities").document("DC")

# Set the capital field
await city_ref.update({"capital": True})
snippets.py

C++

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)}});
snippets.cpp

Node.js

Use o método update():

const cityRef = db.collection('cities').doc('DC');

// Set the 'capital' field of the city
const res = await cityRef.update({capital: true});
index.js

Go

Use o método Update():

import (
	"context"
	"log"

	"cloud.google.com/go/firestore"
)

func updateDoc(ctx context.Context, client *firestore.Client) error {
	// ...

	_, err := client.Collection("cities").Doc("DC").Update(ctx, []firestore.Update{
		{
			Path:  "capital",
			Value: true,
		},
	})
	if err != nil {
		// Handle any errors in an appropriate way, such as returning them.
		log.Printf("An error has occurred: %s", err)
	}

	return err
}
save_data_set_field.go

PHP

Use o método update():

PHP

Para se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

$cityRef = $db->collection('samples/php/cities')->document('DC');
$cityRef->update([
    ['path' => 'capital', 'value' => true]
]);

Unity

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);

C#

Use o método UpdateAsync():

DocumentReference cityRef = db.Collection("cities").Document("new-city-id");
Dictionary<string, object> updates = new Dictionary<string, object>
{
    { "Capital", false }
};
await cityRef.UpdateAsync(updates);

// You can also update a single field with: await cityRef.UpdateAsync("Capital", false);
Program.cs

Ruby

Use o método update():

city_ref = firestore.doc "#{collection_path}/DC"
city_ref.update({ capital: true })
add_data.rb

Data/hora do servidor

Pode definir um campo no seu documento para uma data/hora do servidor que monitoriza quando o servidor recebe a atualização.

Versão Web 9

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()
});
update_with_server_timestamp.js

Versão Web 8

Saiba mais acerca da API Web modular com eliminação de código não utilizado e das respetivas vantagens em relação à API com espaço de nomes.

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()
});
test.firestore.js

Swift

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

do {
  try await db.collection("objects").document("some-id").updateData([
    "lastUpdated": FieldValue.serverTimestamp(),
  ])
  print("Document successfully updated")
} catch {
  print("Error updating document: \(error)")
}
ViewController.swift

Objective-C

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

[[[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");
  }
}];
ViewController.m

Kotlin
Android

// 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 { }
DocSnippets.kt

Java
Android

// 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>() {
    // ...
    // ...
DocSnippets.java

Dart

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"));
firestore.dart

Java

DocumentReference docRef = db.collection("objects").document("some-id");
// Update the timestamp field with the value from the server
ApiFuture<WriteResult> writeResult = docRef.update("timestamp", FieldValue.serverTimestamp());
System.out.println("Update time : " + writeResult.get());
ManageDataSnippets.java

Python

city_ref = db.collection("objects").document("some-id")
city_ref.update({"timestamp": firestore.SERVER_TIMESTAMP})
snippets.py

Python
(assíncrono)

city_ref = db.collection("objects").document("some-id")
await city_ref.update({"timestamp": firestore.SERVER_TIMESTAMP})
snippets.py

C++

DocumentReference doc_ref = db->Collection("objects").Document("some-id");
doc_ref.Update({{"timestamp", FieldValue::ServerTimestamp()}})
    .OnCompletion([](const Future<void>& future) {
      // ...
    });
snippets.cpp

Node.js

// Create a document reference
const docRef = db.collection('objects').doc('some-id');

// Update the timestamp field with the value from the server
const res = await docRef.update({
  timestamp: FieldValue.serverTimestamp()
});
index.js

Go

import (
	"context"
	"log"

	"cloud.google.com/go/firestore"
)

func updateDocServerTimestamp(ctx context.Context, client *firestore.Client) error {
	// ...

	_, err := client.Collection("objects").Doc("some-id").Set(ctx, map[string]interface{}{
		"timestamp": firestore.ServerTimestamp,
	}, firestore.MergeAll)
	if err != nil {
		// Handle any errors in an appropriate way, such as returning them.
		log.Printf("An error has occurred: %s", err)
	}

	return err
}
save_data_set_server_timestamp.go

PHP

PHP

Para se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

$docRef = $db->collection('samples/php/objects')->document('some-id');
$docRef->update([
    ['path' => 'timestamp', 'value' => FieldValue::serverTimestamp()]
]);

Unity

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.");
	});

C#

DocumentReference cityRef = db.Collection("cities").Document("new-city-id");
await cityRef.UpdateAsync("Timestamp", Timestamp.GetCurrentTimestamp());
Program.cs

Ruby

city_ref = firestore.doc "#{collection_path}/new-city-id"
city_ref.update({ timestamp: firestore.field_server_time })
add_data.rb

Quando atualiza vários campos de data/hora numa transação, cada campo recebe o mesmo valor de data/hora do servidor.

Atualize campos em objetos aninhados

Se o seu documento contiver objetos aninhados, pode usar a notação de ponto para fazer referência a campos aninhados no documento quando chamar update():

Versão Web 9

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"
});
update_document_nested.js

Versão Web 8

Saiba mais acerca da API Web modular com eliminação de código não utilizado e das respetivas vantagens em relação à API com espaço de nomes.

// 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!");
});
test.firestore.js

Swift

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

// 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)")
}
ViewController.swift

Objective-C

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

// 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");
  }
}];
ViewController.m

Kotlin
Android

// 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",
        ),
    )
DocSnippets.kt

Java
Android

// 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"
        );
DocSnippets.java

Dart

// 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"});
firestore.dart

Java

// Create an initial document to update
DocumentReference frankDocRef = db.collection("users").document("frank");
Map<String, Object> initialData = new HashMap<>();
initialData.put("name", "Frank");
initialData.put("age", 12);

Map<String, Object> favorites = new HashMap<>();
favorites.put("food", "Pizza");
favorites.put("color", "Blue");
favorites.put("subject", "Recess");
initialData.put("favorites", favorites);

ApiFuture<WriteResult> initialResult = frankDocRef.set(initialData);
// Confirm that data has been successfully saved by blocking on the operation
initialResult.get();

// Update age and favorite color
Map<String, Object> updates = new HashMap<>();
updates.put("age", 13);
updates.put("favorites.color", "Red");

// Async update document
ApiFuture<WriteResult> writeResult = frankDocRef.update(updates);
// ...
System.out.println("Update time : " + writeResult.get().getUpdateTime());
ManageDataSnippets.java

Python

# Create an initial document to update
frank_ref = db.collection("users").document("frank")
frank_ref.set(
    {
        "name": "Frank",
        "favorites": {"food": "Pizza", "color": "Blue", "subject": "Recess"},
        "age": 12,
    }
)

# Update age and favorite color
frank_ref.update({"age": 13, "favorites.color": "Red"})
snippets.py

Python
(assíncrono)

# Create an initial document to update
frank_ref = db.collection("users").document("frank")
await frank_ref.set(
    {
        "name": "Frank",
        "favorites": {"food": "Pizza", "color": "Blue", "subject": "Recess"},
        "age": 12,
    }
)

# Update age and favorite color
await frank_ref.update({"age": 13, "favorites.color": "Red"})
snippets.py

C++

// 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")},
});
snippets.cpp

Node.js

const initialData = {
  name: 'Frank',
  age: 12,
  favorites: {
    food: 'Pizza',
    color: 'Blue',
    subject: 'recess'
  }
};

// ...
const res = await db.collection('users').doc('Frank').update({
  age: 13,
  'favorites.color': 'Red'
});
index.js

Go

import (
	"context"
	"log"

	"cloud.google.com/go/firestore"
)

func updateDocNested(ctx context.Context, client *firestore.Client) error {
	initialData := map[string]interface{}{
		"name": "Frank",
		"age":  12,
		"favorites": map[string]interface{}{
			"food":    "Pizza",
			"color":   "Blue",
			"subject": "recess",
		},
	}

	// ...

	_, err := client.Collection("users").Doc("frank").Set(ctx, map[string]interface{}{
		"age": 13,
		"favorites": map[string]interface{}{
			"color": "Red",
		},
	}, firestore.MergeAll)
	if err != nil {
		// Handle any errors in an appropriate way, such as returning them.
		log.Printf("An error has occurred: %s", err)
	}

	return err
}
save_data_set_nested_fields.go

PHP

PHP

Para se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

// Create an initial document to update
$frankRef = $db->collection('samples/php/users')->document('frank');
$frankRef->set([
    'first' => 'Frank',
    'last' => 'Franklin',
    'favorites' => ['food' => 'Pizza', 'color' => 'Blue', 'subject' => 'Recess'],
    'age' => 12
]);

// Update age and favorite color
$frankRef->update([
    ['path' => 'age', 'value' => 13],
    ['path' => 'favorites.color', 'value' => 'Red']
]);

Unity

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.");
});

C#

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);
await frankDocRef.SetAsync(initialData);

// Update age and favorite color
Dictionary<string, object> updates = new Dictionary<string, object>
{
    { "Age", 13 },
    { "Favorites.Color", "Red" },
};

// Asynchronously update the document
await frankDocRef.UpdateAsync(updates);
Program.cs

Ruby

# Create an initial document to update
frank_ref = firestore.doc "#{collection_path}/frank"
frank_ref.set(
  {
    name:      "Frank",
    favorites: {
      food:    "Pizza",
      color:   "Blue",
      subject: "Recess"
    },
    age:       12
  }
)

# Update age and favorite color
frank_ref.update({ age: 13, "favorites.color": "Red" })
add_data.rb

A notação de pontos permite-lhe atualizar um único campo aninhado sem substituir outros campos aninhados. Se atualizar um campo aninhado sem a notação de ponto, vai substituir todo o campo do mapa, conforme mostrado no exemplo seguinte:

Web

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

Atualize elementos numa matriz

Se o seu documento contiver um campo de matriz, pode usar 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 fornecido.

Versão Web 9

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")
});
update_document_array.js

Versão Web 8

Saiba mais acerca da API Web modular com eliminação de código não utilizado e das respetivas vantagens em relação à API com espaço de nomes.

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")
});
test.firestore.js

Swift

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

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"])
])
ViewController.swift

Objective-C

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

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"]]
}];
ViewController.m

Kotlin
Android

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"))
DocSnippets.kt

Java
Android

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"));
DocSnippets.java

Dart

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"]),
});
firestore.dart

Java

DocumentReference washingtonRef = db.collection("cities").document("DC");

// Atomically add a new region to the "regions" array field.
ApiFuture<WriteResult> arrayUnion =
    washingtonRef.update("regions", FieldValue.arrayUnion("greater_virginia"));
System.out.println("Update time : " + arrayUnion.get());

// Atomically remove a region from the "regions" array field.
ApiFuture<WriteResult> arrayRm =
    washingtonRef.update("regions", FieldValue.arrayRemove("east_coast"));
System.out.println("Update time : " + arrayRm.get());
ManageDataSnippets.java

Python

city_ref = db.collection("cities").document("DC")

# Atomically add a new region to the 'regions' array field.
city_ref.update({"regions": firestore.ArrayUnion(["greater_virginia"])})

# // Atomically remove a region from the 'regions' array field.
city_ref.update({"regions": firestore.ArrayRemove(["east_coast"])})
snippets.py

Python
(assíncrono)

city_ref = db.collection("cities").document("DC")

# Atomically add a new region to the 'regions' array field.
await city_ref.update({"regions": firestore.ArrayUnion(["greater_virginia"])})

# // Atomically remove a region from the 'regions' array field.
await city_ref.update({"regions": firestore.ArrayRemove(["east_coast"])})
snippets.py

C++

// This is not yet supported.

Node.js

// ...
const washingtonRef = db.collection('cities').doc('DC');

// Atomically add a new region to the "regions" array field.
const unionRes = await washingtonRef.update({
  regions: FieldValue.arrayUnion('greater_virginia')
});
// Atomically remove a region from the "regions" array field.
const removeRes = await washingtonRef.update({
  regions: FieldValue.arrayRemove('east_coast')
});

// To add or remove multiple items, pass multiple arguments to arrayUnion/arrayRemove
const multipleUnionRes = await washingtonRef.update({
  regions: FieldValue.arrayUnion('south_carolina', 'texas')
  // Alternatively, you can use spread operator in ES6 syntax
  // const newRegions = ['south_carolina', 'texas']
  // regions: FieldValue.arrayUnion(...newRegions)
});
index.js

Go

// Not supported yet

PHP

PHP

Para se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

$cityRef = $db->collection('samples/php/cities')->document('DC');

// Atomically add a new region to the "regions" array field.
$cityRef->update([
    ['path' => 'regions', 'value' => FieldValue::arrayUnion(['greater_virginia'])]
]);

// Atomically remove a region from the "regions" array field.
$cityRef->update([
    ['path' => 'regions', 'value' => FieldValue::arrayRemove(['east_coast'])]
]);

Unity

// This is not yet supported in the Unity SDK
  

C#

DocumentReference washingtonRef = db.Collection("cities").Document("DC");

// Atomically add a new region to the "regions" array field.
await washingtonRef.UpdateAsync("Regions", FieldValue.ArrayUnion("greater_virginia"));

// Atomically remove a region from the "regions" array field.
await washingtonRef.UpdateAsync("Regions", FieldValue.ArrayRemove("east_coast"));
Program.cs

Ruby

// Not supported yet

Aumente um valor numérico

Pode incrementar ou decrementar um valor de campo numérico, conforme mostrado no exemplo seguinte. Uma operação de incremento aumenta ou diminui o valor atual de um campo pelo valor indicado.

Nota: se o campo não existir ou se o valor do campo atual não for um valor numérico, a operação define o campo para o valor indicado.

Versão Web 9

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)
});
update_document_increment.js

Versão Web 8

Saiba mais acerca da API Web modular com eliminação de código não utilizado e das respetivas vantagens em relação à API com espaço de nomes.

var washingtonRef = db.collection('cities').doc('DC');

// Atomically increment the population of the city by 50.
washingtonRef.update({
    population: firebase.firestore.FieldValue.increment(50)
});
test.firestore.js

Swift

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

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))
])
ViewController.swift

Objective-C

Nota: este produto não está disponível em alvos do watchOS e de App Clips.

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]
}];
ViewController.m

Kotlin
Android

val washingtonRef = db.collection("cities").document("DC")

// Atomically increment the population of the city by 50.
washingtonRef.update("population", FieldValue.increment(50))
DocSnippets.kt

Java
Android

DocumentReference washingtonRef = db.collection("cities").document("DC");

// Atomically increment the population of the city by 50.
washingtonRef.update("population", FieldValue.increment(50));
DocSnippets.java

Dart

var washingtonRef = db.collection('cities').doc('DC');

// Atomically increment the population of the city by 50.
washingtonRef.update(
  {"population": FieldValue.increment(50)},
);
firestore.dart

Java

DocumentReference washingtonRef = db.collection("cities").document("DC");

// Atomically increment the population of the city by 50.
final ApiFuture<WriteResult> updateFuture =
    washingtonRef.update("population", FieldValue.increment(50));
ManageDataSnippets.java

Python

washington_ref = db.collection("cities").document("DC")

washington_ref.update({"population": firestore.Increment(50)})
snippets.py

Python
(assíncrono)

washington_ref = db.collection("cities").document("DC")

await washington_ref.update({"population": firestore.Increment(50)})
snippets.py

C++

// This is not yet supported.

Node.js

// ...
const washingtonRef = db.collection('cities').doc('DC');

// Atomically increment the population of the city by 50.
const res = await washingtonRef.update({
  population: FieldValue.increment(50)
});
index.js

Go

import (
	"context"
	"fmt"

	"cloud.google.com/go/firestore"
)

// updateDocumentIncrement increments the population of the city document in the
// cities collection by 50.
func updateDocumentIncrement(projectID, city string) error {
	// projectID := "my-project"

	ctx := context.Background()

	client, err := firestore.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("firestore.NewClient: %w", err)
	}
	defer client.Close()

	dc := client.Collection("cities").Doc(city)
	_, err = dc.Update(ctx, []firestore.Update{
		{Path: "population", Value: firestore.Increment(50)},
	})
	if err != nil {
		return fmt.Errorf("Update: %w", err)
	}

	return nil
}
increment.go

PHP

PHP

Para se autenticar no Firestore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

$cityRef = $db->collection('samples/php/cities')->document('DC');

// Atomically increment the population of the city by 50.
$cityRef->update([
    ['path' => 'regions', 'value' => FieldValue::increment(50)]
]);

Unity

// This is not yet supported in the Unity SDK.
  

C#

DocumentReference washingtonRef = db.Collection("cities").Document("DC");

// Atomically increment the population of the city by 50.
await washingtonRef.UpdateAsync("Regions", FieldValue.Increment(50));
Program.cs

Ruby

city_ref = firestore.doc "#{collection_path}/DC"
city_ref.update({ population: firestore.field_increment(50) })
add_data.rb

As operações de incremento são úteis para implementar contadores. Tenha em atenção que a atualização de um único documento demasiado rapidamente pode originar contestações ou erros. Se precisar de atualizar o contador a uma taxa muito elevada, consulte a página Contadores distribuídos.