Clear & ClearAdd

clear removes all items in the collection, and clearAdd adds new data after clear.

Overview

The clear and clearAdd operations are destructive operations:

  • clear removes all items in the specified collection.

  • clearAdd removes all items and then inserts new data.

These operations are typically used when resetting a dataset, importing data, or ensuring that a collection matches a known set of items.

Warning

These operations permanently delete data in the target collection.

It is strongly recommended to back up your DB before executing.

Be especially cautious in production or when multiple agents share the same database.

Usage

import 'package:delta_trace_db/delta_trace_db.dart';

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

  // Clear the "users" collection
  final clearQuery = RawQueryBuilder.clear(
    target: 'users',
    resetSerial: true, // Optional: reset auto-increment serial
    mustAffectAtLeastOne:
    false, // Should be false if you might be adding to an empty DB.
  ).build();

  final result = db.executeQuery(clearQuery);
  print(result.toDict()); // {isSuccess: true, ...}
}

import 'package:delta_trace_db/delta_trace_db.dart';

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

  // Replace entire collection with new data
  final clearAddQuery = RawQueryBuilder.clearAdd(
    target: 'users',
    rawAddData: [
      {'id': -1, 'name': 'Taro'},
      {'id': -1, 'name': 'Hanako'},
    ],
    serialKey: 'id',   // Assign unique sequential IDs
    resetSerial: true, // Reset ID counter before assigning
    returnData: true,  // Return newly inserted objects
    mustAffectAtLeastOne: false, // Should be false if you might be adding to an empty DB.
  ).build();

  final result = db.executeQuery(clearAddQuery);
  print(result.toDict());
}

from delta_trace_db import DeltaTraceDatabase, RawQueryBuilder

db = DeltaTraceDatabase()

# Clear the "users" collection
clear_query = RawQueryBuilder.clear(
    target="users",
    reset_serial=True,  # Optional: reset auto-increment serial
    must_affect_at_least_one=False
).build()

result = db.execute_query(clear_query)
print(result.to_dict())  # {"is_success": True, ...}

from delta_trace_db import DeltaTraceDatabase, RawQueryBuilder

db = DeltaTraceDatabase()

# Replace entire collection with new data
clear_add_query = RawQueryBuilder.clear_add(
    target="users",
    raw_add_data=[
        {"id": -1, "name": "Taro"},
        {"id": -1, "name": "Hanako"},
    ],
    serial_key="id",                # Assign unique sequential IDs
    reset_serial=True,              # Reset ID counter before assigning
    return_data=True,               # Return newly inserted objects
    must_affect_at_least_one=False, # False if adding to an empty DB
).build()

result = db.execute_query(clear_add_query)
print(result.to_dict())

Result

Both operations return a QueryResult.

Example output (clearAdd):

{className: QueryResult, version: 6, isSuccess: true, target: users, type: clearAdd,
result: [
    {id: 0, name: Taro},
    {id: 1, name: Hanako}
], dbLength: 2, updateCount: 0, hitCount: 0, errorMessage: null}

API

Notes

  • When using DeltaTraceDatabase in Flutter front-end applications, clearAdd can be especially useful for state management.

    If a UI listener is registered using db.addListener(target, ...), then calling clearAdd will trigger that listener, allowing the UI to automatically update when the underlying data changes.

    This means that the database itself can act as a state management framework.

    See DB Listeners for implementation details.

  • serialKey assigns unique integer IDs to inserted items.

  • resetSerial resets the internal counter used for serialKey.

  • mustAffectAtLeastOne can enforce that the operation must change data. If true and no items are affected, the query will be marked as failed.

  • cause can store metadata useful for logging, auditing, or AI agent explainability.