將資料新增至 Cloud Firestore

這份文件說明如何在以下位置設定、新增或更新個別文件： Cloud Firestore。如要大量寫入資料，請參閱 交易和批次寫入。

總覽

您可以透過下列其中一種方式將資料寫入 Cloud Firestore：

  • 在集合內設定文件的資料，明確指定 文件 ID。
  • 將新文件加入集合。在本例中，Cloud Firestore 系統會自動產生文件 ID。
  • 利用自動產生的 ID 建立空白文件。 以便稍後指派資料
，瞭解如何調查及移除這項存取權。

事前準備

初始化 Cloud Firestore 以設定、新增或更新資料之前： 您必須完成下列步驟：

初始化 Cloud Firestore

初始化 Cloud Firestore 的執行個體：

Web

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。

如要在裝置連線中斷時保留資料，請參閱啟用離線資料說明文件。

Web

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。

如要在裝置連線中斷時保留資料，請參閱啟用離線資料說明文件。

Swift
注意：這項產品不適用於 watchOS 和 App Clip 目標。 
import FirebaseCore
import FirebaseFirestore
 
FirebaseApp.configure()

let db = Firestore.firestore()
AppDelegate.swift
Objective-C
注意：這項產品不適用於 watchOS 和 App Clip 目標。 
@import FirebaseCore;
@import FirebaseFirestore;

// Use Firebase library to configure APIs
[FIRApp configure];
  
FIRFirestore *defaultFirestore = [FIRFirestore firestore];
AppDelegate.m

Kotlin+KTX

// Access a Cloud Firestore instance from your Activity
 
val db = Firebase.firestore
DocSnippets.kt

Java

// Access a Cloud Firestore instance from your Activity
 
FirebaseFirestore db = FirebaseFirestore.getInstance();
DocSnippets.java

Dart

db = FirebaseFirestore.instance;
Java
Cloud Firestore SDK 的初始化方式會根據 您的環境。最常見的做法如下。如需完整參考資料 看 初始化 Admin SDK：
  • 在 Google Cloud 上初始化 
    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 與管理員 >服務帳戶 也能前往 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();
    • Python
    Cloud Firestore SDK 的初始化方式會根據 您的環境。最常見的做法如下。如需完整參考資料 看 初始化 Admin SDK：
  • 在 Google Cloud 上初始化 
    import firebase_admin
from firebase_admin import firestore

# Application Default credentials are automatically created.
app = firebase_admin.initialize_app()
db = firestore.client()
    firestore.py

    現有的應用程式預設憑證也可用來初始化 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()
    firestore.py
  • 在自己的伺服器上初始化

    如要在自己的伺服器上使用 Firebase Admin SDK，請使用 服務帳戶

    前往 IAM 與管理員 >服務帳戶 也能前往 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()
    firestore.py

    • Python

    Cloud Firestore SDK 的初始化方式會根據 您的環境。最常見的做法如下。如需完整參考資料 看 初始化 Admin SDK：
  • 在 Google Cloud 上初始化 
    import firebase_admin
from firebase_admin import firestore_async

# Application Default credentials are automatically created.
app = firebase_admin.initialize_app()
db = firestore_async.client()
    firestore_async.py

    現有的應用程式預設憑證也可用來初始化 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()
    firestore_async.py
  • 在自己的伺服器上初始化

    如要在自己的伺服器上使用 Firebase Admin SDK，請使用 服務帳戶

    前往 IAM 與管理員 >服務帳戶 也能前往 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()
    firestore_async.py
    • C++
    // Make sure the call to `Create()` happens some time before you call Firestore::GetInstance().
App::Create();
Firestore* db = Firestore::GetInstance();
    AppDelegate.mm
    Node.js
    Cloud Firestore SDK 的初始化方式會根據 您的環境。最常見的做法如下。如需完整參考資料 看 初始化 Admin SDK：
    • 在 Cloud Functions 上初始化 
      const { initializeApp, applicationDefault, cert } = require('firebase-admin/app');
const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
       
      initializeApp();

