Set-ZrItem
Writes or updates a single item in the connected Zaris store, creating the item or overwriting an existing one and returning its new revision and version. An optional TTL or lease binding controls automatic expiry.
Syntax
Set-ZrItem [-Key] <string> [-Value] <object> [-ExpireAfterSec <int>] [-LeaseId <LeaseId>]
[-ConnectionString <string>] [-StoreName <string>] [-Endpoints <string[]>] [-TimeoutSec <int>]
[-WhatIf] [-Confirm]
Description
Set-ZrItem stores the given value under the specified key. It requires an active connection opened with Connect-ZrStore, or the independent -StoreName/-Endpoints parameters for a one-shot connection.
-ExpireAfterSec and -LeaseId are mutually exclusive — supplying both is an error. -ExpireAfterSec sets a fixed time-to-live; -LeaseId binds the item to a lease so it expires when that lease ends. The cmdlet supports ShouldProcess, so -WhatIf and -Confirm are available. Press Ctrl+C to cancel safely.
The returned object has StoreName, Key, IsUpdate, Revision, Version, TimeToLiveSec, LeaseId, Success, and Error.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
-Key | String | Yes | The key under which the value is stored. Position 0. Must be non-null and non-empty. |
-Value | Object | Yes | The value to store. Position 1. Must be non-null; any serializable object supported by the client. |
-ExpireAfterSec | Int32 | No | Time-to-live in seconds, after which the item expires. Range 1 to Int32.MaxValue. Cannot be combined with -LeaseId. |
-LeaseId | LeaseId | No | A lease to bind the item to, so it expires when the lease ends. Cannot be combined with -ExpireAfterSec. |
-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 operate on for a one-shot (independent) connection instead of the active session. Requires -Endpoints; ignored when a Connect-ZrStore session is active. |
-Endpoints | String[] | No | One or more host:port endpoints for a one-shot connection. Ignored when a session is active. |
-TimeoutSec | Int32 | No | Connection timeout in seconds for a one-shot connection. Range 1–120. Default 5. |
Supports the -WhatIf and -Confirm common parameters via ShouldProcess.
Examples
Store a value under a key:
Set-ZrItem -Key "order:1001" -Value "created"
Store a value with a one-hour time-to-live:
Set-ZrItem -Key "user:42" -Value $profile -ExpireAfterSec 3600
Bind an item to a lease so it expires when the lease ends:
Set-ZrItem -Key "leader" -Value "node1" -LeaseId $lease