> ## 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.

# Overview

> Define business entities as versioned objects and manage their instances through a governed API

# Knowledge Objects

Knowledge Objects let you model the business entities of your domain — `Employee`, `Invoice`, `Company`, `Ticket` — as declarative YAML definitions in your project repository. On deploy, Datazone stores each definition as metadata and materializes a ClickHouse table behind it. Every row in that table is an **instance**, created, read, updated, and deleted through a governed REST API.

Unlike an Extract (which ingests data from an external source) or a Pipeline (which transforms datasets), a Knowledge Object is a **first-class, hand-curated entity**: its schema is versioned in Git, its instances are edited by users or agents, and every change is tracked.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/datazone/images/light/knowledge-objects/knowledge-object-example.png" alt="Knowledge Object Example" />
</Frame>

## What you get

* **Declarative schema** — fields, types, primary keys, defaults, and relationships defined in YAML and validated on deploy.
* **A materialized table + view** — each object is backed by a ClickHouse table you can query in the SQL editor and join with the rest of your data.
* **A CRUD API** — list, create, read, update, and delete instances, with pagination, column selection, and filtering.
* **Versioning** — every write appends a new version; the API always serves the latest, and full history is available.
* **Relationships** — a field can point at another object's instance, resolved on demand.
* **Branch awareness** — objects live in your repository, so they follow the same branch model as the rest of your project.

## How it works

An object is a YAML file in your repository, registered in `config.yaml`, exactly like a pipeline or an endpoint:

1. Create a YAML file under `objects/` (e.g. `objects/employee.yaml`) defining the object.
2. Register the file in your project's `config.yaml`.
3. Deploy. Datazone parses the definition, stores it, and enqueues a migration that builds the ClickHouse table and view.
4. Once the migration completes, the object becomes `READY` and its instance API is live.

```yaml objects/employee.yaml theme={null}
name: Employee
description: A person employed by the company.

fields:
  - name: id
    type: int
    primary_key: true
  - name: name
    type: str
  - name: email
    type: str
    optional: true
  - name: hired_at
    type: datetime
    default: now()

settings:
  icon: users
  label_column: name
```

<Note>
  You can also create an object directly from the UI (or the `POST /knowledge-object/create` endpoint). Datazone writes the YAML file, registers it in `config.yaml`, and deploys it for you — the object is still materialized by the same loader, so the outcome is identical to committing the file yourself.
</Note>

## Core concepts

### Object vs. Definition

A Knowledge Object is **one identity per (project, object name)** — its id is stable no matter which branch you are on. Deploying the object to a branch produces a **definition** for that branch, and each definition carries its own schema, migration status, and ClickHouse table/view.

```
KnowledgeObject "Employee"   (stable id, shared across branches)
 ├── definition @ main        → READY,    table object_main_employee
 └── definition @ feature-x   → PENDING,  table object_feature_x_employee
```

This means you can evolve an object's schema on a feature branch — add a field, change a default — and try it in isolation before merging to `main`. See [Branching](#branching) below.

### Instances and the instance key

Each row is an **instance**, addressed by an opaque **instance key** (`_key`): a hex string derived server-side from the instance's primary key values. The key is stable across updates — the same primary key values always map to the same `_key`, so an instance keeps its URL for life.

### Versioning

Updates and deletes never modify a row in place; they append a new version. The API always serves the latest non-deleted version, so you can treat instances as plain mutable records — while still being able to read the full [history](/reference/knowledge-objects/api#instance-history) of any instance.

## Branching

Because objects are stored in your repository, they follow your project's branch model end to end:

* The **object identity** (and its id) is shared across branches.
* Each **branch has its own definition** — schema, status, and a dedicated ClickHouse table (`object_<branch>_<name>`), so instance data is isolated per branch.
* Every API call takes an optional **`branch` query parameter, defaulting to `main`**. The object id in the URL never changes when you switch branches — only the `branch` param does.
* Object responses include a **`branches`** array listing every branch the object is deployed on, which powers the branch switcher in the UI.
* If an object is not deployed on the requested branch, object reads return `definition: null` and instance calls return `404`.

<Info>
  Working on a feature branch is the safe way to change an object's schema. Deploy the change to your branch, verify the migration and instances there, then merge to `main`.
</Info>

## Next steps

* [YAML Reference](/reference/knowledge-objects/yaml-reference) — every attribute you can declare on an object.
* [Instance API](/reference/knowledge-objects/api) — the full REST API for managing objects and their instances.
* [Actions SDK](/reference/knowledge-objects/actions-sdk) — read and write instances from within an [action](/reference/development/actions).