Knowledge Objects in actions

Actions can read and write Knowledge Object instances through the KnowledgeObject client, exposed by the action SDK. It calls the same governed instance operations as the REST API — validation, options, filters, and versioning all apply — and runs as the action’s user, on the action’s project.

from datazone.actions import KnowledgeObject

employee = KnowledgeObject("Employee").get(key="8A3F9C2E1B4D6F7A8A3F9C2E1B4D6F7A")
print(employee["email"])

Instances are addressed by their opaque _key (returned by get, list, and create). Operations run on the main branch by default; pass branch= to target another branch.

Constructing a client

KnowledgeObject(name, branch=None)

name — the object’s name (e.g. "Employee").
branch — (optional) branch to read/write on. Defaults to the project’s main branch.

employees = KnowledgeObject("Employee")                 # main
employees = KnowledgeObject("Employee", branch="dev")   # a feature branch

Methods

get

get(key, add_relationships=False) -> dict

Fetch a single instance by its _key. Pass add_relationships=True to also resolve the object’s relationship fields (one level deep) under an _relationships key.

employee = KnowledgeObject("Employee").get(key="8A3F...")
company = KnowledgeObject("Company").get(key="AB12...", add_relationships=True)
print(company["_relationships"]["owner"])   # resolved related instance

list

list(filters=None, page=1, page_size=50, fields=None) -> iterator of pages

Returns an iterator over pages; each page exposes .items (a list of instance dicts) and .total_count. Pages are fetched lazily as you iterate.

filters — a list of {"column", "operator", "value"} objects, combined with AND. Operators: equal, not_equal, contains, not_contains, greater_than, less_than.
fields — restrict the columns returned (the meta fields _key and _version are always included).

employees = KnowledgeObject("Employee")

for page in employees.list(
    filters=[
        {"column": "gender", "operator": "equal", "value": "female"},
        {"column": "age", "operator": "greater_than", "value": 30},
    ],
    fields=["name", "email"],
):
    for employee in page.items:
        print(employee["name"], employee["email"])

update

update(key, payload) -> dict

Partially update an instance by its _key; returns the full updated instance. Primary key fields cannot be changed.

KnowledgeObject("Employee").update(key="8A3F...", payload={"email": "new@acme.com"})

delete

delete(key) -> None

Delete an instance by its _key.

KnowledgeObject("Employee").delete(key="8A3F...")

batch_upsert

batch_upsert(payloads) -> dict

Insert or update up to 1000 instances in one call. A payload whose primary key does not exist is inserted; one that already exists is updated (a new version). Returns a summary.

result = KnowledgeObject("Employee").batch_upsert([
    {"id": 1, "name": "John", "email": "john@acme.com"},
    {"id": 2, "name": "Jane", "email": "jane@acme.com"},
])
# result -> {"created": 1, "updated": 1, "total": 2}

Full example

from datazone.actions import action, context, KnowledgeObject

@action
def deactivate_inactive_employees():
    """Mark all active employees as inactive."""
    employees = KnowledgeObject("Employee")
    updated = 0

    for page in employees.list(
        filters=[{"column": "is_active", "operator": "equal", "value": True}]
    ):
        for employee in page.items:
            context.log_info(f"Deactivating {employee['name']}")
            employees.update(key=employee["_key"], payload={"is_active": False})
            updated += 1

    return {"updated": updated}

Next steps

Actions — writing and deploying actions.
Instance API — the REST equivalent of these operations.
YAML Reference — defining objects and their fields.

Get Started

Reference

Deployment

Tutorial

Actions SDK

Knowledge Objects in actions

Constructing a client

Methods

get

list

update

delete

batch_upsert

Full example

Next steps

​Knowledge Objects in actions

​Constructing a client

​Methods

​get

​list

​update

​delete

​batch_upsert

​Full example

​Next steps

Knowledge Objects in actions

Constructing a client

Methods

get

list

update

delete

batch_upsert

Full example

Next steps