const db = getFirestore();

      index.js
    • 在 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();
      index.js
    • 在自己的伺服器上初始化

      如要在自己的伺服器 (或任何其他 Node.js 環境) 上使用 Firebase Admin SDK， 請使用服務帳戶。 前往 IAM 與管理員 >服務帳戶。產生新的私密金鑰並儲存 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();

      index.js
    Go
    Cloud Firestore SDK 的初始化方式會根據 您的環境。最常見的做法如下。如需完整參考資料 看 初始化 Admin SDK：
  • 在 Google Cloud 上初始化 
    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 與管理員 >服務帳戶 也能前往 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

    PHP

    如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端，請參閱 Cloud Firestore 用戶端程式庫。 

    use Google\Cloud\Firestore\FirestoreClient;

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

    C#

    如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端，請參閱 Cloud Firestore 用戶端程式庫。 

    FirestoreDb db = FirestoreDb.Create(project);
Console.WriteLine("Created Cloud Firestore client with project ID: {0}", project);
    Program.cs
    Ruby
    require "google/cloud/firestore"

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

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

    設定文件

    如要建立或覆寫單一文件，請使用下列各語言專用的 set() 方法：

    Web

    使用 setDoc() 方法：

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

// Add a new document in collection "cities"
await setDoc(doc(db, "cities", "LA"), {
  name: "Los Angeles",
  state: "CA",
  country: "USA"
});
    set_document.js

    Web

    使用 set() 方法：

    // Add a new document in collection "cities"
db.collection("cities").doc("LA").set({
    name: "Los Angeles",
    state: "CA",
    country: "USA"
})
.then(() => {
    console.log("Document successfully written!");
})
.catch((error) => {
    console.error("Error writing document: ", error);
});
    test.firestore.js
    Swift

    使用 setData() 方法：

    注意：這項產品不適用於 watchOS 和 App Clip 目標。 
    // Add a new document in collection "cities"
do {
  try await db.collection("cities").document("LA").setData([
    "name": "Los Angeles",
    "state": "CA",
    "country": "USA"
  ])
  print("Document successfully written!")
} catch {
  print("Error writing document: \(error)")
}
    ViewController.swift
    Objective-C

    使用 setData: 方法：

    注意：這項產品不適用於 watchOS 和 App Clip 目標。 
    // Add a new document in collection "cities"
[[[self.db collectionWithPath:@"cities"] documentWithPath:@"LA"] setData:@{
  @"name": @"Los Angeles",
  @"state": @"CA",
  @"country": @"USA"
} completion:^(NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"Error writing document: %@", error);
  } else {
    NSLog(@"Document successfully written!");
  }
}];
    ViewController.m

    Kotlin+KTX

    使用 set() 方法：

    val city = hashMapOf(
    "name" to "Los Angeles",
    "state" to "CA",
    "country" to "USA",
)

db.collection("cities").document("LA")
    .set(city)
    .addOnSuccessListener { Log.d(TAG, "DocumentSnapshot successfully written!") }
    .addOnFailureListener { e -> Log.w(TAG, "Error writing document", e) }
    DocSnippets.kt

    Java

    使用 set() 方法：

    Map<String, Object> city = new HashMap<>();
city.put("name", "Los Angeles");
city.put("state", "CA");
city.put("country", "USA");

db.collection("cities").document("LA")
        .set(city)
        .addOnSuccessListener(new OnSuccessListener<Void>() {
            @Override
            public void onSuccess(Void aVoid) {
                Log.d(TAG, "DocumentSnapshot successfully written!");
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                Log.w(TAG, "Error writing document", e);
            }
        });
    DocSnippets.java

    Dart

    使用 set() 方法：

    final city = <String, String>{
  "name": "Los Angeles",
  "state": "CA",
  "country": "USA"
};

db
    .collection("cities")
    .doc("LA")
    .set(city)
    .onError((e, _) => print("Error writing document: $e"));
    firestore.dart
    Java

    使用 set() 方法：

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

    使用 set() 方法：

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

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

    Python

    使用 set() 方法：

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

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

    使用 Set() 方法：

    // Add a new document in collection 'cities'
db->Collection("cities")
    .Document("LA")
    .Set({{"name", FieldValue::String("Los Angeles")},
          {"state", FieldValue::String("CA")},
          {"country", FieldValue::String("USA")}})
    .OnCompletion([](const Future<void>& future) {
      if (future.error() == Error::kErrorOk) {
        std::cout << "DocumentSnapshot successfully written!" << std::endl;
      } else {
        std::cout << "Error writing document: " << future.error_message()
                  << std::endl;
      }
    });
    snippets.cpp
    Node.js

    使用 set() 方法：

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

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

    使用 Set() 方法：

    
