Key-Value document store

Key-Value document store

The KV sub-client provides access to the IYREE Key-Value store. Store, retrieve, update, and delete JSON documents organized by variables (namespaces).

from iyree import IyreeClient

with IyreeClient(api_key="my-key") as client:
    client.kv.put("config", {"theme": "dark"}, key="user_prefs")
    doc = client.kv.get("config", "user_prefs")
    print(doc.data)  # {"theme": "dark"}

---

Methods

get

Retrieve a document by key.

doc = client.kv.get("config", "user_prefs")
print(doc.data)
print(doc.created_at)

Parameters

variable · str · required

KV store variable (namespace).

key · str · required

Document key.

Returns KvDocument

key · str

Document key.

data · Any

Arbitrary document payload (typically a dict).

created_at · datetime

Creation timestamp.

updated_at · datetime

Last modification timestamp.

expires_at · datetime

Expiry timestamp, or None if the document does not expire.

Errors

Exception	Condition
IyreeNotFoundError	Document does not exist

---

put

Create or update a document. Returns the document key.

key = client.kv.put("config", {"theme": "dark"}, key="user_prefs")
print(key)  # "user_prefs"

Parameters

variable · str · required

KV store variable (namespace).

data · Any · required

Document payload. Any JSON-serializable value.

key · str

Document key. If None, the server auto-generates a key.

indexes · Dict[str, Any]

Optional index fields for querying documents.

indexes={"user_id": 42, "region": "US"}

ttl · int

Time-to-live in seconds. The document expires after this duration.

upsert · bool · default: "True"

If True (default), overwrite an existing document with the same key. If False, the request fails when the key already exists.

Returns str

The document key (same as key if provided, or the auto-generated key).

---

delete

Delete a document by key.

deleted = client.kv.delete("config", "user_prefs")
print(deleted)  # True

Parameters

variable · str · required

KV store variable (namespace).

key · str · required

Document key.

Returns bool

Always True after a successful deletion.

---

exists

Check whether a document exists. Does not raise on 404 — returns False instead.

if client.kv.exists("config", "user_prefs"):
    doc = client.kv.get("config", "user_prefs")

Parameters

variable · str · required

KV store variable (namespace).

key · str · required

Document key.

Returns bool

True if the document exists, False otherwise.

---

patch

Partially update a document. Supports setting, unsetting, and incrementing fields.

updated = client.kv.patch(
    "config", "user_prefs",
    set={"theme": "light", "language": "en"},
    inc={"login_count": 1},
)
print(updated.data)

Parameters

variable · str · required

KV store variable (namespace).

key · str · required

Document key.

set · Dict[str, Any]

Fields to set or overwrite.

set={"theme": "light", "language": "en"}

unset · List[str]

Field names to remove from the document.

unset=["deprecated_field", "temp_flag"]

inc · Dict[str, Any]

Fields to increment by a numeric value.

inc={"view_count": 1, "score": 10}

indexes · Dict[str, Any]

Index fields to update.

Returns KvDocument

The updated document.

---

list

List documents with optional filtering, ordering, and cursor-based pagination. Filter on secondary indexes using where conditions.

page = client.kv.list(
    "users",
    where=[{"index_name": "role", "value": "admin"}],
    order_by={"field": "created_at", "direction": "desc"},
    limit=50,
)
for doc in page.items:
    print(doc.key, doc.data)

Parameters

variable · str · required

KV store variable (namespace).

where · List[Dict[str, Any]]

Filter conditions on secondary indexes. Each dict should contain:

Show Where condition structure

index_name · str · required

Name of the secondary index to filter on.

value · Any · required

Value to compare against. datetime objects are automatically converted to ISO-8601 strings.

op · str · default: "\"eq\""

Comparison operator: eq, gt, gte, lt, lte, or between.

value_to · Any

Upper bound for between operator. datetime objects are automatically converted to ISO-8601 strings.

where=[
    {"index_name": "region", "value": "US"},
    {"index_name": "score", "value": 50, "op": "gte"},
    {"index_name": "created", "value": "2024-01-01", "op": "between", "value_to": "2024-12-31"},
]

order_by · Dict[str, str]

Sort directive.

Show Order by structure

field · str · required

Field to sort by: updated_at or created_at.

direction · str · required

Sort direction: asc or desc.

order_by={"field": "updated_at", "direction": "desc"}

limit · int · default: "100"

Maximum documents per page (1–1000).

cursor · str

Opaque cursor from a previous page for pagination. Use page.cursor from the previous result.

select · List[str]

Subset of top-level data keys to return. When specified, only these fields are included in doc.data.

select=["name", "email"]

Returns KvListResult

items · List[KvDocument]

Documents in this page.

cursor · str

Opaque cursor for the next page, or None if this is the last page.

has_more · bool

Whether more pages are available.

---

list_iter

Auto-paginating iterator over all documents matching the query. Handles cursor pagination automatically.

for doc in client.kv.list_iter("users", where=[{"index_name": "role", "value": "admin"}]):
    print(doc.key, doc.data)

Parameters

variable · str · required

KV store variable (namespace).

where · List[Dict[str, Any]]

Filter conditions on secondary indexes (same structure as list).

order_by · Dict[str, str]

Sort directive (same structure as list).

limit · int · default: "100"

Maximum documents per page (controls internal page size).

select · List[str]

Subset of top-level data keys to return.

Yields KvDocument

Yields individual KvDocument instances across all pages.

---

bulk_get

Fetch multiple documents by keys in a single request.

docs = client.kv.bulk_get("users", ["alice", "bob", "charlie"])
for key, doc in docs.items():
    print(key, doc.data)

Parameters

variable · str · required

KV store variable (namespace).

keys · List[str] · required

Document keys to fetch.

Returns Dict[str, KvDocument]

A dict mapping each found key to its KvDocument. Keys that do not exist are omitted from the result.

---

bulk_put

Create or upsert multiple documents in a single request.

keys = client.kv.bulk_put("users", [
    {"key": "alice", "data": {"name": "Alice", "role": "admin"}},
    {"key": "bob", "data": {"name": "Bob", "role": "user"}, "ttl": 86400},
    {"data": {"name": "Charlie"}},  # auto-generated key
])
print(keys)  # ["alice", "bob", "<auto-generated>"]

Parameters

variable · str · required

KV store variable (namespace).

items · List[Dict[str, Any]] · required

List of document dicts. Each dict must contain at minimum a data key.

Show Item structure

data · Any · required

Document payload.

key · str

Document key. Auto-generated if omitted.

indexes · Dict[str, Any]

Index fields. datetime objects are automatically converted to ISO-8601 strings.

ttl · int

Time-to-live in seconds.

upsert · bool · default: "True"

If True (default), overwrite existing documents with the same key.

Returns List[str]

List of document keys in the same order as the input items.

---

Examples

CRUD operations

from iyree import IyreeClient

with IyreeClient(api_key="my-key") as client:
    # Create
    key = client.kv.put("users", {"name": "Alice", "role": "admin"}, key="alice")

    # Read
    doc = client.kv.get("users", "alice")
    print(doc.data)  # {"name": "Alice", "role": "admin"}

    # Update
    updated = client.kv.patch("users", "alice", set={"role": "superadmin"})
    print(updated.data["role"])  # "superadmin"

    # Delete
    client.kv.delete("users", "alice")