حذف داده‌ها از Cloud Firestore

مثال‌های زیر نحوه حذف اسناد، فیلدها، و مجموعه‌ها را نشان می‌دهد.

برای کمک هوش مصنوعی، پیام‌واره زیر را در عامل کدنویسی هوش مصنوعی خود (مانند Gemini در Android Studio،‏ Antigravity،‏ Claude Code،‏ Codex، و Cursor) کپی کنید. می‌توانید پیام‌واره را سفارشی‌سازی کنید و با نماینده‌تان تکرار کنید. برای اطلاعات دقیق نصب، به مهارت‌های عامل Firebase مراجعه کنید.

Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`. Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me delete documents, fields, and collections from Cloud Firestore in my app.

حذف کردن اسناد

برای حذف سند، از روش‌های delete() زیر که مختص زبان هستند استفاده کنید:

Web

از روش deleteDoc() استفاده کنید:

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

await deleteDoc(doc(db, "cities", "DC"));

Web

از روش delete() استفاده کنید:

db.collection("cities").doc("DC").delete().then(() => {
    console.log("Document successfully deleted!");
}).catch((error) => {
    console.error("Error removing document: ", error);
});
Swift

از روش delete() استفاده کنید:

توجه: این محصول در watchOS و App Clip دردسترس نیست.
do {
  try await db.collection("cities").document("DC").delete()
  print("Document successfully removed!")
} catch {
  print("Error removing document: \(error)")
}
Objective-C

از روش deleteDocumentWithCompletion: استفاده کنید:

توجه: این محصول در watchOS و App Clip دردسترس نیست.
[[[self.db collectionWithPath:@"cities"] documentWithPath:@"DC"]
    deleteDocumentWithCompletion:^(NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"Error removing document: %@", error);
      } else {
        NSLog(@"Document successfully removed!");
      }
}];

Kotlin

از روش delete() استفاده کنید:

db.collection("cities").document("DC")
    .delete()
    .addOnSuccessListener { Log.d(TAG, "DocumentSnapshot successfully deleted!") }
    .addOnFailureListener { e -> Log.w(TAG, "Error deleting document", e) }

Java

از روش delete() استفاده کنید:

db.collection("cities").document("DC")
        .delete()
        .addOnSuccessListener(new OnSuccessListener<Void>() {
            @Override
            public void onSuccess(Void aVoid) {
                Log.d(TAG, "DocumentSnapshot successfully deleted!");
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                Log.w(TAG, "Error deleting document", e);
            }
        });

Dart

از روش delete() استفاده کنید:

db.collection("cities").doc("DC").delete().then(
      (doc) => print("Document deleted"),
      onError: (e) => print("Error updating document $e"),
    );
جاوا

از روش delete() استفاده کنید:

// asynchronously delete a document
ApiFuture<WriteResult> writeResult = db.collection("cities").document("DC").delete();
// ...
System.out.println("Update time : " + writeResult.get().getUpdateTime());
پایتون

از روش delete() استفاده کنید:

db.collection("cities").document("DC").delete()

Python

از روش delete() استفاده کنید:

await db.collection("cities").document("DC").delete()
C++‎

از روش Delete() استفاده کنید:

db->Collection("cities").Document("DC").Delete().OnCompletion(
    [](const Future<void>& future) {
      if (future.error() == Error::kErrorOk) {
        std::cout << "DocumentSnapshot successfully deleted!" << std::endl;
      } else {
        std::cout << "Error deleting document: " << future.error_message()
                  << std::endl;
      }
    });
Node.js

از روش delete() استفاده کنید:

const res = await db.collection('cities').doc('DC').delete();
رفتن

از روش Delete() استفاده کنید:


import (
	"context"
	"log"

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

func deleteDoc(ctx context.Context, client *firestore.Client) error {
	_, err := client.Collection("cities").Doc("DC").Delete(ctx)
	if err != nil {
		// Handle any errors in an appropriate way, such as returning them.
		log.Printf("An error has occurred: %s", err)
	}

	return err
}
PHP

از روش delete() استفاده کنید:

$db->collection('samples/php/cities')->document('DC')->delete();
Unity

از روش DeleteAsync() استفاده کنید:

DocumentReference cityRef = db.Collection("cities").Document("DC");
cityRef.DeleteAsync();
سی شارپ

از روش DeleteAsync() استفاده کنید:

DocumentReference cityRef = db.Collection("cities").Document("DC");
await cityRef.DeleteAsync();
Ruby

از روش delete() استفاده کنید:

city_ref = firestore.doc "#{collection_path}/DC"
city_ref.delete

وقتی سندی را حذف می‌کنید، Cloud Firestore به‌طور خودکار اسناد موجود در زیرمجموعه‌های آن را حذف نمی‌کند. همچنان می‌توانید ازطریق ارجاع به اسناد زیرمجموعه دسترسی داشته باشید. برای مثال، می‌توانید به سند در مسیر /mycoll/mydoc/mysubcoll/mysubdoc دسترسی داشته باشید حتی اگر سند والد را در /mycoll/mydoc حذف کنید.

اسناد اصلی غیرموجود در کنسول ظاهر می‌شوند، اما در نتایج پُرسمان و عکس‌های آنی ظاهر نمی‌شوند.

اگر می‌خواهید سندی و همه اسناد موجود در زیرمجموعه‌های آن را حذف کنید، باید این کار را به‌صورت دستی انجام دهید. برای اطلاعات بیشتر، به حذف مجموعه‌ها مراجعه کنید.

حذف فیلدها

برای حذف فیلدهای خاص از سند، هنگام به‌روزرسانی سند از روش‌های FieldValue.delete() زیر که مختص زبان هستند استفاده کنید:

Web

از روش deleteField() استفاده کنید:

import { doc, updateDoc, deleteField } from "firebase/firestore";

const cityRef = doc(db, 'cities', 'BJ');

// Remove the 'capital' field from the document
await updateDoc(cityRef, {
    capital: deleteField()
});

Web

از روش FieldValue.delete() استفاده کنید:

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

// Remove the 'capital' field from the document
var removeCapital = cityRef.update({
    capital: firebase.firestore.FieldValue.delete()
});
Swift

از روش FieldValue.delete() استفاده کنید:

توجه: این محصول در watchOS و App Clip دردسترس نیست.
do {

  try await db.collection("cities").document("BJ").updateData([
    "capital": FieldValue.delete(),
  ])
  print("Document successfully updated")
} catch {
  print("Error updating document: \(error)")
}
Objective-C

از روش fieldValueForDelete: استفاده کنید:

توجه: این محصول در watchOS و App Clip دردسترس نیست.
[[[self.db collectionWithPath:@"cities"] documentWithPath:@"BJ"] updateData:@{
  @"capital": [FIRFieldValue fieldValueForDelete]
} completion:^(NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"Error updating document: %@", error);
  } else {
    NSLog(@"Document successfully updated");
  }
}];

Kotlin

از روش FieldValue.delete() استفاده کنید:

val docRef = db.collection("cities").document("BJ")

// Remove the 'capital' field from the document
val updates = hashMapOf<String, Any>(
    "capital" to FieldValue.delete(),
)

docRef.update(updates).addOnCompleteListener { }

Java

از روش FieldValue.delete() استفاده کنید:

DocumentReference docRef = db.collection("cities").document("BJ");

// Remove the 'capital' field from the document
Map<String,Object> updates = new HashMap<>();
updates.put("capital", FieldValue.delete());

docRef.update(updates).addOnCompleteListener(new OnCompleteListener<Void>() {
    // ...
    // ...

Dart

از روش FieldValue.delete() استفاده کنید:

final docRef = db.collection("cities").doc("BJ");

// Remove the 'capital' field from the document
final updates = <String, dynamic>{
  "capital": FieldValue.delete(),
};

docRef.update(updates);
جاوا

از روش FieldValue.delete() استفاده کنید:

DocumentReference docRef = db.collection("cities").document("BJ");
Map<String, Object> updates = new HashMap<>();
updates.put("capital", FieldValue.delete());
// Update and delete the "capital" field in the document
ApiFuture<WriteResult> writeResult = docRef.update(updates);
System.out.println("Update time : " + writeResult.get());
پایتون

از روش firestore.DELETE_FIELD استفاده کنید:

city_ref = db.collection("cities").document("BJ")
city_ref.update({"capital": firestore.DELETE_FIELD})

Python

از روش firestore.DELETE_FIELD استفاده کنید:

city_ref = db.collection("cities").document("BJ")
await city_ref.update({"capital": firestore.DELETE_FIELD})
C++‎

از روش FieldValue::Delete() استفاده کنید:

DocumentReference doc_ref = db->Collection("cities").Document("BJ");
doc_ref.Update({{"capital", FieldValue::Delete()}})
    .OnCompletion([](const Future<void>& future) { /*...*/ });
Node.js

از روش FieldValue.delete() استفاده کنید:

// Create a document reference
const cityRef = db.collection('cities').doc('BJ');

// Remove the 'capital' field from the document
const res = await cityRef.update({
  capital: FieldValue.delete()
});
رفتن

از روش firestore.Delete استفاده کنید:


import (
	"context"
	"log"

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

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

	// ...
	return err
}
PHP

از روش FieldValue::deleteField() استفاده کنید:

$cityRef = $db->collection('samples/php/cities')->document('BJ');
$cityRef->update([
    ['path' => 'capital', 'value' => FieldValue::deleteField()]
]);
Unity

از روش FieldValue.Delete استفاده کنید:

DocumentReference cityRef = db.Collection("cities").Document("BJ");
Dictionary<string, object> updates = new Dictionary<string, object>
{
    { "Capital", FieldValue.Delete }
};
سی شارپ

از روش FieldValue.Delete استفاده کنید:

DocumentReference cityRef = db.Collection("cities").Document("BJ");
Dictionary<string, object> updates = new Dictionary<string, object>
{
    { "Capital", FieldValue.Delete }
};
await cityRef.UpdateAsync(updates);
Ruby

از روش firestore.field_delete استفاده کنید:

city_ref = firestore.doc "#{collection_path}/BJ"
city_ref.update({ capital: firestore.field_delete })

حذف مجموعه‌ها

برای حذف کل مجموعه یا زیرمجموعه در Cloud Firestore، همه اسناد موجود در مجموعه یا زیرمجموعه را بازیابی (بخوانید) و آن‌ها را حذف کنید. این فرایند هم هزینه خواندن و هم هزینه حذف کردن دارد. اگر مجموعه‌های بزرگ‌تری دارید، شاید بهتر باشد اسناد را در دسته‌های کوچک‌تر حذف کنید تا از خطاهای کمبود حافظه جلوگیری شود. این فرایند را تکرار کنید تا کل مجموعه یا زیرمجموعه حذف شود.

حذف مجموعه مستلزم هماهنگی تعداد نامحدودی از درخواست‌های حذف فردی است. اگر لازم است کل مجموعه‌ها را حذف کنید، این کار را فقط از محیط سرور مطمئن انجام دهید. درحالی‌که امکان حذف مجموعه از کلاینت وب/تلفن همراه وجود دارد، انجام این کار پیامدهای منفی امنیتی و عملکردی دارد.

قطعه‌های زیر برای شفافیت ساده شده‌اند و شامل رسیدگی به خطا، امنیت، حذف زیرمجموعه‌ها، یا بهینه‌سازی عملکرد نمی‌شوند. برای آشنایی بیشتر با یکی از رویکردهای توصیه‌شده برای حذف مجموعه‌ها در تولید، به حذف مجموعه‌ها و زیرمجموعه‌ها مراجعه کنید.

وب
// Deleting collections from a Web client is not recommended.
Swift
توجه: این محصول در watchOS و App Clip دردسترس نیست.
// Deleting collections from an Apple client is not recommended.
Objective-C
توجه: این محصول در watchOS و App Clip دردسترس نیست.
// Deleting collections from an Apple client is not recommended.
  

Kotlin

// Deleting collections from an Android client is not recommended.

Java

// Deleting collections from an Android client is not recommended.

Dart

حذف مجموعه‌ها از کلاینت توصیه نمی‌شود.

جاوا

import com.google.api.core.ApiFuture;
import com.google.cloud.firestore.CollectionReference;
import com.google.cloud.firestore.Firestore;
import com.google.cloud.firestore.FirestoreOptions;

public class DeleteCollection {

  /**
   * Delete a collection and all its subcollections.
   *
   * @param projectId The Google Cloud project ID
   * @param collectionName The name of the collection to delete
   */
  public static void deleteCollection(String projectId, String collectionName) throws Exception {
    FirestoreOptions firestoreOptions =
        FirestoreOptions.getDefaultInstance().toBuilder().setProjectId(projectId).build();
    try (Firestore db = firestoreOptions.getService()) {
      CollectionReference collection = db.collection(collectionName);

      ApiFuture<Void> future = db.recursiveDelete(collection);

      future.get();
      System.out.println("Collection and all its subcollections deleted successfully.");
    }
  }

  public static void main(String[] args) throws Exception {
    String projectId = "example-project-id";
    String collectionName = "example-collection-name";

    deleteCollection(projectId, collectionName);
  }
}
پایتون
def delete_collection(coll_ref):

    print(f"Recursively deleting collection: {coll_ref}")
    db.recursive_delete(coll_ref)

Python

async def delete_collection(coll_ref):

    await db.recursive_delete(coll_ref)
C++‎
// This is not supported. Delete data using CLI as discussed below.
  
Node.js
async function deleteCollection(db, collectionPath) {
  const collectionRef = db.collection(collectionPath);
  return await db.recursiveDelete(collectionRef);
}
رفتن

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/firestore"
	"google.golang.org/api/iterator"
)

func deleteCollection(w io.Writer, projectID, collectionName string,
	batchSize int) error {

	// Instantiate a client
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, projectID)
	if err != nil {
		return err
	}

	col := client.Collection(collectionName)
	bulkwriter := client.BulkWriter(ctx)

	for {
		// Get a batch of documents
		iter := col.Limit(batchSize).Documents(ctx)
		numDeleted := 0

		// Iterate through the documents, adding
		// a delete operation for each one to the BulkWriter.
		for {
			doc, err := iter.Next()
			if err == iterator.Done {
				break
			}
			if err != nil {
				return err
			}

			bulkwriter.Delete(doc.Ref)
			numDeleted++
		}

		// If there are no documents to delete,
		// the process is over.
		if numDeleted == 0 {
			bulkwriter.End()
			break
		}

		bulkwriter.Flush()
	}
	fmt.Fprintf(w, "Deleted collection \"%s\"", collectionName)
	return nil
}
PHP
function data_delete_collection(string $projectId, string $collectionName, int $batchSize)
{
    // Create the Cloud Firestore client
    $db = new FirestoreClient([
        'projectId' => $projectId,
    ]);
    $collectionReference = $db->collection($collectionName);
    $documents = $collectionReference->limit($batchSize)->documents();
    while (!$documents->isEmpty()) {
        foreach ($documents as $document) {
            printf('Deleting document %s' . PHP_EOL, $document->id());
            $document->reference()->delete();
        }
        $documents = $collectionReference->limit($batchSize)->documents();
    }
}
Unity
// This is not supported. Delete data using CLI as discussed below.
سی شارپ
private static async Task DeleteCollection(CollectionReference collectionReference, int batchSize)
{
    QuerySnapshot snapshot = await collectionReference.Limit(batchSize).GetSnapshotAsync();
    IReadOnlyList<DocumentSnapshot> documents = snapshot.Documents;
    while (documents.Count > 0)
    {
        foreach (DocumentSnapshot document in documents)
        {
            Console.WriteLine("Deleting document {0}", document.Id);
            await document.Reference.DeleteAsync();
        }
        snapshot = await collectionReference.Limit(batchSize).GetSnapshotAsync();
        documents = snapshot.Documents;
    }
    Console.WriteLine("Finished deleting all documents from the collection.");
}
Ruby
cities_ref = firestore.col collection_path
query      = cities_ref

query.get do |document_snapshot|
  puts "Deleting document #{document_snapshot.document_id}."
  document_ref = document_snapshot.ref
  document_ref.delete
end

حذف داده‌ها با خط‌مشی‌های TTL

خط‌مشی TTL فیلد مشخصی را به‌عنوان زمان انقضای اسناد در گروه مجموعه مشخصی تعیین می‌کند. عملیات حذف TTL در هزینه‌های حذف سند شما لحاظ می‌شود.

برای اطلاعات بیشتر درباره تنظیم TTL، به مدیریت حفظ داده‌ها با خط‌مشی‌های TTL مراجعه کنید.

کارهای حذف انبوه

Cloud Firestore از چندین ابزار برای حذف انبوه پشتیبانی می‌کند. باید ابزاری را براساس تعداد اسنادی که باید حذف کنید و سطح پیکربندی موردنیازتان انتخاب کنید.

برای کارهای کوچک‌تر با هزاران سند، از کنسول یا واسط خط فرمان Firebase استفاده کنید. برای کارهای بزرگ‌تر، ممکن است این ابزارها با اتمام مهلت مواجه شوند و لازم باشد ابزار را چندین بار اجرا کنید.

کنسول

می‌توانید اسناد و مجموعه‌ها را از صفحه Cloud Firestore در کنسول حذف کنید. حذف سند از کنسول، همه داده‌های تودرتو در آن سند، ازجمله همه زیرمجموعه‌ها را حذف می‌کند.

واسط خط فرمان Firebase

همچنین می‌توانید از واسط خط فرمان Firebase برای حذف اسناد و مجموعه‌ها استفاده کنید. از فرمان زیر برای حذف داده‌ها استفاده کنید:

firebase firestore:delete  --database=DATABASE_ID PATH

DATABASE_ID را با شناسه پایگاه داده‌تان و PATH را با مسیر سند یا مجموعه جایگزین کنید.

برای کارهای حذف بزرگ (میلیون‌ها سند)، از یکی از موارد زیر استفاده کنید:

حذف انبوه مدیریت‌شده

Cloud Firestore از حذف انبوه یک یا چند گروه مجموعه پشتیبانی می‌کند. برای اطلاعات بیشتر، به حذف انبوه داده‌ها مراجعه کنید.

رابط Dataflow

می‌توانید از Dataflow برای عملیات انبوه در پایگاه داده‌تان استفاده کنید. این گزینه بیشترین قابلیت پیکربندی را دارد، اما نسبت‌به سایر گزینه‌های حذف انبوه به راه‌اندازی بیشتری نیاز دارد. Cloud Firestore connector for Dataflow introduction blog post has an example of deleting all documents in a collection group. را ببینید.