import (
	"context"
	"log"

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

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

	return err
}

    save_data_set_from_map.go
    PHP

    使用 set() 方法：

    PHP

    如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端，請參閱 Cloud Firestore 用戶端程式庫。 

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

    使用 SetAsync() 方法：

    DocumentReference docRef = db.Collection("cities").Document("LA");
Dictionary<string, object> city = new Dictionary<string, object>
{
	{ "Name", "Los Angeles" },
	{ "State", "CA" },
	{ "Country", "USA" }
};
docRef.SetAsync(city).ContinueWithOnMainThread(task => {
	Debug.Log("Added data to the LA document in the cities collection.");
});
    C#

    使用 SetAsync() 方法：

    DocumentReference docRef = db.Collection("cities").Document("LA");
Dictionary<string, object> city = new Dictionary<string, object>
{
    { "name", "Los Angeles" },
    { "state", "CA" },
    { "country", "USA" }
};
await docRef.SetAsync(city);
    Program.cs
    Ruby

    使用 set() 方法：

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

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

city_ref.set data
    add_data.rb

    如果文件不存在，系統將建立文件。如果文件確實存在 系統將以新提供的資料覆寫其內容，除非您 指定資料應合併至現有文件，如下所示：

    Web

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

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

    Web

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

var setWithMerge = cityRef.set({
    capital: true
}, { merge: true });
    test.firestore.js
    Swift
    注意：這項產品不適用於 watchOS 和 App Clip 目標。 
    // Update one field, creating the document if it does not exist.
db.collection("cities").document("BJ").setData([ "capital": true ], merge: true)
    ViewController.swift
    Objective-C
    注意：這項產品不適用於 watchOS 和 App Clip 目標。 
    // Write to the document reference, merging data with existing
// if the document already exists
[[[self.db collectionWithPath:@"cities"] documentWithPath:@"BJ"]
     setData:@{ @"capital": @YES }
     merge:YES
     completion:^(NSError * _Nullable error) {
       // ...
     }];
    ViewController.m

    Kotlin+KTX

    // Update one field, creating the document if it does not already exist.
val data = hashMapOf("capital" to true)

db.collection("cities").document("BJ")
    .set(data, SetOptions.merge())
    DocSnippets.kt

    Java

    // Update one field, creating the document if it does not already exist.
Map<String, Object> data = new HashMap<>();
data.put("capital", true);

db.collection("cities").document("BJ")
        .set(data, SetOptions.merge());
    DocSnippets.java

    Dart

    // Update one field, creating the document if it does not already exist.
final data = {"capital": true};

db.collection("cities").doc("BJ").set(data, SetOptions(merge: true));
    firestore.dart
    Java
    // asynchronously update doc, create the document if missing
Map<String, Object> update = new HashMap<>();
update.put("capital", true);

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

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

    Python

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

await city_ref.set({"capital": True}, merge=True)
    snippets.py
    C++
    db->Collection("cities").Document("BJ").Set(
    {{"capital", FieldValue::Boolean(true)}}, SetOptions::Merge());
    snippets.cpp
    Node.js
    const cityRef = db.collection('cities').doc('BJ');

const res = await cityRef.set({
  capital: true
}, { merge: true });
    index.js
    Go
    
import (
	"context"
	"log"

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

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

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

	return err
}

    save_data_set_doc_upsert.go
    PHP

    PHP

    如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端，請參閱 Cloud Firestore 用戶端程式庫。 

    $cityRef = $db->collection('samples/php/cities')->document('BJ');
$cityRef->set([
    'capital' => true
], ['merge' => true]);
    data_set_doc_upsert.php
    Unity
    DocumentReference docRef = db.Collection("cities").Document("LA");
Dictionary<string, object> update = new Dictionary<string, object>
{
	{ "capital", false }
};
docRef.SetAsync(update, SetOptions.MergeAll);
    C#
    DocumentReference docRef = db.Collection("cities").Document("LA");
Dictionary<string, object> update = new Dictionary<string, object>
{
    { "capital", false }
};
await docRef.SetAsync(update, SetOptions.MergeAll);
    Program.cs
    Ruby
    city_ref = firestore.doc "#{collection_path}/LA"
city_ref.set({ capital: false }, merge: true)
    add_data.rb

    如果不確定文件是否存在，請傳送合併新文件的選項。 資料，避免覆寫整份文件。適用對象 包含地圖的文件，如果您用欄位指定一組含有 如果地圖為空白，則會覆寫目標文件的對應欄位。

    資料類型

    Cloud Firestore 可讓您在文件中撰寫多種資料類型、 包括字串、布林值、數字、日期、空值和巢狀陣列 如需儲存大量結構化物件 建議使用 Cloud BigtableCloud Firestore 一律會將數字儲存為雙精度浮點數，無論 您需要在程式碼中使用哪一種號碼

    Web

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

