این سند نحوه تنظیم، افزودن یا بهروزرسانی اسناد فردی را در Cloud Firestore توضیح میدهد. برای نوشتن داده ها به صورت انبوه، به تراکنش ها و نوشته های دسته ای مراجعه کنید.
نمای کلی
می توانید داده ها را به یکی از روش های زیر در Cloud Firestore بنویسید:
- داده های یک سند را در یک مجموعه تنظیم کنید و به صراحت یک شناسه سند را مشخص کنید.
- یک سند جدید به مجموعه اضافه کنید. در این حالت، Cloud Firestore به طور خودکار شناسه سند را تولید می کند.
- یک سند خالی با شناسه ای که به طور خودکار تولید می شود ایجاد کنید و بعداً داده ها را به آن اختصاص دهید.
قبل از شروع
قبل از اینکه بتوانید Cloud Firestore برای تنظیم، افزودن یا بهروزرسانی دادهها مقداردهی کنید، باید مراحل زیر را انجام دهید:
- یک پایگاه داده Cloud Firestore ایجاد کنید. برای اطلاعات بیشتر، شروع به کار با Cloud Firestore را ببینید
- اگر از کتابخانه های سرویس گیرنده وب یا تلفن همراه استفاده می کنید، با قوانین امنیتی احراز هویت کنید. برای اطلاعات بیشتر، شروع به کار با قوانین امنیتی را ببینید.
- اگر از کتابخانه های سرویس گیرنده سرور یا REST API استفاده می کنید، با مدیریت هویت و دسترسی (IAM) احراز هویت کنید. برای اطلاعات بیشتر، امنیت برای کتابخانه های سرویس گیرنده سرور را ببینید.
Cloud Firestore را راه اندازی کنید
نمونه ای از 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);
firebaseConfig
برنامه وب خود را جایگزین FIREBASE_CONFIGURATION کنید.
برای تداوم دادهها وقتی دستگاه اتصال خود را قطع میکند، به مستندات Enable 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();
firebaseConfig
برنامه وب خود را جایگزین FIREBASE_CONFIGURATION کنید.
برای تداوم دادهها وقتی دستگاه اتصال خود را قطع میکند، به مستندات Enable 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();
برای استفاده از Firebase Admin SDK در سرور خود، از یک حساب سرویس استفاده کنید.
به IAM & admin > حسابهای سرویس در کنسول Google Cloud بروید. یک کلید خصوصی جدید ایجاد کنید و فایل JSON را ذخیره کنید. سپس از فایل برای مقداردهی اولیه 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()
یک اعتبار پیش فرض برنامه موجود نیز می تواند برای مقداردهی اولیه SDK استفاده شود.
import firebase_admin from firebase_admin import credentials from firebase_admin import firestore # Use the application default credentials. cred = credentials.ApplicationDefault() firebase_admin.initialize_app(cred) db = firestore.client()
برای استفاده از Firebase Admin SDK در سرور خود، از یک حساب سرویس استفاده کنید.
به IAM & admin > حسابهای سرویس در کنسول Google Cloud بروید. یک کلید خصوصی جدید ایجاد کنید و فایل JSON را ذخیره کنید. سپس از فایل برای مقداردهی اولیه 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()
یک اعتبار پیش فرض برنامه موجود نیز می تواند برای مقداردهی اولیه SDK استفاده شود.
import firebase_admin from firebase_admin import credentials from firebase_admin import firestore_async # Use the application default credentials. cred = credentials.ApplicationDefault() firebase_admin.initialize_app(cred) db = firestore_async.client()
برای استفاده از Firebase Admin SDK در سرور خود، از یک حساب سرویس استفاده کنید.
به IAM & admin > حسابهای سرویس در کنسول Google Cloud بروید. یک کلید خصوصی جدید ایجاد کنید و فایل JSON را ذخیره کنید. سپس از فایل برای مقداردهی اولیه 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();
- در Cloud Functions راه اندازی کنید
const { initializeApp, applicationDefault, cert } = require('firebase-admin/app'); const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
initializeApp(); const db = getFirestore();
- در 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();
- بر روی سرور خود راه اندازی کنید
برای استفاده از Firebase Admin SDK در سرور خود (یا هر محیط دیگر Node.js)، از یک حساب سرویس استفاده کنید. به IAM & admin > حسابهای سرویس در کنسول Google Cloud بروید. یک کلید خصوصی جدید ایجاد کنید و فایل JSON را ذخیره کنید. سپس از فایل برای مقداردهی اولیه 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()
برای استفاده از Firebase Admin SDK در سرور خود، از یک حساب سرویس استفاده کنید.
به IAM & admin > حسابهای سرویس در کنسول Google Cloud بروید. یک کلید خصوصی جدید ایجاد کنید و فایل JSON را ذخیره کنید. سپس از فایل برای مقداردهی اولیه 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
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده Cloud Firestore مراجعه کنید.
using Firebase.Firestore; using Firebase.Extensions;
FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
سی شارپ
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده Cloud Firestore مراجعه کنید.
یک سند تنظیم کنید
برای ایجاد یا بازنویسی یک سند واحد، از متدهای set()
مخصوص زبان زیر استفاده کنید:
از متد 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()
استفاده کنید:
// 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); });
از متد 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)") }
از متد 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!"); } }];
از متد 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) }
از متد 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); } });
از متد 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"));
از متد set()
استفاده کنید:
از متد set()
استفاده کنید:
از متد set()
استفاده کنید:
از متد 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; } });
از متد set()
استفاده کنید:
از متد Set()
استفاده کنید:
از متد set()
استفاده کنید:
PHP
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده Cloud Firestore مراجعه کنید.
از متد 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."); });
از متد SetAsync()
استفاده کنید:
از متد set()
استفاده کنید:
اگر سند وجود نداشته باشد، ایجاد می شود. اگر سند وجود داشته باشد، محتویات آن با دادههای ارائهشده جدید رونویسی میشود، مگر اینکه مشخص کنید که دادهها باید در سند موجود ادغام شوند، به شرح زیر:
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
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده Cloud Firestore مراجعه کنید.
DocumentReference docRef = db.Collection("cities").Document("LA"); Dictionary<string, object> update = new Dictionary<string, object> { { "capital", false } }; docRef.SetAsync(update, SetOptions.MergeAll);
اگر مطمئن نیستید که سند وجود دارد یا خیر، گزینه ادغام داده های جدید با هر سند موجود را برای جلوگیری از رونویسی کل اسناد عبور دهید. برای اسنادی که حاوی نقشه هستند، اگر مجموعه ای را با یک فیلد مشخص کنید که حاوی یک نقشه خالی است، فیلد نقشه سند مورد نظر بازنویسی می شود.
انواع داده ها
Cloud Firestore به شما امکان می دهد انواع داده ها را در داخل یک سند بنویسید، از جمله رشته ها، بولی ها، اعداد، تاریخ ها، آرایه ها و اشیاء تهی و تودرتو. Cloud Firestore همیشه اعداد را به صورت دو برابر ذخیره می کند، صرف نظر از اینکه از چه نوع عددی در کد خود استفاده می کنید.
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
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده 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);
اشیاء سفارشی
استفاده از اشیاء Map
یا Dictionary
برای نشان دادن اسناد شما اغلب ناخوشایند است، بنابراین Cloud Firestore از نوشتن اسناد با کلاس های سفارشی پشتیبانی می کند. Cloud Firestore اشیاء را به انواع داده های پشتیبانی شده تبدیل می کند.
با استفاده از کلاس های سفارشی، می توانید مثال اولیه را به روش زیر بازنویسی کنید:
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, )
هر کلاس سفارشی باید یک سازنده عمومی داشته باشد که هیچ آرگومانی دریافت نکند. علاوه بر این، کلاس باید شامل یک گیرنده عمومی برای هر ویژگی باشد.
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
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده 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.
یک سند اضافه کنید
هنگامی که از set()
برای ایجاد یک سند استفاده می کنید، باید یک شناسه برای ایجاد سند مشخص کنید، همانطور که در مثال زیر نشان داده شده است:
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
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده Cloud Firestore مراجعه کنید.
db.Collection("cities").Document("new-city-id").SetAsync(city);
اگر شناسه معنیداری برای سند وجود نداشته باشد، Cloud Firestore میتواند بهطور خودکار یک شناسه برای شما ایجاد کند. می توانید متدهای add()
مخصوص زبان زیر را فراخوانی کنید:
از متد 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()
استفاده کنید:
// 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); });
از متد 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)") }
از متد 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); } }];
از متد 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) }
از متد 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); } });
از متد 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}"));
از متد add()
استفاده کنید:
از متد add()
استفاده کنید:
از متد add()
استفاده کنید:
از متد Add()
استفاده کنید:
db->Collection("cities").Add({/*some data*/});
از متد add()
استفاده کنید:
از متد Add()
استفاده کنید:
از متد add()
استفاده کنید:
PHP
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده Cloud Firestore مراجعه کنید.
از متد 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)); });
از متد AddAsync()
استفاده کنید:
از متد add()
استفاده کنید:
در برخی موارد، ایجاد یک مرجع سند با شناسه ای که به طور خودکار تولید می شود، می تواند مفید باشد، سپس بعداً از مرجع استفاده کنید. برای این مورد استفاده، می توانید doc()
را به روش زیر فراخوانی کنید:
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
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده 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)); });
در backend، .add(...)
و .doc().set(...)
معادل هستند، بنابراین می توانید از هر یک از گزینه ها استفاده کنید.
یک سند را به روز کنید
برای به روز رسانی برخی از فیلدهای یک سند بدون بازنویسی کل سند، از متدهای update()
مخصوص زبان زیر استفاده کنید:
از متد 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()
استفاده کنید:
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); });
از متد 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)") }
از متد 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"); } }];
از متد 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) }
از متد 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); } });
از متد 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"));
از متد update()
استفاده کنید:
از متد update()
استفاده کنید:
از متد update()
استفاده کنید:
از متد Update()
استفاده کنید:
DocumentReference washington_ref = db->Collection("cities").Document("DC"); // Set the "capital" field of the city "DC". washington_ref.Update({{"capital", FieldValue::Boolean(true)}});
از متد update()
استفاده کنید:
از متد Update()
استفاده کنید:
از متد update()
استفاده کنید:
PHP
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده Cloud Firestore مراجعه کنید.
از متد 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);
از متد UpdateAsync()
استفاده کنید:
از متد 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
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده 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."); });
هنگام به روز رسانی چندین فیلد مُهر زمان در داخل یک تراکنش ، هر فیلد همان مقدار مهر زمانی سرور را دریافت می کند.
فیلدها را در اشیاء تودرتو به روز کنید
اگر سند شما حاوی اشیاء تودرتو است، میتوانید هنگام فراخوانی 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
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده 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."); });
نماد نقطه به شما امکان می دهد یک فیلد تودرتو را بدون بازنویسی سایر فیلدهای تودرتو به روز کنید. اگر یک فیلد تودرتو را بدون علامت نقطه به روز کنید، کل فیلد نقشه را بازنویسی می کنید، همانطور که در مثال زیر نشان داده شده است:
// 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 } */
به روز رسانی عناصر در یک آرایه
اگر سند شما حاوی یک فیلد آرایه است، می توانید از arrayUnion()
و arrayRemove()
برای افزودن و حذف عناصر استفاده کنید. arrayUnion()
عناصری را به یک آرایه اضافه می کند اما فقط عناصری را که قبلاً وجود ندارند اضافه می کند. arrayRemove()
تمام نمونه های هر عنصر داده شده را حذف می کند.
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
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده Cloud Firestore مراجعه کنید.
// This is not yet supported in the Unity SDK
// Not supported yet
یک مقدار عددی را افزایش دهید
همانطور که در مثال زیر نشان داده شده است، می توانید مقدار فیلد عددی را افزایش یا کاهش دهید. یک عملیات افزایشی، مقدار فعلی یک فیلد را به مقدار معین افزایش یا کاهش می دهد.
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
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده Cloud Firestore مراجعه کنید.
// This is not yet supported in the Unity SDK.
عملیات افزایشی برای پیاده سازی شمارنده ها مفید است. توجه داشته باشید که بهروزرسانی سریع یک سند میتواند منجر به مشاجره یا خطا شود . اگر می خواهید پیشخوان خود را با سرعت بسیار بالا به روز کنید، به صفحه شمارنده های توزیع شده مراجعه کنید.
،این سند نحوه تنظیم، افزودن یا بهروزرسانی اسناد فردی را در Cloud Firestore توضیح میدهد. برای نوشتن داده ها به صورت انبوه، به تراکنش ها و نوشته های دسته ای مراجعه کنید.
نمای کلی
می توانید داده ها را به یکی از روش های زیر در Cloud Firestore بنویسید:
- داده های یک سند را در یک مجموعه تنظیم کنید و به صراحت یک شناسه سند را مشخص کنید.
- یک سند جدید به مجموعه اضافه کنید. در این حالت، Cloud Firestore به طور خودکار شناسه سند را تولید می کند.
- یک سند خالی با شناسه ای که به طور خودکار تولید می شود ایجاد کنید و بعداً داده ها را به آن اختصاص دهید.
قبل از شروع
قبل از اینکه بتوانید Cloud Firestore برای تنظیم، افزودن یا بهروزرسانی دادهها مقداردهی کنید، باید مراحل زیر را انجام دهید:
- یک پایگاه داده Cloud Firestore ایجاد کنید. برای اطلاعات بیشتر، شروع به کار با Cloud Firestore را ببینید
- اگر از کتابخانه های سرویس گیرنده وب یا تلفن همراه استفاده می کنید، با قوانین امنیتی احراز هویت کنید. برای اطلاعات بیشتر، شروع به کار با قوانین امنیتی را ببینید.
- اگر از کتابخانه های سرویس گیرنده سرور یا REST API استفاده می کنید، با مدیریت هویت و دسترسی (IAM) احراز هویت کنید. برای اطلاعات بیشتر، امنیت برای کتابخانه های سرویس گیرنده سرور را ببینید.
Cloud Firestore را راه اندازی کنید
نمونه ای از 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);
firebaseConfig
برنامه وب خود را جایگزین FIREBASE_CONFIGURATION کنید.
برای تداوم دادهها وقتی دستگاه اتصال خود را قطع میکند، به مستندات Enable 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();
firebaseConfig
برنامه وب خود را جایگزین FIREBASE_CONFIGURATION کنید.
برای تداوم دادهها وقتی دستگاه اتصال خود را قطع میکند، به مستندات Enable 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();
برای استفاده از Firebase Admin SDK در سرور خود، از یک حساب سرویس استفاده کنید.
به IAM & admin > حسابهای سرویس در کنسول Google Cloud بروید. یک کلید خصوصی جدید ایجاد کنید و فایل JSON را ذخیره کنید. سپس از فایل برای مقداردهی اولیه 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()
یک اعتبار پیش فرض برنامه موجود نیز می تواند برای مقداردهی اولیه SDK استفاده شود.
import firebase_admin from firebase_admin import credentials from firebase_admin import firestore # Use the application default credentials. cred = credentials.ApplicationDefault() firebase_admin.initialize_app(cred) db = firestore.client()
برای استفاده از Firebase Admin SDK در سرور خود، از یک حساب سرویس استفاده کنید.
به IAM & admin > حسابهای سرویس در کنسول Google Cloud بروید. یک کلید خصوصی جدید ایجاد کنید و فایل JSON را ذخیره کنید. سپس از فایل برای مقداردهی اولیه 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()
یک اعتبار پیش فرض برنامه موجود نیز می تواند برای مقداردهی اولیه SDK استفاده شود.
import firebase_admin from firebase_admin import credentials from firebase_admin import firestore_async # Use the application default credentials. cred = credentials.ApplicationDefault() firebase_admin.initialize_app(cred) db = firestore_async.client()
برای استفاده از Firebase Admin SDK در سرور خود، از یک حساب سرویس استفاده کنید.
به IAM & admin > حسابهای سرویس در کنسول Google Cloud بروید. یک کلید خصوصی جدید ایجاد کنید و فایل JSON را ذخیره کنید. سپس از فایل برای مقداردهی اولیه 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();
- در Cloud Functions راه اندازی کنید
const { initializeApp, applicationDefault, cert } = require('firebase-admin/app'); const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
initializeApp(); const db = getFirestore();
- در 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();
- بر روی سرور خود راه اندازی کنید
برای استفاده از Firebase Admin SDK در سرور خود (یا هر محیط دیگر Node.js)، از یک حساب سرویس استفاده کنید. به IAM & admin > حسابهای سرویس در کنسول Google Cloud بروید. یک کلید خصوصی جدید ایجاد کنید و فایل JSON را ذخیره کنید. سپس از فایل برای مقداردهی اولیه 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()
برای استفاده از Firebase Admin SDK در سرور خود، از یک حساب سرویس استفاده کنید.
به IAM & admin > حسابهای سرویس در کنسول Google Cloud بروید. یک کلید خصوصی جدید ایجاد کنید و فایل JSON را ذخیره کنید. سپس از فایل برای مقداردهی اولیه 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
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده Cloud Firestore مراجعه کنید.
using Firebase.Firestore; using Firebase.Extensions;
FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
سی شارپ
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده Cloud Firestore مراجعه کنید.
یک سند تنظیم کنید
برای ایجاد یا بازنویسی یک سند واحد، از متدهای set()
مخصوص زبان زیر استفاده کنید:
از متد 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()
استفاده کنید:
// 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); });
از متد 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)") }
از متد 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!"); } }];
از متد 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) }
از متد 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); } });
از متد 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"));
از متد set()
استفاده کنید:
از متد set()
استفاده کنید:
از متد set()
استفاده کنید:
از متد 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; } });
از متد set()
استفاده کنید:
از متد Set()
استفاده کنید:
از متد set()
استفاده کنید:
PHP
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده Cloud Firestore مراجعه کنید.
از متد 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."); });
از متد SetAsync()
استفاده کنید:
از متد set()
استفاده کنید:
اگر سند وجود نداشته باشد، ایجاد می شود. اگر سند وجود داشته باشد، محتویات آن با دادههای ارائهشده جدید رونویسی میشود، مگر اینکه مشخص کنید که دادهها باید در سند موجود ادغام شوند، به شرح زیر:
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
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده Cloud Firestore مراجعه کنید.
DocumentReference docRef = db.Collection("cities").Document("LA"); Dictionary<string, object> update = new Dictionary<string, object> { { "capital", false } }; docRef.SetAsync(update, SetOptions.MergeAll);
اگر مطمئن نیستید که سند وجود دارد یا خیر، گزینه ادغام داده های جدید با هر سند موجود را برای جلوگیری از رونویسی کل اسناد عبور دهید. برای اسنادی که حاوی نقشه هستند، اگر مجموعه ای را با یک فیلد مشخص کنید که حاوی یک نقشه خالی است، فیلد نقشه سند مورد نظر بازنویسی می شود.
انواع داده ها
Cloud Firestore به شما امکان می دهد انواع داده ها را در داخل یک سند بنویسید، از جمله رشته ها، بولی ها، اعداد، تاریخ ها، آرایه ها و اشیاء تهی و تودرتو. Cloud Firestore همیشه اعداد را به صورت دو برابر ذخیره می کند، صرف نظر از اینکه از چه نوع عددی در کد خود استفاده می کنید.
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
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده 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);
اشیاء سفارشی
استفاده از اشیاء Map
یا Dictionary
برای نشان دادن اسناد شما اغلب ناخوشایند است، بنابراین Cloud Firestore از نوشتن اسناد با کلاس های سفارشی پشتیبانی می کند. Cloud Firestore اشیاء را به انواع داده های پشتیبانی شده تبدیل می کند.
با استفاده از کلاس های سفارشی، می توانید مثال اولیه را به روش زیر بازنویسی کنید:
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, )
هر کلاس سفارشی باید یک سازنده عمومی داشته باشد که هیچ آرگومانی دریافت نکند. علاوه بر این، کلاس باید شامل یک گیرنده عمومی برای هر ویژگی باشد.
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
برای اطلاعات بیشتر در مورد نصب و ایجاد کلاینت Cloud Firestore ، به کتابخانه های سرویس گیرنده 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.
یک سند اضافه کنید
هنگامی که از set()
برای ایجاد یک سند استفاده می کنید ، باید یک شناسه را برای ایجاد سند مشخص کنید ، همانطور که در مثال زیر نشان داده شده است:
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
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری Cloud Firestore مراجعه کنید.
db.Collection("cities").Document("new-city-id").SetAsync(city);
اگر یک شناسه معنی دار برای سند وجود نداشته باشد ، Cloud Firestore می تواند یک شناسه را برای شما ایجاد کند. می توانید روشهای add()
زبان زیر را فراخوانی کنید:
از روش 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()
استفاده کنید:
// 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); });
از روش 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)") }
از 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); } }];
از روش 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) }
از روش 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); } });
از روش 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}"));
از روش add()
استفاده کنید:
از روش add()
استفاده کنید:
از روش add()
استفاده کنید:
از روش Add()
استفاده کنید:
db->Collection("cities").Add({/*some data*/});
از روش add()
استفاده کنید:
از روش Add()
استفاده کنید:
از روش add()
استفاده کنید:
PHP
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری Cloud Firestore مراجعه کنید.
از روش 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)); });
از روش AddAsync()
استفاده کنید:
از روش add()
استفاده کنید:
در بعضی موارد ، ایجاد یک مرجع سند با یک شناسه تولید شده به صورت خودکار می تواند مفید باشد ، سپس بعداً از مرجع استفاده کنید. برای این مورد استفاده ، می توانید به روش زیر با doc()
تماس بگیرید:
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
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری 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)); });
در باطن ، .add(...)
و .doc().set(...)
معادل هستند ، بنابراین می توانید از هر گزینه استفاده کنید.
یک سند را به روز کنید
برای به روزرسانی برخی از زمینه های یک سند بدون نوشتن کل سند ، از روش های update()
استفاده کنید:
از روش 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()
استفاده کنید:
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); });
از روش 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)") }
از روش 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"); } }];
از روش 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) }
از روش 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); } });
از روش 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"));
از روش update()
استفاده کنید:
از روش update()
استفاده کنید:
از روش update()
استفاده کنید:
از روش Update()
استفاده کنید:
DocumentReference washington_ref = db->Collection("cities").Document("DC"); // Set the "capital" field of the city "DC". washington_ref.Update({{"capital", FieldValue::Boolean(true)}});
از روش update()
استفاده کنید:
از روش Update()
استفاده کنید:
از روش update()
استفاده کنید:
PHP
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری Cloud Firestore مراجعه کنید.
از روش 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);
از روش UpdateAsync()
استفاده کنید:
از روش update()
استفاده کنید:
مهر زمان سرور
می توانید یک فیلد را در سند خود در یک Timestamp سرور تنظیم کنید که هنگام دریافت سرور به روزرسانی را ردیابی می کند.
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
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری 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."); });
هنگام به روزرسانی چندین قسمت Timestamp در داخل یک معامله ، هر فیلد همان مقدار Timestamp سرور را دریافت می کند.
زمینه ها را در اشیاء تو در تو به روز کنید
اگر سند شما حاوی اشیاء تو در تو است ، می توانید هنگام تماس با update()
از Notation DOT برای استفاده از قسمت های مرجع در داخل سند استفاده کنید:
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
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری 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."); });
Dot Notation به شما امکان می دهد بدون نوشتن سایر زمینه های تو در تو ، یک زمینه تو در تو را به روز کنید. اگر یک قسمت تو در تو را بدون نماد نقطه به روز کنید ، همانطور که در مثال زیر نشان داده شده است ، کل قسمت نقشه را بازنویسی خواهید کرد:
// 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 } */
عناصر را در یک آرایه به روز کنید
اگر سند شما حاوی یک قسمت آرایه است ، می توانید از arrayUnion()
و arrayRemove()
برای اضافه کردن و حذف عناصر استفاده کنید. arrayUnion()
عناصر را به یک آرایه اضافه می کند اما فقط عناصری که از قبل موجود نیستند. arrayRemove()
تمام نمونه های هر عنصر معین را حذف می کند.
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
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری Cloud Firestore مراجعه کنید.
// This is not yet supported in the Unity SDK
// Not supported yet
مقدار عددی را افزایش دهید
همانطور که در مثال زیر نشان داده شده است می توانید مقدار میدان عددی را افزایش یا کاهش دهید. یک عمل افزایش مقدار فعلی یک میدان را با مقدار مشخص افزایش یا کاهش می دهد.
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
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری Cloud Firestore مراجعه کنید.
// This is not yet supported in the Unity SDK.
عملیات افزایش برای اجرای پیشخوان ها مفید است. توجه داشته باشید که به روزرسانی یک سند خیلی سریع می تواند منجر به مشاجره یا خطاها شود . اگر نیاز دارید پیشخوان خود را با نرخ بسیار بالا به روز کنید ، به صفحه پیشخوان های توزیع شده مراجعه کنید.
،این سند نحوه تنظیم ، افزودن یا به روزرسانی اسناد جداگانه در Cloud Firestore را توضیح می دهد. برای نوشتن داده ها به صورت عمده ، به معاملات و نوشتن های Batched مراجعه کنید.
نمای کلی
شما می توانید به یکی از روشهای زیر داده ها را به Cloud Firestore بنویسید:
- داده های یک سند را در یک مجموعه تنظیم کنید ، و صریحاً یک شناسه سند را مشخص کنید.
- یک سند جدید به یک مجموعه اضافه کنید. در این حالت ، Cloud Firestore به طور خودکار شناسه سند را تولید می کند.
- یک سند خالی با یک شناسه به طور خودکار ایجاد کنید و بعداً داده ها را به آن اختصاص دهید.
قبل از شروع
قبل از اینکه بتوانید Cloud Firestore برای تنظیم ، افزودن یا به روزرسانی داده ها آغاز کنید ، باید مراحل زیر را انجام دهید:
- یک پایگاه داده Cloud Firestore ایجاد کنید. برای اطلاعات بیشتر ، به شروع کار با Cloud Firestore مراجعه کنید
- اگر از کتابخانه های وب یا مشتری تلفن همراه استفاده می کنید ، با قوانین امنیتی تأیید کنید. برای اطلاعات بیشتر ، به شروع با قوانین امنیتی مراجعه کنید.
- اگر از کتابخانه های مشتری سرور یا API REST استفاده می کنید ، با هویت و مدیریت دسترسی (IAM) تأیید کنید. برای اطلاعات بیشتر ، به امنیت برای کتابخانه های مشتری سرور مراجعه کنید.
Cloud Firestore را اولیه کنید
نمونه ای از 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);
FIREBASE_CONFIGURATION با firebaseConfig
برنامه وب خود جایگزین کنید.
برای ادامه داده ها وقتی دستگاه اتصال خود را از دست می دهد ، مستندات داده های آفلاین را مشاهده کنید.
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();
FIREBASE_CONFIGURATION با firebaseConfig
برنامه وب خود جایگزین کنید.
برای ادامه داده ها وقتی دستگاه اتصال خود را از دست می دهد ، مستندات داده های آفلاین را مشاهده کنید.
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();
برای استفاده از Firebase Admin SDK در سرور خود ، از یک حساب خدمات استفاده کنید.
در کنسول Google Cloud به IAM & Admin> Service Accounts بروید. یک کلید خصوصی جدید ایجاد کنید و پرونده JSON را ذخیره کنید. سپس از پرونده برای اولیه سازی 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()
یک اعتبار پیش فرض برنامه موجود نیز می تواند برای اولیه سازی SDK استفاده شود.
import firebase_admin from firebase_admin import credentials from firebase_admin import firestore # Use the application default credentials. cred = credentials.ApplicationDefault() firebase_admin.initialize_app(cred) db = firestore.client()
برای استفاده از Firebase Admin SDK در سرور خود ، از یک حساب خدمات استفاده کنید.
در کنسول Google Cloud به IAM & Admin> Service Accounts بروید. یک کلید خصوصی جدید ایجاد کنید و پرونده JSON را ذخیره کنید. سپس از پرونده برای اولیه سازی 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()
یک اعتبار پیش فرض برنامه موجود نیز می تواند برای اولیه سازی SDK استفاده شود.
import firebase_admin from firebase_admin import credentials from firebase_admin import firestore_async # Use the application default credentials. cred = credentials.ApplicationDefault() firebase_admin.initialize_app(cred) db = firestore_async.client()
برای استفاده از Firebase Admin SDK در سرور خود ، از یک حساب خدمات استفاده کنید.
در کنسول Google Cloud به IAM & Admin> Service Accounts بروید. یک کلید خصوصی جدید ایجاد کنید و پرونده JSON را ذخیره کنید. سپس از پرونده برای اولیه سازی 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();
- اولیه را بر روی Cloud Functions آغاز کنید
const { initializeApp, applicationDefault, cert } = require('firebase-admin/app'); const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
initializeApp(); const db = getFirestore();
- اولیه سازی در 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();
- اولیه را روی سرور خود خود قرار دهید
برای استفاده از Firebase Admin SDK در سرور خود (یا هر محیط Node.js دیگر) ، از یک حساب سرویس استفاده کنید. در کنسول Google Cloud به IAM & Admin> Service Accounts بروید. یک کلید خصوصی جدید ایجاد کنید و پرونده JSON را ذخیره کنید. سپس از پرونده برای اولیه سازی 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()
برای استفاده از Firebase Admin SDK در سرور خود ، از یک حساب خدمات استفاده کنید.
در کنسول Google Cloud به IAM & Admin> Service Accounts بروید. یک کلید خصوصی جدید ایجاد کنید و پرونده JSON را ذخیره کنید. سپس از پرونده برای اولیه سازی 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
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری Cloud Firestore مراجعه کنید.
using Firebase.Firestore; using Firebase.Extensions;
FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
سی شارپ
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری Cloud Firestore مراجعه کنید.
یک سند را تنظیم کنید
برای ایجاد یا رونویسی یک سند واحد ، از روشهای set()
خاص زبان استفاده کنید:
از روش 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()
استفاده کنید:
// 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); });
از روش 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)") }
از 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!"); } }];
از روش 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) }
از روش 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); } });
از روش 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"));
از روش set()
استفاده کنید:
از روش set()
استفاده کنید:
از روش set()
استفاده کنید:
از روش 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; } });
از روش set()
استفاده کنید:
از روش Set()
استفاده کنید:
از روش set()
استفاده کنید:
PHP
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری Cloud Firestore مراجعه کنید.
از روش 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."); });
از روش SetAsync()
استفاده کنید:
از روش set()
استفاده کنید:
اگر سند وجود نداشته باشد ، ایجاد می شود. اگر این سند وجود داشته باشد ، محتوای آن با داده های تازه ارائه شده رونویسی می شود ، مگر اینکه مشخص کنید که داده ها باید در سند موجود ادغام شوند ، به شرح زیر:
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
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری Cloud Firestore مراجعه کنید.
DocumentReference docRef = db.Collection("cities").Document("LA"); Dictionary<string, object> update = new Dictionary<string, object> { { "capital", false } }; docRef.SetAsync(update, SetOptions.MergeAll);
اگر مطمئن نیستید که آیا این سند وجود دارد ، گزینه ادغام داده های جدید را با هر سند موجود برای جلوگیری از رونویسی کل اسناد منتقل کنید. برای اسنادی که حاوی نقشه ها هستند ، اگر مجموعه ای را با فیلدی که شامل نقشه خالی است مشخص کنید ، قسمت نقشه سند هدف رونویسی می شود.
انواع داده ها
Cloud Firestore به شما امکان می دهد انواع مختلفی از داده ها را در داخل یک سند بنویسید ، از جمله رشته ها ، بول ها ، شماره ها ، تاریخ ها ، آرایه ها و اشیاء توخالی. Cloud Firestore همیشه بدون توجه به نوع شماره ای که در کد خود استفاده می کنید ، اعداد را به عنوان دو برابر ذخیره می کند.
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
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری 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);
اشیاء سفارشی
استفاده از Map
یا اشیاء Dictionary
برای نشان دادن اسناد شما اغلب ناخوشایند است ، بنابراین Cloud Firestore از نوشتن اسناد با کلاس های سفارشی پشتیبانی می کند. Cloud Firestore اشیاء را به انواع داده های پشتیبانی شده تبدیل می کند.
با استفاده از کلاسهای سفارشی ، می توانید مثال اولیه را به روش زیر بازنویسی کنید:
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, )
هر کلاس سفارشی باید یک سازنده عمومی داشته باشد که هیچ استدلالی در نظر نمی گیرد. علاوه بر این ، کلاس باید برای هر ملک یک گیرنده عمومی را در بر بگیرد.
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
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری 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.
یک سند اضافه کنید
هنگامی که از set()
برای ایجاد یک سند استفاده می کنید ، باید یک شناسه را برای ایجاد سند مشخص کنید ، همانطور که در مثال زیر نشان داده شده است:
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
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری Cloud Firestore مراجعه کنید.
db.Collection("cities").Document("new-city-id").SetAsync(city);
اگر یک شناسه معنی دار برای سند وجود نداشته باشد ، Cloud Firestore می تواند یک شناسه را برای شما ایجاد کند. می توانید روشهای add()
زبان زیر را فراخوانی کنید:
از روش 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()
استفاده کنید:
// 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); });
از روش 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)") }
از 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); } }];
از روش 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) }
از روش 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); } });
از روش 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}"));
از روش add()
استفاده کنید:
از روش add()
استفاده کنید:
از روش add()
استفاده کنید:
از روش Add()
استفاده کنید:
db->Collection("cities").Add({/*some data*/});
از روش add()
استفاده کنید:
از روش Add()
استفاده کنید:
از روش add()
استفاده کنید:
PHP
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری Cloud Firestore مراجعه کنید.
از روش 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)); });
از روش AddAsync()
استفاده کنید:
از روش add()
استفاده کنید:
در بعضی موارد ، ایجاد یک مرجع سند با یک شناسه تولید شده به صورت خودکار می تواند مفید باشد ، سپس بعداً از مرجع استفاده کنید. برای این مورد استفاده ، می توانید به روش زیر با doc()
تماس بگیرید:
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
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری 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)); });
در باطن ، .add(...)
و .doc().set(...)
معادل هستند ، بنابراین می توانید از هر گزینه استفاده کنید.
یک سند را به روز کنید
برای به روزرسانی برخی از زمینه های یک سند بدون نوشتن کل سند ، از روش های update()
استفاده کنید:
از روش 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()
استفاده کنید:
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); });
از روش 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)") }
از روش 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"); } }];
از روش 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) }
از روش 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); } });
از روش 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"));
از روش update()
استفاده کنید:
از روش update()
استفاده کنید:
از روش update()
استفاده کنید:
از روش Update()
استفاده کنید:
DocumentReference washington_ref = db->Collection("cities").Document("DC"); // Set the "capital" field of the city "DC". washington_ref.Update({{"capital", FieldValue::Boolean(true)}});
از روش update()
استفاده کنید:
از روش Update()
استفاده کنید:
از روش update()
استفاده کنید:
PHP
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری Cloud Firestore مراجعه کنید.
از روش 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);
از روش UpdateAsync()
استفاده کنید:
از روش update()
استفاده کنید:
مهر زمان سرور
می توانید یک فیلد را در سند خود در یک Timestamp سرور تنظیم کنید که هنگام دریافت سرور به روزرسانی را ردیابی می کند.
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
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری 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."); });
هنگام به روزرسانی چندین قسمت Timestamp در داخل یک معامله ، هر فیلد همان مقدار Timestamp سرور را دریافت می کند.
زمینه ها را در اشیاء تو در تو به روز کنید
اگر سند شما حاوی اشیاء تو در تو است ، می توانید هنگام تماس با update()
از Notation DOT برای استفاده از قسمت های مرجع در داخل سند استفاده کنید:
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
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری 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."); });
Dot Notation به شما امکان می دهد بدون نوشتن سایر زمینه های تو در تو ، یک زمینه تو در تو را به روز کنید. اگر یک قسمت تو در تو را بدون نماد نقطه به روز کنید ، همانطور که در مثال زیر نشان داده شده است ، کل قسمت نقشه را بازنویسی خواهید کرد:
// 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 } */
عناصر را در یک آرایه به روز کنید
اگر سند شما حاوی یک قسمت آرایه است ، می توانید از arrayUnion()
و arrayRemove()
برای اضافه کردن و حذف عناصر استفاده کنید. arrayUnion()
عناصر را به یک آرایه اضافه می کند اما فقط عناصری که از قبل موجود نیستند. arrayRemove()
تمام نمونه های هر عنصر معین را حذف می کند.
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
برای اطلاعات بیشتر در مورد نصب و ایجاد مشتری Cloud Firestore ، به کتابخانه های مشتری Cloud Firestore مراجعه کنید.
// This is not yet supported in the Unity SDK
// Not supported yet
مقدار عددی را افزایش دهید
همانطور که در مثال زیر نشان داده شده است می توانید مقدار میدان عددی را افزایش یا کاهش دهید. یک عمل افزایش مقدار فعلی یک میدان را با مقدار مشخص افزایش یا کاهش می دهد.
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
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries .
// This is not yet supported in the Unity SDK.
Increment operations are useful for implementing counters. Note that updating a single document too quickly can lead to contention or errors . If you need to update your counter at a very high rate, see the Distributed counters page.
،This document explains how to set, add, or update individual documents in Cloud Firestore . To write data in bulk, see Transactions and batched writes .
نمای کلی
You can write data to Cloud Firestore in one of the following ways:
- Set the data of a document within a collection, explicitly specifying a document identifier.
- Add a new document to a collection. In this case, Cloud Firestore automatically generates the document identifier.
- Create an empty document with an automatically generated identifier, and assign data to it later.
قبل از شروع
Before you can initialize Cloud Firestore to set, add, or update data, you must complete the following steps:
- Create a Cloud Firestore database. For more information, see Get started with Cloud Firestore
- If you use the web or mobile client libraries, authenticate with security rules. For more information, see Getting started with security rules .
- If you use the server client libraries or REST API, authenticate with Identity and Access Management (IAM). For more information, see Security for server client libraries .
Initialize Cloud Firestore
Initialize an instance of 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);
Replace FIREBASE_CONFIGURATION with your web app's firebaseConfig
.
To persist data when the device loses its connection, see the Enable Offline Data documentation.
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();
Replace FIREBASE_CONFIGURATION with your web app's firebaseConfig
.
To persist data when the device loses its connection, see the Enable Offline Data documentation.
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();
To use the Firebase Admin SDK on your own server, use a service account .
Go to IAM & admin > Service accounts in the Google Cloud console. Generate a new private key and save the JSON file. Then use the file to initialize the 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()
An existing application default credential can also be used to initialize the SDK.
import firebase_admin from firebase_admin import credentials from firebase_admin import firestore # Use the application default credentials. cred = credentials.ApplicationDefault() firebase_admin.initialize_app(cred) db = firestore.client()
To use the Firebase Admin SDK on your own server, use a service account .
Go to IAM & admin > Service accounts in the Google Cloud console. Generate a new private key and save the JSON file. Then use the file to initialize the 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()
An existing application default credential can also be used to initialize the SDK.
import firebase_admin from firebase_admin import credentials from firebase_admin import firestore_async # Use the application default credentials. cred = credentials.ApplicationDefault() firebase_admin.initialize_app(cred) db = firestore_async.client()
To use the Firebase Admin SDK on your own server, use a service account .
Go to IAM & admin > Service accounts in the Google Cloud console. Generate a new private key and save the JSON file. Then use the file to initialize the 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();
- Initialize on Cloud Functions
const { initializeApp, applicationDefault, cert } = require('firebase-admin/app'); const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
initializeApp(); const db = getFirestore();
- Initialize on 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();
- Initialize on your own server
To use the Firebase Admin SDK on your own server (or any other Node.js environment), use a service account . Go to IAM & admin > Service accounts in the Google Cloud console. Generate a new private key and save the JSON file. Then use the file to initialize the 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()
To use the Firebase Admin SDK on your own server, use a service account .
Go to IAM & admin > Service accounts in the Google Cloud console. Generate a new private key and save the JSON file. Then use the file to initialize the 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
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries .
using Firebase.Firestore; using Firebase.Extensions;
FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
سی شارپ
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries .
Set a document
To create or overwrite a single document, use the following language-specific set()
methods:
Use the setDoc()
method:
import { doc, setDoc } from "firebase/firestore"; // Add a new document in collection "cities" await setDoc(doc(db, "cities", "LA"), { name: "Los Angeles", state: "CA", country: "USA" });
Use the set()
method:
// Add a new document in collection "cities" db.collection("cities").doc("LA").set({ name: "Los Angeles", state: "CA", country: "USA" }) .then(() => { console.log("Document successfully written!"); }) .catch((error) => { console.error("Error writing document: ", error); });
Use the setData()
method:
// Add a new document in collection "cities" do { try await db.collection("cities").document("LA").setData([ "name": "Los Angeles", "state": "CA", "country": "USA" ]) print("Document successfully written!") } catch { print("Error writing document: \(error)") }
Use the setData:
method:
// Add a new document in collection "cities" [[[self.db collectionWithPath:@"cities"] documentWithPath:@"LA"] setData:@{ @"name": @"Los Angeles", @"state": @"CA", @"country": @"USA" } completion:^(NSError * _Nullable error) { if (error != nil) { NSLog(@"Error writing document: %@", error); } else { NSLog(@"Document successfully written!"); } }];
Use the set()
method:
val city = hashMapOf( "name" to "Los Angeles", "state" to "CA", "country" to "USA", ) db.collection("cities").document("LA") .set(city) .addOnSuccessListener { Log.d(TAG, "DocumentSnapshot successfully written!") } .addOnFailureListener { e -> Log.w(TAG, "Error writing document", e) }
Use the set()
method:
Map<String, Object> city = new HashMap<>(); city.put("name", "Los Angeles"); city.put("state", "CA"); city.put("country", "USA"); db.collection("cities").document("LA") .set(city) .addOnSuccessListener(new OnSuccessListener<Void>() { @Override public void onSuccess(Void aVoid) { Log.d(TAG, "DocumentSnapshot successfully written!"); } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { Log.w(TAG, "Error writing document", e); } });
Use the set()
method:
final city = <String, String>{ "name": "Los Angeles", "state": "CA", "country": "USA" }; db .collection("cities") .doc("LA") .set(city) .onError((e, _) => print("Error writing document: $e"));
Use the set()
method:
Use the set()
method:
Use the set()
method:
Use the Set()
method:
// Add a new document in collection 'cities' db->Collection("cities") .Document("LA") .Set({{"name", FieldValue::String("Los Angeles")}, {"state", FieldValue::String("CA")}, {"country", FieldValue::String("USA")}}) .OnCompletion([](const Future<void>& future) { if (future.error() == Error::kErrorOk) { std::cout << "DocumentSnapshot successfully written!" << std::endl; } else { std::cout << "Error writing document: " << future.error_message() << std::endl; } });
Use the set()
method:
Use the Set()
method:
Use the set()
method:
PHP
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries .
Use the SetAsync()
method:
DocumentReference docRef = db.Collection("cities").Document("LA"); Dictionary<string, object> city = new Dictionary<string, object> { { "Name", "Los Angeles" }, { "State", "CA" }, { "Country", "USA" } }; docRef.SetAsync(city).ContinueWithOnMainThread(task => { Debug.Log("Added data to the LA document in the cities collection."); });
Use the SetAsync()
method:
Use the set()
method:
If the document does not exist, it will be created. If the document does exist, its contents will be overwritten with the newly provided data, unless you specify that the data should be merged into the existing document, as follows:
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
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries .
DocumentReference docRef = db.Collection("cities").Document("LA"); Dictionary<string, object> update = new Dictionary<string, object> { { "capital", false } }; docRef.SetAsync(update, SetOptions.MergeAll);
If you're not sure whether the document exists, pass the option to merge the new data with any existing document to avoid overwriting entire documents. For documents that contain maps, if you specify a set with a field that contains an empty map, the map field of the target document is overwritten.
انواع داده ها
Cloud Firestore lets you write a variety of data types inside a document, including strings, booleans, numbers, dates, null, and nested arrays and objects. Cloud Firestore always stores numbers as doubles, regardless of what type of number you use in your code.
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
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries .
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);
اشیاء سفارشی
Using Map
or Dictionary
objects to represent your documents is often inconvenient, so Cloud Firestore supports writing documents with custom classes. Cloud Firestore converts the objects to supported data types.
Using custom classes, you can rewrite the initial example in the following way:
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, )
Each custom class must have a public constructor that takes no arguments. In addition, the class must include a public getter for each property.
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
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries .
[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.
Add a document
When you use set()
to create a document, you must specify an ID for the document to create, as shown in the following example:
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
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries .
db.Collection("cities").Document("new-city-id").SetAsync(city);
If there isn't a meaningful ID for the document, Cloud Firestore can auto-generate an ID for you. You can call the following language-specific add()
methods:
Use the addDoc()
method:
import { collection, addDoc } from "firebase/firestore"; // Add a new document with a generated id. const docRef = await addDoc(collection(db, "cities"), { name: "Tokyo", country: "Japan" }); console.log("Document written with ID: ", docRef.id);
Use the add()
method:
// Add a new document with a generated id. db.collection("cities").add({ name: "Tokyo", country: "Japan" }) .then((docRef) => { console.log("Document written with ID: ", docRef.id); }) .catch((error) => { console.error("Error adding document: ", error); });
Use the addDocument()
method:
// Add a new document with a generated id. do { let ref = try await db.collection("cities").addDocument(data: [ "name": "Tokyo", "country": "Japan" ]) print("Document added with ID: \(ref.documentID)") } catch { print("Error adding document: \(error)") }
Use the addDocumentWithData:
method:
// Add a new document with a generated id. __block FIRDocumentReference *ref = [[self.db collectionWithPath:@"cities"] addDocumentWithData:@{ @"name": @"Tokyo", @"country": @"Japan" } completion:^(NSError * _Nullable error) { if (error != nil) { NSLog(@"Error adding document: %@", error); } else { NSLog(@"Document added with ID: %@", ref.documentID); } }];
Use the add()
method:
// Add a new document with a generated id. val data = hashMapOf( "name" to "Tokyo", "country" to "Japan", ) db.collection("cities") .add(data) .addOnSuccessListener { documentReference -> Log.d(TAG, "DocumentSnapshot written with ID: ${documentReference.id}") } .addOnFailureListener { e -> Log.w(TAG, "Error adding document", e) }
Use the add()
method:
// Add a new document with a generated id. Map<String, Object> data = new HashMap<>(); data.put("name", "Tokyo"); data.put("country", "Japan"); db.collection("cities") .add(data) .addOnSuccessListener(new OnSuccessListener<DocumentReference>() { @Override public void onSuccess(DocumentReference documentReference) { Log.d(TAG, "DocumentSnapshot written with ID: " + documentReference.getId()); } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { Log.w(TAG, "Error adding document", e); } });
Use the add()
method:
// Add a new document with a generated id. final data = {"name": "Tokyo", "country": "Japan"}; db.collection("cities").add(data).then((documentSnapshot) => print("Added Data with ID: ${documentSnapshot.id}"));
Use the add()
method:
Use the add()
method:
Use the add()
method:
Use the Add()
method:
db->Collection("cities").Add({/*some data*/});
Use the add()
method:
Use the Add()
method:
Use the add()
method:
PHP
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries .
Use the AddAsync()
method:
Dictionary<string, object> city = new Dictionary<string, object> { { "Name", "Tokyo" }, { "Country", "Japan" } }; db.Collection("cities").AddAsync(city).ContinueWithOnMainThread(task => { DocumentReference addedDocRef = task.Result; Debug.Log(String.Format("Added document with ID: {0}.", addedDocRef.Id)); });
Use the AddAsync()
method:
Use the add()
method:
In some cases, it can be useful to create a document reference with an auto-generated ID, then use the reference later. For this use case, you can call doc()
in the following way:
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
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries .
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)); });
In the backend, .add(...)
and .doc().set(...)
are equivalent, so you can use either option.
یک سند را به روز کنید
To update some fields of a document without overwriting the entire document, use the following language-specific update()
methods:
Use the updateDoc()
method:
import { doc, updateDoc } from "firebase/firestore"; const washingtonRef = doc(db, "cities", "DC"); // Set the "capital" field of the city 'DC' await updateDoc(washingtonRef, { capital: true });
Use the update()
method:
var washingtonRef = db.collection("cities").doc("DC"); // Set the "capital" field of the city 'DC' return washingtonRef.update({ capital: true }) .then(() => { console.log("Document successfully updated!"); }) .catch((error) => { // The document probably doesn't exist. console.error("Error updating document: ", error); });
Use the updateData()
method:
let washingtonRef = db.collection("cities").document("DC") // Set the "capital" field of the city 'DC' do { try await washingtonRef.updateData([ "capital": true ]) print("Document successfully updated") } catch { print("Error updating document: \(error)") }
Use the updateData:
method:
FIRDocumentReference *washingtonRef = [[self.db collectionWithPath:@"cities"] documentWithPath:@"DC"]; // Set the "capital" field of the city [washingtonRef updateData:@{ @"capital": @YES } completion:^(NSError * _Nullable error) { if (error != nil) { NSLog(@"Error updating document: %@", error); } else { NSLog(@"Document successfully updated"); } }];
Use the update()
method:
val washingtonRef = db.collection("cities").document("DC") // Set the "isCapital" field of the city 'DC' washingtonRef .update("capital", true) .addOnSuccessListener { Log.d(TAG, "DocumentSnapshot successfully updated!") } .addOnFailureListener { e -> Log.w(TAG, "Error updating document", e) }
Use the update()
method:
DocumentReference washingtonRef = db.collection("cities").document("DC"); // Set the "isCapital" field of the city 'DC' washingtonRef .update("capital", true) .addOnSuccessListener(new OnSuccessListener<Void>() { @Override public void onSuccess(Void aVoid) { Log.d(TAG, "DocumentSnapshot successfully updated!"); } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { Log.w(TAG, "Error updating document", e); } });
Use the update()
method:
final washingtonRef = db.collection("cites").doc("DC"); washingtonRef.update({"capital": true}).then( (value) => print("DocumentSnapshot successfully updated!"), onError: (e) => print("Error updating document $e"));
Use the update()
method:
Use the update()
method:
Use the update()
method:
Use the Update()
method:
DocumentReference washington_ref = db->Collection("cities").Document("DC"); // Set the "capital" field of the city "DC". washington_ref.Update({{"capital", FieldValue::Boolean(true)}});
Use the update()
method:
Use the Update()
method:
Use the update()
method:
PHP
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries .
Use the UpdateAsync()
method:
DocumentReference cityRef = db.Collection("cities").Document("new-city-id"); Dictionary<string, object> updates = new Dictionary<string, object> { { "Capital", false } }; cityRef.UpdateAsync(updates).ContinueWithOnMainThread(task => { Debug.Log( "Updated the Capital field of the new-city-id document in the cities collection."); }); // You can also update a single field with: cityRef.UpdateAsync("Capital", false);
Use the UpdateAsync()
method:
Use the update()
method:
مهر زمان سرور
You can set a field in your document to a server timestamp which tracks when the server receives the 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
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries .
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."); });
When updating multiple timestamp fields inside of a transaction , each field receives the same server timestamp value.
Update fields in nested objects
If your document contains nested objects, you can use the dot notation to reference nested fields within the document when you call 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
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries .
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."); });
Dot notation allows you to update a single nested field without overwriting other nested fields. If you update a nested field without dot notation, you will overwrite the entire map field, as shown in the following example:
// 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 } */
Update elements in an array
If your document contains an array field, you can use arrayUnion()
and arrayRemove()
to add and remove elements. arrayUnion()
adds elements to an array but only elements not already present. arrayRemove()
removes all instances of each given element.
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
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries .
// This is not yet supported in the Unity SDK
// Not supported yet
Increment a numeric value
You can increment or decrement a numeric field value as shown in the following example. An increment operation increases or decreases the current value of a field by the given amount.
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
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries .
// This is not yet supported in the Unity SDK.
Increment operations are useful for implementing counters. Note that updating a single document too quickly can lead to contention or errors . If you need to update your counter at a very high rate, see the Distributed counters page.