Deleting Data

Deleting data does not require performing explicit deleting actions like DELETE FROM table WHERE…. Instead you just need to clear any references to the object in your object-graph and store those changes. If a stored object is not reachable anymore its data will be deleted from the storage later. This behavior is comparable to Java’s garbage collector.

Basic Deletion

Remove the reference to the object and store the parent:

root.getMyArrayList().remove(0);
storage.store(root.getMyArrayList());

Deleting from Different Collection Types

Removing from a List

// Remove by index
root.getOrders().remove(0);
storage.store(root.getOrders());

// Remove by reference
root.getOrders().remove(order);
storage.store(root.getOrders());

// Remove with condition
root.getOrders().removeIf(o -> o.isCancelled());
storage.store(root.getOrders());

Removing from a Map

// Remove by key
root.getCustomerMap().remove(customerId);
storage.store(root.getCustomerMap());

// Remove entries matching a condition
root.getCustomerMap().entrySet().removeIf(
	e -> e.getValue().isInactive()
);
storage.store(root.getCustomerMap());

Removing from a Set

root.getTags().remove(tag);
storage.store(root.getTags());

Clearing an Entire Collection

root.getOrders().clear();
storage.store(root.getOrders());

Setting a Field to Null

If the object to delete is referenced by a single field rather than a collection:

root.setCurrentSession(null);
storage.store(root);

Bulk Deletion

When removing many objects, batch the removals and store once:

// Remove all inactive customers
List<Customer> inactive = root.getCustomers().stream()
	.filter(Customer::isInactive)
	.toList();

root.getCustomers().removeAll(inactive);
storage.store(root.getCustomers());

Important: Always Store the Parent

You must store the parent object that contains the reference, not the deleted object itself.

Incorrect (does nothing for deletion):

root.getOrders().remove(order);
storage.store(order); // Wrong! This stores the removed object, not the parent

Correct:

root.getOrders().remove(order);
storage.store(root.getOrders()); // Store the collection that changed

When Is Data Actually Erased?

Deleted data is not erased immediately from the storage files.

The erasing from the storage files is done by the housekeeping process. Housekeeping runs in the background and reclaims space from deleted (unreachable) objects during its garbage collection phase.

The timing depends on your housekeeping configuration:

Housekeeping interval — how often housekeeping runs
Time budget — how much time each housekeeping cycle is allowed to spend

Until housekeeping reclaims the space, the data remains in the storage files but is no longer accessible through the object graph.

Deleting with Lazy References

If the object to delete is behind a Lazy reference, you need to clear the lazy reference and store the parent.

Clearing a Lazy Field

public class DataRoot
{
	private Lazy<List<Order>> archive = Lazy.Reference(new ArrayList<>());

	public Lazy<List<Order>> getArchive()
	{
		return this.archive;
	}

	public void setArchive(Lazy<List<Order>> archive)
	{
		this.archive = archive;
	}
}

// Delete the archived data
Lazy.clear(root.getArchive()); (1)
root.setArchive(null);         (2)
storage.store(root);           (3)

1	Clear the lazy reference to free the loaded data from memory. The static `Lazy.clear()` is null-safe — unlike calling `.clear()` on the instance directly, it does not throw a `NullPointerException` if the reference is `null`.
2	Set the field to `null` to remove the reference from the object graph
3	Store the parent so the change is persisted

Removing from a Collection of Lazy References

public class DataRoot
{
	private final Map<String, Lazy<Customer>> customers = new HashMap<>();
}

// Remove a single customer
Lazy<Customer> removed = root.getCustomers().remove(customerId);
Lazy.clear(removed);
storage.store(root.getCustomers());