const docData = {
    stringExample: "Hello world!",
    booleanExample: true,
    numberExample: 3.14159265,
    dateExample: Timestamp.fromDate(new Date("December 10, 1815")),
    arrayExample: [5, true, "hello"],
    nullExample: null,
    objectExample: {
        a: 5,
        b: {
            nested: "foo"
        }
    }
};
await setDoc(doc(db, "data", "one"), docData);
    data_types.js

    Web

    var docData = {
    stringExample: "Hello world!",
    booleanExample: true,
    numberExample: 3.14159265,
    dateExample: firebase.firestore.Timestamp.fromDate(new Date("December 10, 1815")),
    arrayExample: [5, true, "hello"],
    nullExample: null,
    objectExample: {
        a: 5,
        b: {
            nested: "foo"
        }
    }
};
db.collection("data").doc("one").set(docData).then(() => {
    console.log("Document successfully written!");
});
    test.firestore.js
    Swift
    注意：這項產品不適用於 watchOS 和 App Clip 目標。 
    let docData: [String: Any] = [
  "stringExample": "Hello world!",
  "booleanExample": true,
  "numberExample": 3.14159265,
  "dateExample": Timestamp(date: Date()),
  "arrayExample": [5, true, "hello"],
  "nullExample": NSNull(),
  "objectExample": [
    "a": 5,
    "b": [
      "nested": "foo"
    ]
  ]
]
do {
  try await db.collection("data").document("one").setData(docData)
  print("Document successfully written!")
} catch {
  print("Error writing document: \(error)")
}
    ViewController.swift
    Objective-C
    注意：這項產品不適用於 watchOS 和 App Clip 目標。 
    NSDictionary *docData = @{
  @"stringExample": @"Hello world!",
  @"booleanExample": @YES,
  @"numberExample": @3.14,
  @"dateExample": [FIRTimestamp timestampWithDate:[NSDate date]],
  @"arrayExample": @[@5, @YES, @"hello"],
  @"nullExample": [NSNull null],
  @"objectExample": @{
    @"a": @5,
    @"b": @{
      @"nested": @"foo"
    }
  }
};

[[[self.db collectionWithPath:@"data"] documentWithPath:@"one"] setData:docData
    completion:^(NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"Error writing document: %@", error);
      } else {
        NSLog(@"Document successfully written!");
      }
    }];
    ViewController.m

    Kotlin+KTX

    val docData = hashMapOf(
    "stringExample" to "Hello world!",
    "booleanExample" to true,
    "numberExample" to 3.14159265,
    "dateExample" to Timestamp(Date()),
    "listExample" to arrayListOf(1, 2, 3),
    "nullExample" to null,
)

val nestedData = hashMapOf(
    "a" to 5,
    "b" to true,
)

docData["objectExample"] = nestedData

db.collection("data").document("one")
    .set(docData)
    .addOnSuccessListener { Log.d(TAG, "DocumentSnapshot successfully written!") }
    .addOnFailureListener { e -> Log.w(TAG, "Error writing document", e) }
    DocSnippets.kt

    Java

    Map<String, Object> docData = new HashMap<>();
docData.put("stringExample", "Hello world!");
docData.put("booleanExample", true);
docData.put("numberExample", 3.14159265);
docData.put("dateExample", new Timestamp(new Date()));
docData.put("listExample", Arrays.asList(1, 2, 3));
docData.put("nullExample", null);

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

docData.put("objectExample", nestedData);

db.collection("data").document("one")
        .set(docData)
        .addOnSuccessListener(new OnSuccessListener<Void>() {
            @Override
            public void onSuccess(Void aVoid) {
                Log.d(TAG, "DocumentSnapshot successfully written!");
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                Log.w(TAG, "Error writing document", e);
            }
        });
    DocSnippets.java

    Dart

    final docData = {
  "stringExample": "Hello world!",
  "booleanExample": true,
  "numberExample": 3.14159265,
  "dateExample": Timestamp.now(),
  "listExample": [1, 2, 3],
  "nullExample": null
};

final nestedData = {
  "a": 5,
  "b": true,
};

