Set-ZrItemExpiration
Applies a new time-to-live to an existing Clustron Zaris item, measured from now. Fails if the key does not exist.
Syntax
Set-ZrItemExpiration [-Key] <string> [-TimeToLive] <TimeSpan> [-ConnectionString <string>] [-StoreName <string>] [-Endpoints <string[]>] [-TimeoutSec <int>] [-WhatIf] [-Confirm]
Description
Set-ZrItemExpiration changes an item's expiry. It reads the current value of -Key, then rewrites it with the supplied -TimeToLive (Put.WithTtl), so the new TTL is measured from the moment the command runs. Unlike Refresh-ZrItem.md, which reuses the item's existing TTL, this command sets an explicit new duration.
If the key does not exist, the command reports Success = false with Error = "Key does not exist" rather than creating a new item. The cmdlet supports ShouldProcess, so -WhatIf previews the change and -Confirm prompts before applying it.
The command runs against the active Connect-ZrStore session, or against a one-shot connection when -StoreName and -Endpoints are supplied.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
-Key | String | Yes | Key identifying the item whose expiration is updated. Positional (position 0). Must not be null or empty. |
-TimeToLive | TimeSpan | Yes | New time-to-live to apply, measured from now. Positional (position 1). |
-ConnectionString | String | No | Connect via a Zaris connection string, e.g. zaris://host:7861/store; an alternative to -StoreName + -Endpoints for a one-shot connection. Ignored when a Connect-ZrStore session is active. |
-StoreName | String | No | Store to target when using an independent (one-shot) connection instead of the active session. Requires -Endpoints. |
-Endpoints | String[] | No | One or more node endpoints (host:port) for an independent connection. Ignored when a Connect-ZrStore session is active. |
-TimeoutSec | Int32 | No | Connection timeout in seconds (1–120) for an independent connection. Default 5. |
-WhatIf | Switch | No | Shows what would happen without applying the new expiration. |
-Confirm | Switch | No | Prompts for confirmation before applying the new expiration. |
Examples
Set a session item to expire 30 minutes from now:
Set-ZrItemExpiration -Key "session:abc123" -TimeToLive (New-TimeSpan -Minutes 30)
Expire a cache item in 60 seconds using positional arguments:
Set-ZrItemExpiration "cache:product:100" (New-TimeSpan -Seconds 60)
Preview the change without applying it:
Set-ZrItemExpiration -Key "session:abc123" -TimeToLive (New-TimeSpan -Minutes 10) -WhatIf