This function registers a request to permanently delete histories that match a filter and have not been updated since a given time. Deletion does not happen during the call: the call registers the request (in a digest), and the work is carried out afterwards by a background task -
A purge is defined by three things: which histories it targets (
1. Finds or creates a digest that accumulates the targeted histories
2. Records the latest event id
3. Links the purge to the relevant digest
Everything after that - populating the digest, flagging histories as purgeable, deleting them, and eventually retiring the digest, happens in
Parameters
| Name | Type | Description |
|---|---|---|
| name | String, optional | The name of the purge. May only contain alphanumeric characters and underscores. May not be "shared". If omitted, the purge joins a shared pool and the name becomes "shared". The name determines which digests this purge is allowed to reuse |
| filter | Object, required | A history filter object. Only histories matching this filter will be considered for this purge. The filter can only access top level history properties (ie it cannot access subject or event values). At least one direct positive comparison on a label (labela..labele) or on id. A filter that only excludes values, for example NOT(EQ(labela, X)), does not count as constraining and is rejected |
| eventFilter | Object, optional | A history filter object. A history is included only if it has at least one event matching this filter; a history with no matching event never gets a digest row and is therefore never purged |
| before | Integer <epoch milliseconds>, required | Histories older than this are eligible for deletion. Age is taken from the digest's |
Returns
| Property | Type | Description |
|---|---|---|
| purgeId | Integer | Id of the new WkHistoryPurge row |
| purgeName | String | The purge name used, lower-cased. "shared" if name was omitted |
| digestName | String | Name of the digest backing this purge |
| digestCreated | Boolean | True if a new digest was created, false if an existing one was reused |
How it Works
A purge is driven by a digest holding one row per targeted history with two fixed columns:
- lasttimestamp - the timestamp of the last event in the history, of any kind
- purgeable - a placeholder column used by the purge process itself
The call looks for a digest already registered under the same purge name, whose
Digests are only ever reused from those registered under the same purge name. A digest belonging to a different purge name is never adopted, however well its filters match.
Calls that omit name all share the "shared" pool, so unnamed purges can reuse each other's digests.
Registering the purge
Repeated calls with the same name and the same filters reuse the digest but each gets its own WkHistoryPurge row, and therefore its own "before" cutoff. Calls with the same name but different filters get a newly created digest, still under the same purge name.
Populating the digest
You don't have to call
Deleting
Deletion runs as its own reserved job in the digest queue. It deletes flagged histories in batches across every purge digest, and stops when there is nothing left to delete, or when the run is close enough to its time limit that another batch would overrun it.
Retiring
A purge digest is retired once all of the following are true:
- every purge referencing it has reached its PurgeAtEventID
- no history in it is still flagged purgeable
- no new purge has been registered against it for the configured grace period