docData["objectExample"] = nestedData;

db
    .collection("data")
    .doc("one")
    .set(docData)
    .onError((e, _) => print("Error writing document: $e"));
    firestore.dart
    Java
    Map<String, Object> docData = new HashMap<>();
docData.put("stringExample", "Hello, World");
docData.put("booleanExample", false);
docData.put("numberExample", 3.14159265);
docData.put("nullExample", null);

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

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

docData.put("objectExample", objectExample);

ApiFuture<WriteResult> future = db.collection("data").document("one").set(docData);
System.out.println("Update time : " + future.get().getUpdateTime());
    ManageDataSnippets.java
    Python
    data = {
    "stringExample": "Hello, World!",
    "booleanExample": True,
    "numberExample": 3.14159265,
    "dateExample": datetime.datetime.now(tz=datetime.timezone.utc),
    "arrayExample": [5, True, "hello"],
    "nullExample": None,
    "objectExample": {"a": 5, "b": True},
}

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

    Python

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

await db.collection("data").document("one").set(data)
    snippets.py
    C++
    MapFieldValue doc_data{
    {"stringExample", FieldValue::String("Hello world!")},
    {"booleanExample", FieldValue::Boolean(true)},
    {"numberExample", FieldValue::Double(3.14159265)},
    {"dateExample", FieldValue::Timestamp(Timestamp::Now())},
    {"arrayExample", FieldValue::Array({FieldValue::Integer(1),
                                        FieldValue::Integer(2),
                                        FieldValue::Integer(3)})},
    {"nullExample", FieldValue::Null()},
    {"objectExample",
     FieldValue::Map(
         {{"a", FieldValue::Integer(5)},
          {"b", FieldValue::Map(
                    {{"nested", FieldValue::String("foo")}})}})},
};

db->Collection("data").Document("one").Set(doc_data).OnCompletion(
    [](const Future<void>& future) {
      if (future.error() == Error::kErrorOk) {
        std::cout << "DocumentSnapshot successfully written!" << std::endl;
      } else {
        std::cout << "Error writing document: " << future.error_message()
                  << std::endl;
      }
    });
    snippets.cpp
    Node.js
    const data = {
  stringExample: 'Hello, World!',
  booleanExample: true,
  numberExample: 3.14159265,
  dateExample: Timestamp.fromDate(new Date('December 10, 1815')),
  arrayExample: [5, true, 'hello'],
  nullExample: null,
  objectExample: {
    a: 5,
    b: true
  }
};

const res = await db.collection('data').doc('one').set(data);
    index.js
    Go
    
import (
	"context"
	"log"
	"time"

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

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

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

	return err
}

    save_data_set_from_map_nested.go
    PHP

    PHP

    如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端，請參閱 Cloud Firestore 用戶端程式庫。 

    $data = [
    'stringExample' => 'Hello World',
    'booleanExample' => true,
    'numberExample' => 3.14159265,
    'dateExample' => new Timestamp(new DateTime()),
    'arrayExample' => array(5, true, 'hello'),
    'nullExample' => null,
    'objectExample' => ['a' => 5, 'b' => true],
    'documentReferenceExample' => $db->collection('samples/php/data')->document('two'),
];
$db->collection('samples/php/data')->document('one')->set($data);
printf('Set multiple data-type data for the one document in the data collection.' . PHP_EOL);
    data_set_from_map_nested.php
    Unity
    DocumentReference docRef = db.Collection("data").Document("one");
Dictionary<string, object> docData = new Dictionary<string, object>
{
	{ "stringExample", "Hello World" },
	{ "booleanExample", false },
	{ "numberExample", 3.14159265 },
	{ "nullExample", null },
	{ "arrayExample", new List<object>() { 5, true, "Hello" } },
	{ "objectExample", new Dictionary<string, object>
		{
			{ "a", 5 },
			{ "b", true },
		}
	},
};

docRef.SetAsync(docData);
    C#
    DocumentReference docRef = db.Collection("data").Document("one");
Dictionary<string, object> docData = new Dictionary<string, object>
{
    { "stringExample", "Hello World" },
    { "booleanExample", false },
    { "numberExample", 3.14159265 },
    { "nullExample", null },
    { "arrayExample", new object[] { 5, true, "Hello" } },
    { "objectExample", new Dictionary<string, object>
        {
            { "a", 5 },
            { "b", true},
        }
    }
};

