> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datazone.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Actions SDK

> Read and write Knowledge Object instances from within an action.

# Knowledge Objects in actions

[Actions](/reference/development/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](/reference/knowledge-objects/api) — validation, options, filters, and versioning all apply — and runs as the action's user, on the action's project.

```python theme={null}
from datazone.actions import KnowledgeObject

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

<Note>
  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.
</Note>

## Constructing a client

```python theme={null}
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.

```python theme={null}
employees = KnowledgeObject("Employee")                 # main
employees = KnowledgeObject("Employee", branch="dev")   # a feature branch
```

## Methods

### get

```python theme={null}
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.

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

### list

```python theme={null}
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).

```python theme={null}
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

```python theme={null}
update(key, payload) -> dict
```

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

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

### delete

```python theme={null}
delete(key) -> None
```

Delete an instance by its `_key`.

```python theme={null}
KnowledgeObject("Employee").delete(key="8A3F...")
```

### batch\_upsert

```python theme={null}
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.

```python theme={null}
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

```python theme={null}
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](/reference/development/actions) — writing and deploying actions.
* [Instance API](/reference/knowledge-objects/api) — the REST equivalent of these operations.
* [YAML Reference](/reference/knowledge-objects/yaml-reference) — defining objects and their fields.