Skip to main content

​
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