await docRef.SetAsync(docData);
    Program.cs
    Ruby
    doc_ref = firestore.doc "#{collection_path}/one"

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

doc_ref.set data
    add_data.rb

    自訂物件

    經常使用 Map 或 Dictionary 物件代表文件 使用起來不方便，因此 Cloud Firestore 支援以自訂方式撰寫文件 類別Cloud Firestore 會將物件轉換為支援的資料類型。

    使用自訂類別時，您可以透過下列方式重寫初始範例：

    Web

    class City {
    constructor (name, state, country ) {
        this.name = name;
        this.state = state;
        this.country = country;
    }
    toString() {
        return this.name + ', ' + this.state + ', ' + this.country;
    }
}

// Firestore data converter
const cityConverter = {
    toFirestore: (city) => {
        return {
            name: city.name,
            state: city.state,
            country: city.country
            };
    },
    fromFirestore: (snapshot, options) => {
        const data = snapshot.data(options);
        return new City(data.name, data.state, data.country);
    }
};
    city_custom_object.js

    Web

    class City {
    constructor (name, state, country ) {
        this.name = name;
        this.state = state;
        this.country = country;
    }
    toString() {
        return this.name + ', ' + this.state + ', ' + this.country;
    }
}

// Firestore data converter
var cityConverter = {
    toFirestore: function(city) {
        return {
            name: city.name,
            state: city.state,
            country: city.country
            };
    },
    fromFirestore: function(snapshot, options){
        const data = snapshot.data(options);
        return new City(data.name, data.state, data.country);
    }
};
    test.firestore.js
    Swift
    注意：這項產品不適用於 watchOS 和 App Clip 目標。 
    public struct City: Codable {

  let name: String
  let state: String?
  let country: String?
  let isCapital: Bool?
  let population: Int64?

  enum CodingKeys: String, CodingKey {
    case name
    case state
    case country
    case isCapital = "capital"
    case population
  }

}
    ViewController.swift
    Objective-C
    注意：這項產品不適用於 watchOS 和 App Clip 目標。 
    // This isn't supported in Objective-C.

    Kotlin+KTX

    data class City(
    val name: String? = null,
    val state: String? = null,
    val country: String? = null,
    @field:JvmField // use this annotation if your Boolean field is prefixed with 'is'
    val isCapital: Boolean? = null,
    val population: Long? = null,
    val regions: List<String>? = null,
)
    DocSnippets.kt

    Java

    每個自訂類別都必須有一個不使用引數的公開建構函式。於 此外，類別必須包含一個公開的 getter。 

    public class City {


    private String name;
    private String state;
    private String country;
    private boolean capital;
    private long population;
    private List<String> regions;

    public City() {}

    public City(String name, String state, String country, boolean capital, long population, List<String> regions) {
        // ...
    }

    public String getName() {
        return name;
    }

    public String getState() {
        return state;
    }

    public String getCountry() {
        return country;
    }

    public boolean isCapital() {
        return capital;
    }

    public long getPopulation() {
        return population;
    }

    public List<String> getRegions() {
        return regions;
    }

}
    DocSnippets.java

    Dart

    class City {
  final String? name;
  final String? state;
  final String? country;
  final bool? capital;
  final int? population;
  final List<String>? regions;

  City({
    this.name,
    this.state,
    this.country,
    this.capital,
    this.population,
    this.regions,
  });

  factory City.fromFirestore(
    DocumentSnapshot<Map<String, dynamic>> snapshot,
    SnapshotOptions? options,
  ) {
    final data = snapshot.data();
    return City(
      name: data?['name'],
      state: data?['state'],
      country: data?['country'],
      capital: data?['capital'],
      population: data?['population'],
      regions:
          data?['regions'] is Iterable ? List.from(data?['regions']) : null,
    );
  }

  Map<String, dynamic> toFirestore() {
    return {
      if (name != null) "name": name,
      if (state != null) "state": state,
      if (country != null) "country": country,
      if (capital != null) "capital": capital,
      if (population != null) "population": population,
      if (regions != null) "regions": regions,
    };
  }
}
    firestore_add_data_custom_objects_snippet.dart
    Java
    public City() {
  // Must have a public no-argument constructor
}

