Remove Collection

Delete an entire collection from the database, including its structure.

Overview

The removeCollection operation is a structural and destructive operation. Unlike operations such as clear or clearAdd, which remove or replace items, this command deletes the collection itself.

Warning

This operation cannot be undone.

Use this command only for administrative database maintenance, such as:

• Dropping obsolete collections

• Restructuring schema designs

• Resetting the database before migration

It is not intended for normal application flow and should not be used as part of regular insert/update/delete operations.

Characteristics

• The entire collection is deleted.

• The operation cannot be included inside a transaction query.

• No UI listeners or callbacks will be triggered.

• If mustAffectAtLeastOne is enabled, the query fails when the target does not exist.

• Use only when database structure changes are required.

Usage

Dart

import 'package:delta_trace_db/delta_trace_db.dart';

void main() {
  final db = DeltaTraceDatabase();

  // Insert temporary data
  final q1 = RawQueryBuilder.add(
    target: "user",
    rawAddData: [
      {"id": -1, "name": "a"},
      {"id": -1, "name": "b"},
    ],
    serialKey: "id",
    returnData: true,
  ).build();
  final r1 = db.executeQuery(q1);

  // Remove entire collection
  final q2 = RawQueryBuilder.removeCollection(target: "user").build();
  final r2 = db.executeQuery(q2);

  print(r1.toDict());
  print(r2.toDict());
}

Python

from delta_trace_db import DeltaTraceDatabase, RawQueryBuilder

db = DeltaTraceDatabase()

# Insert temporary data
q1 = (
    RawQueryBuilder.add(
        target="user",
        raw_add_data=[
            {"id": -1, "name": "a"},
            {"id": -1, "name": "b"},
        ],
        serial_key="id",
        return_data=True
    )
    .build()
)

r1 = db.execute_query(q1)

# Remove entire collection
q2 = RawQueryBuilder.remove_collection(
    target="user",
).build()

r2 = db.execute_query(q2)

print(r1.to_dict())
print(r2.to_dict())

Result

The result is returned as a QueryResult.

Example output:

// r1
{className: QueryResult, version: 6, isSuccess: true, target: user, type: add,
result: [
    {id: 0, name: a}, {id: 1, name: b}
], dbLength: 2, updateCount: 2, hitCount: 0, errorMessage: null}

// r2
{className: QueryResult, version: 6, isSuccess: true, target: user, type: removeCollection,
result: [], dbLength: 0, updateCount: 1, hitCount: 0, errorMessage: null}

API

• Dart: [QueryBuilder.removeCollection]

• Dart(RawData): [RawQueryBuilder.removeCollection]

• Python: [QueryBuilder.remove_collection]

• Python(RawData): [RawQueryBuilder.remove_collection]

Notes

• This operation deletes the collection itself, not just its items. Because of this, it cannot be included in a transaction query.

• UI listeners registered via db.addListener(target, ...) will not be called.

• It is recommended to design the database schema so that removeCollection does not need to be used during normal application runtime.

• Set mustAffectAtLeastOne = true only when ensuring the target must exist.

• cause can be used to store metadata for logging, auditing, or AI-explainability.