Dokumen ini menjelaskan cara menetapkan, menambahkan, atau memperbarui setiap dokumen di Cloud Firestore. Untuk menulis data secara massal, lihat Transaksi dan batch operasi tulis.
Ringkasan
Anda dapat menulis data ke Cloud Firestore dengan salah satu cara berikut:
- Menetapkan data dokumen dalam koleksi, dengan secara eksplisit menentukan ID dokumen.
- Menambahkan dokumen baru ke koleksi. Dalam hal ini, Cloud Firestore akan otomatis menghasilkan ID dokumen.
- Membuat dokumen kosong dengan ID yang otomatis dihasilkan, lalu menetapkan data untuk dokumen tersebut.
Sebelum memulai
Agar dapat melakukan inisialisasi Cloud Firestore untuk menetapkan, menambahkan, atau memperbarui data, Anda harus menyelesaikan langkah-langkah berikut:
- Membuat database Cloud Firestore. Untuk informasi lebih lanjut, lihat Mulai menggunakan Cloud Firestore
- Jika Anda menggunakan library klien web atau seluler, lakukan autentikasi dengan aturan keamanan. Untuk informasi selengkapnya, lihat Mulai menggunakan aturan keamanan.
- Jika Anda menggunakan library klien server atau REST API, lakukan autentikasi dengan Identity and Access Management (IAM). Untuk informasi selengkapnya, lihat Keamanan untuk library klien server.
Melakukan inisialisasi Cloud Firestore
Lakukan inisialisasi instance 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);
Ganti FIREBASE_CONFIGURATION dengan firebaseConfig
aplikasi web Anda.
Untuk mempertahankan data saat perangkat kehilangan koneksi, lihat dokumentasi Mengaktifkan Data Offline.
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();
Ganti FIREBASE_CONFIGURATION dengan firebaseConfig
aplikasi web Anda.
Untuk mempertahankan data saat perangkat kehilangan koneksi, lihat dokumentasi Mengaktifkan Data Offline.
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();
Untuk menggunakan Firebase Admin SDK pada server Anda sendiri, gunakan akun layanan.
Buka IAM & admin > Service accounts di Konsol Google Cloud. Buat kunci pribadi baru dan simpan file JSON-nya. Lalu gunakan file tersebut untuk melakukan inisialisasi 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()
Kredensial default aplikasi yang sudah ada juga dapat digunakan untuk melakukan inisialisasi SDK tersebut.
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()
Untuk menggunakan Firebase Admin SDK pada server Anda sendiri, gunakan akun layanan.
Buka IAM & admin > Service accounts di Konsol Google Cloud. Buat kunci pribadi baru dan simpan file JSON-nya. Lalu gunakan file tersebut untuk melakukan inisialisasi 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()
Kredensial default aplikasi yang sudah ada juga dapat digunakan untuk melakukan inisialisasi SDK tersebut.
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()
Untuk menggunakan Firebase Admin SDK pada server Anda sendiri, gunakan akun layanan.
Buka IAM & admin > Service accounts di Konsol Google Cloud. Buat kunci pribadi baru dan simpan file JSON-nya. Lalu gunakan file tersebut untuk melakukan inisialisasi 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();
-
Melakukan inisialisasi pada Cloud Functions
const { initializeApp, applicationDefault, cert } = require('firebase-admin/app'); const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
initializeApp(); const db = getFirestore();
-
Melakukan inisialisasi pada 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();
-
Melakukan inisialisasi pada server Anda sendiri
Untuk menggunakan Firebase Admin SDK pada server Anda sendiri (atau lingkungan Node.js lainnya), gunakan akun layanan. Buka IAM & admin > Service accounts di Konsol Google Cloud. Buat kunci pribadi baru dan simpan file JSON-nya. Lalu gunakan file tersebut untuk melakukan inisialisasi 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()
Untuk menggunakan Firebase Admin SDK pada server Anda sendiri, gunakan akun layanan.
Buka IAM & admin > Service accounts di Konsol Google Cloud. Buat kunci pribadi baru dan simpan file JSON-nya. Lalu gunakan file tersebut untuk melakukan inisialisasi 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
Untuk mengetahui informasi lebih lanjut tentang cara menginstal dan membuat klien Cloud Firestore, lihat Library Klien Cloud Firestore.
using Firebase.Firestore; using Firebase.Extensions;
FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
C#
Untuk mengetahui informasi lebih lanjut tentang cara menginstal dan membuat klien Cloud Firestore, lihat Library Klien Cloud Firestore.
Menetapkan dokumen
Untuk membuat atau menimpa sebuah dokumen, gunakan metode set()
khusus bahasa berikut:
Gunakan metode 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" });
Gunakan metode 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); });
Gunakan metode 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)") }
Gunakan metode 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!"); } }];
Gunakan metode 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) }
Gunakan metode 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); } });
Gunakan metode 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"));
Gunakan metode set()
:
Gunakan metode set()
:
Gunakan metode set()
:
Gunakan metode 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; } });
Gunakan metode set()
:
Gunakan metode Set()
:
Gunakan metode set()
:
PHP
Untuk mengetahui informasi lebih lanjut tentang cara menginstal dan membuat klien Cloud Firestore, lihat Library Klien Cloud Firestore.
Gunakan metode 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."); });
Gunakan metode SetAsync()
:
Gunakan metode set()
:
Jika belum ada, dokumen itu akan dibuat. Jika dokumen sudah ada, isinya akan ditimpa dengan data yang baru disediakan, kecuali jika Anda menentukan bahwa data tersebut harus digabungkan ke dalam dokumen yang ada, seperti berikut:
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
Untuk mengetahui informasi lebih lanjut tentang cara menginstal dan membuat klien Cloud Firestore, lihat Library Klien Cloud Firestore.
DocumentReference docRef = db.Collection("cities").Document("LA"); Dictionary<string, object> update = new Dictionary<string, object> { { "capital", false } }; docRef.SetAsync(update, SetOptions.MergeAll);
Jika Anda tidak yakin apakah dokumen itu ada, teruskan opsi untuk menggabungkan data baru dengan dokumen yang ada agar tidak menimpa keseluruhan dokumen. Untuk dokumen yang berisi peta, jika Anda menentukan kumpulan dengan kolom yang berisi peta kosong, kolom peta dokumen target akan ditimpa.
Jenis data
Cloud Firestore memungkinkan Anda untuk menulis berbagai jenis data di dalam dokumen, termasuk string, boolean, angka, tanggal, null, dan array serta objek bertingkat. Cloud Firestore selalu menyimpan angka sebagai jenis ganda, terlepas dari jenis angka yang Anda gunakan dalam kode.
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
Untuk mengetahui informasi lebih lanjut tentang cara menginstal dan membuat klien Cloud Firestore, lihat Library Klien 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);
Objek kustom
Penggunaan objek Map
atau Dictionary
untuk mewakili dokumen Anda sering kali
tidak praktis. Oleh karena itu, Cloud Firestore mendukung penulisan dokumen dengan
class kustom. Cloud Firestore mengonversi objek ke jenis data yang didukung.
Dengan class kustom, Anda dapat menulis ulang contoh awal dengan cara berikut:
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, )
Setiap class kustom harus memiliki konstruktor publik yang tidak membutuhkan argumen. Selain itu, class tersebut harus menyertakan pengambil publik untuk setiap properti.
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
Untuk mengetahui informasi lebih lanjut tentang cara menginstal dan membuat klien Cloud Firestore, lihat Library Klien 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.
Menambahkan dokumen
Saat menggunakan set()
untuk membuat dokumen, Anda harus menentukan ID untuk
dokumen yang akan dibuat, seperti contoh berikut:
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
Untuk mengetahui informasi lebih lanjut tentang cara menginstal dan membuat klien Cloud Firestore, lihat Library Klien Cloud Firestore.
db.Collection("cities").Document("new-city-id").SetAsync(city);
Jika tidak ada ID yang berarti untuk dokumen ini, Cloud Firestore dapat
membuat ID secara otomatis untuk Anda. Anda dapat memanggil metode add()
khusus bahasa
berikut:
Gunakan metode 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);
Gunakan metode 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); });
Gunakan metode 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)") }
Gunakan metode 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); } }];
Gunakan metode 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) }
Gunakan metode 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); } });
Gunakan metode 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}"));
Gunakan metode add()
:
Gunakan metode add()
:
Gunakan metode add()
:
Gunakan metode Add()
:
db->Collection("cities").Add({/*some data*/});
Gunakan metode add()
:
Gunakan metode Add()
:
Gunakan metode add()
:
PHP
Untuk mengetahui informasi lebih lanjut tentang cara menginstal dan membuat klien Cloud Firestore, lihat Library Klien Cloud Firestore.
Gunakan metode 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)); });
Gunakan metode AddAsync()
:
Gunakan metode add()
:
Dalam beberapa kasus, sebaiknya buat referensi dokumen dengan
ID yang dibuat otomatis, agar referensi tersebut dapat digunakan di lain waktu. Untuk kasus penggunaan ini, Anda dapat memanggil
doc()
dengan cara berikut:
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
Untuk mengetahui informasi lebih lanjut tentang cara menginstal dan membuat klien Cloud Firestore, lihat Library Klien 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)); });
Di backend, .add(...)
dan .doc().set(...)
setara, sehingga Anda dapat menggunakan
opsi mana pun.
Memperbarui dokumen
Untuk memperbarui beberapa kolom dokumen tanpa menimpa keseluruhan dokumen, gunakan metode update()
khusus bahasa berikut:
Gunakan metode 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 });
Gunakan metode 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); });
Gunakan metode 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)") }
Gunakan metode 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"); } }];
Gunakan metode 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) }
Gunakan metode 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); } });
Gunakan metode 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"));
Gunakan metode update()
:
Gunakan metode update()
:
Gunakan metode update()
:
Gunakan metode Update()
:
DocumentReference washington_ref = db->Collection("cities").Document("DC"); // Set the "capital" field of the city "DC". washington_ref.Update({{"capital", FieldValue::Boolean(true)}});
Gunakan metode update()
:
Gunakan metode Update()
:
Gunakan metode update()
:
PHP
Untuk mengetahui informasi lebih lanjut tentang cara menginstal dan membuat klien Cloud Firestore, lihat Library Klien Cloud Firestore.
Gunakan metode 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);
Gunakan metode UpdateAsync()
:
Gunakan metode update()
:
Stempel Waktu Server
Anda dapat menetapkan kolom dalam dokumen ke stempel waktu server yang melacak kapan server menerima update.
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
Untuk mengetahui informasi lebih lanjut tentang cara menginstal dan membuat klien Cloud Firestore, lihat Library Klien 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."); });
Saat memperbarui beberapa kolom stempel waktu di dalam transaksi, setiap kolom menerima nilai stempel waktu server yang sama.
Memperbarui kolom pada objek bertingkat
Jika dokumen Anda berisi objek bertingkat, Anda dapat menggunakannotasi titik untuk
merujuk ke kolom bertingkat dalam dokumen saat memanggil 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
Untuk mengetahui informasi lebih lanjut tentang cara menginstal dan membuat klien Cloud Firestore, lihat Library Klien 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."); });
Notasi titik memungkinkan Anda memperbarui satu kolom bertingkat tanpa menimpa kolom bertingkat lainnya. Jika Anda memperbarui kolom bertingkat tanpa notasi titik, Anda akan menimpa seluruh kolom peta, seperti ditunjukkan dalam contoh berikut:
// 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 } */
Memperbarui elemen dalam array
Jika dokumen Anda berisi kolom array, Anda bisa menggunakan arrayUnion()
dan arrayRemove()
untuk menambah dan menghapus elemen. arrayUnion()
menambahkan elemen ke array, tetapi hanya elemen yang belum ada. arrayRemove()
menghapus semua
instance dari setiap elemen yang diberikan.
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
Untuk mengetahui informasi lebih lanjut tentang cara menginstal dan membuat klien Cloud Firestore, lihat Library Klien Cloud Firestore.
// This is not yet supported in the Unity SDK
// Not supported yet
Operasi inkremental nilai numerik
Anda bisa menambahkan atau mengurangi nilai kolom numerik secara inkremental seperti yang ditunjukkan pada contoh berikut. Operasi inkremental akan menambahkan atau mengurangi nilai kolom saat ini dengan jumlah tertentu.
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
Untuk mengetahui informasi lebih lanjut tentang cara menginstal dan membuat klien Cloud Firestore, lihat Library Klien Cloud Firestore.
// This is not yet supported in the Unity SDK.
Operasi inkremental berguna untuk mengimplementasikan penghitung. Perlu diperhatikan bahwa memperbarui satu dokumen terlalu cepat dapat menyebabkan pertentangan atau error. Jika Anda perlu memperbarui penghitung dengan kecepatan yang sangat tinggi, lihat halaman Penghitung terdistribusi.