// Initialize all fields of a city
public City(
    String name,
    String state,
    String country,
    Boolean capital,
    Long population,
    List<String> regions) {
  this.name = name;
  this.state = state;
  this.country = country;
  this.capital = capital;
  this.population = population;
  this.regions = regions;
}
    City.java
    Python
    class City:
    def __init__(self, name, state, country, capital=False, population=0, regions=[]):
        self.name = name
        self.state = state
        self.country = country
        self.capital = capital
        self.population = population
        self.regions = regions

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

    def to_dict(self):
        # ...

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


    snippets.py

    Python

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

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

    def to_dict(self):
        # ...

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


    snippets.py
    C++
    // This is not yet supported.
    Node.js
    // Node.js uses JavaScript objects
    Go
    
// City represents a city.
type City struct {
	Name       string   `firestore:"name,omitempty"`
	State      string   `firestore:"state,omitempty"`
	Country    string   `firestore:"country,omitempty"`
	Capital    bool     `firestore:"capital,omitempty"`
	Population int64    `firestore:"population,omitempty"`
	Density    int64    `firestore:"density,omitempty"`
	Regions    []string `firestore:"regions,omitempty"`
}

    custom_type_definition.go
    PHP

    PHP

    如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端，請參閱 Cloud Firestore 用戶端程式庫。 

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

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

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

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

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

    City.php
    Unity
    [FirestoreData]
public class City
{
	[FirestoreProperty]
	public string Name { get; set; }

	[FirestoreProperty]
	public string State { get; set; }

	[FirestoreProperty]
	public string Country { get; set; }

	[FirestoreProperty]
	public bool Capital { get; set; }

	[FirestoreProperty]
	public long Population { get; set; }
}
    C#
    [FirestoreData]
public class City
{
    [FirestoreProperty]
    public string Name { get; set; }

    [FirestoreProperty]
    public string State { get; set; }

    [FirestoreProperty]
    public string Country { get; set; }

    [FirestoreProperty]
    public bool Capital { get; set; }

    [FirestoreProperty]
    public long Population { get; set; }
}
    Program.cs
    Ruby
    // This isn't supported in Ruby

    Web

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

// Set with cityConverter
const ref = doc(db, "cities", "LA").withConverter(cityConverter);
await setDoc(ref, new City("Los Angeles", "CA", "USA"));
    set_custom_object.js

    Web

    // Set with cityConverter
db.collection("cities").doc("LA")
  .withConverter(cityConverter)
  .set(new City("Los Angeles", "CA", "USA"));
    test.firestore.js
    Swift
    注意：這項產品不適用於 watchOS 和 App Clip 目標。 
    let city = City(name: "Los Angeles",
                state: "CA",
                country: "USA",
                isCapital: false,
                population: 5000000)

do {
  try db.collection("cities").document("LA").setData(from: city)
} catch let error {
  print("Error writing city to Firestore: \(error)")
}
    ViewController.swift
    Objective-C
    注意：這項產品不適用於 watchOS 和 App Clip 目標。 
    // This isn't supported in Objective-C.

    Kotlin+KTX

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

    Java

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

    Dart

    final city = City(
  name: "Los Angeles",
  state: "CA",
  country: "USA",
  capital: false,
  population: 5000000,
  regions: ["west_coast", "socal"],
);
final docRef = db
    .collection("cities")
    .withConverter(
      fromFirestore: City.fromFirestore,
      toFirestore: (City city, options) => city.toFirestore(),
    )
    .doc("LA");
await docRef.set(city);
    firestore.dart
    Java
    City city =
    new City("Los Angeles", "CA", "USA", false, 3900000L, Arrays.asList("west_coast", "socal"));
ApiFuture<WriteResult> future = db.collection("cities").document("LA").set(city);
// block on response if required
System.out.println("Update time : " + future.get().getUpdateTime());
    ManageDataSnippets.java
    Python
    city = City(name="Los Angeles", state="CA", country="USA")
db.collection("cities").document("LA").set(city.to_dict())
    snippets.py

    Python

    city = City(name="Los Angeles", state="CA", country="USA")
await db.collection("cities").document("LA").set(city.to_dict())
    snippets.py
    C++
    // This is not yet supported.
    Node.js
    // Node.js uses JavaScript objects
    Go
    
import (
	"context"
	"log"

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

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

	return err
}

    save_data_set_from_custom_type.go
    PHP
    // This isn't supported in PHP.
    Unity
    DocumentReference docRef = db.Collection("cities").Document("LA");
City city = new City
{
	Name = "Los Angeles",
	State = "CA",
	Country = "USA",
	Capital = false,
	Population = 3900000L
};
docRef.SetAsync(city);
    C#
    DocumentReference docRef = db.Collection("cities").Document("LA");
