Skip to main content

Clear operations

Clear operations remove many keys in one call: the whole store, a prefix, or a key range. This article shows you how to run each kind of clear, preview a clear before it runs, and read the report it returns.

Use a clear instead of deleting keys one by one when you want to reset state or remove a whole group of related keys. A clear runs on the server rather than round-tripping each key.

The ClearRequest and ClearReport types used below live in the Clustron.Zaris.Abstractions namespace. Add using Clustron.Zaris.Abstractions; next to the using Clustron.Zaris.Client; from your client bootstrap.

Clear the whole store​

Call the parameterless ClearAsync to remove every key in the store. It returns a KvResult<ClearReport>.

var result = await client.ClearAsync();

if (result.IsSuccess)
{
    Console.WriteLine($"Deleted {result.Value.DeletedCount} keys.");
}
warning

A full clear deletes all data in the store and cannot be undone. Confirm you are pointed at the store you intend before you call it, especially against a shared or production cluster.

Clear by prefix​

To remove only the keys that share a prefix, pass a ClearRequest with its Prefix set. This is the common way to clear one logical group, such as every key under user:.

var result = await client.ClearAsync(new ClearRequest(Prefix: "user:"));

Given keys user:1, user:2, and user:3, this removes all three while leaving keys with other prefixes untouched. Choose prefixes deliberately: a short prefix such as u matches more keys than you might expect.

Clear by range​

To remove keys that fall within a range, set StartKey and EndKey on the request. Keys are ordered lexicographically, so the range covers every key from the start key up to the end key.

var result = await client.ClearAsync(new ClearRequest(
    StartKey: "user:1",
    EndKey: "user:100"));

Preview with a dry run​

Set DryRun to true to find out how many keys a clear would affect without deleting anything. On a dry run the clear inspects the matching keys but removes none: DeletedCount stays 0, and Examined reports how many keys matched the prefix or range. Read the would-be-removed count from Examined, not DeletedCount.

var preview = await client.ClearAsync(new ClearRequest(Prefix: "user:", DryRun: true));

Console.WriteLine($"Would delete {preview.Value.Examined} keys.");

Read the report​

A successful clear returns a ClearReport in result.Value. Its fields describe what the operation did.

FieldTypeDescription
DeletedCountintThe number of keys actually removed. On a dry run this is always 0; read Examined to see how many keys matched.
ExaminedintThe number of keys inspected while matching the prefix or range. On a dry run, this is how many keys the clear would remove.
Completedbooltrue when the clear finished.
NextResumeTokenstring?Informational marker for where a clear stopped. There is no way to feed it back into a request.

ClearRequest exposes only Prefix, StartKey, EndKey, and DryRun — there is no field to pass NextResumeToken back in, so the token is informational rather than a resume cursor you supply. A clear scans all matching keys internally in batches, so if a clear is interrupted before it finishes, you finish it by re-running the same ClearAsync call: it re-scans the scope and removes whatever remains. Re-running is safe because a delete of an already-removed key is a no-op.

When to use a clear​

Clears fit these situations:

  • Resetting application or session state.
  • Removing temporary or expired-group data by prefix.
  • Cleaning up test data between runs.

Note that clear operations are not transactional. Like bulk and batch operations, they can remove a subset of matched keys if interrupted; the report's Completed flag tells you whether the operation finished.

Next steps​

  • Clear-ZrStore — clear the whole store from the PowerShell CLI.