City city = new City
{
    Name = "Los Angeles",
    State = "CA",
    Country = "USA",
    Capital = false,
    Population = 3900000L
};
await docRef.SetAsync(city);
    Program.cs
    Ruby
    // This isn't supported in Ruby.

    新增文件

    使用 set() 建立文件時，您必須為 建立的文件，如以下範例所示：

    Web

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

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

    Web

    db.collection("cities").doc("new-city-id").set(data);
    test.firestore.js
    Swift
    注意：這項產品不適用於 watchOS 和 App Clip 目標。 
    db.collection("cities").document("new-city-id").setData(data)
    ViewController.swift
    Objective-C
    注意：這項產品不適用於 watchOS 和 App Clip 目標。 
    [[[self.db collectionWithPath:@"cities"] documentWithPath:@"new-city-id"]
    setData:data];
    ViewController.m

    Kotlin+KTX

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

    Java

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

    Dart

    db.collection("cities").doc("new-city-id").set({"name": "Chicago"});
    firestore.dart
    Java
    db.collection("cities").document("new-city-id").set(data);
    ManageDataSnippets.java
    Python
    db.collection("cities").document("new-city-id").set(data)
    snippets.py

    Python

    await db.collection("cities").document("new-city-id").set(data)
    snippets.py
    C++
    db->Collection("cities").Document("SF").Set({/*some data*/});
    snippets.cpp
    Node.js
    await db.collection('cities').doc('new-city-id').set(data);
    index.js
    Go
    
import (
	"context"
	"log"

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

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

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

	return err
}

    save_data_set_id_specified.go
    PHP

    PHP

    如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端，請參閱 Cloud Firestore 用戶端程式庫。 

    $db->collection('samples/php/cities')->document('new-city-id')->set($data);
    data_set_id_specified.php
    Unity
    db.Collection("cities").Document("new-city-id").SetAsync(city);
    C#
    await db.Collection("cities").Document("new-city-id").SetAsync(city);
    Program.cs
    Ruby
    city_ref = firestore.doc "#{collection_path}/new-city-id"
city_ref.set data
    add_data.rb

    如果文件沒有有意義的 ID，Cloud Firestore 可以 自動產生 ID您可以呼叫下列特定語言 add() 方法：

    Web

    使用 addDoc() 方法：

    import { collection, addDoc } from "firebase/firestore"; 

// Add a new document with a generated id.
const docRef = await addDoc(collection(db, "cities"), {
  name: "Tokyo",
  country: "Japan"
});
console.log("Document written with ID: ", docRef.id);
    add_document.js

    Web

    使用 add() 方法：

    // Add a new document with a generated id.
db.collection("cities").add({
    name: "Tokyo",
    country: "Japan"
})
.then((docRef) => {
    console.log("Document written with ID: ", docRef.id);
})
.catch((error) => {
    console.error("Error adding document: ", error);
});
    test.firestore.js
    Swift

    使用 addDocument() 方法：

    注意：這項產品不適用於 watchOS 和 App Clip 目標。 
    // Add a new document with a generated id.
do {
  let ref = try await db.collection("cities").addDocument(data: [
    "name": "Tokyo",
    "country": "Japan"
  ])
  print("Document added with ID: \(ref.documentID)")
} catch {
  print("Error adding document: \(error)")
}
    ViewController.swift
    Objective-C

    使用 addDocumentWithData: 方法：

    注意：這項產品不適用於 watchOS 和 App Clip 目標。 
    // Add a new document with a generated id.
__block FIRDocumentReference *ref =
    [[self.db collectionWithPath:@"cities"] addDocumentWithData:@{
      @"name": @"Tokyo",
      @"country": @"Japan"
    } completion:^(NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"Error adding document: %@", error);
      } else {
        NSLog(@"Document added with ID: %@", ref.documentID);
      }
    }];
    ViewController.m

    Kotlin+KTX

    使用 add() 方法：

    // Add a new document with a generated id.
val data = hashMapOf(
    "name" to "Tokyo",
    "country" to "Japan",
)

db.collection("cities")
    .add(data)
    .addOnSuccessListener { documentReference ->
        Log.d(TAG, "DocumentSnapshot written with ID: ${documentReference.id}")
    }
    .addOnFailureListener { e ->
        Log.w(TAG, "Error adding document", e)
    }
    DocSnippets.kt

    Java

    使用 add() 方法：