Knowledge Object YAML Reference

This page documents every attribute available in a Knowledge Object YAML definition. Each file declares one object per YAML document; you can define multiple objects in one file by separating them with ---.

Top-level structure

name: string            # Object name, unique per project (required)
description: string     # (Optional) Human-readable description
fields:                 # Field definitions (required, at least one)
settings:               # (Optional) Object settings
actions:                # (Optional) Action definitions

A minimal object needs a name and at least one field, and at least one of those fields must be a primary key:

name: Tag
fields:
  - name: slug
    type: str
    primary_key: true
  - name: label
    type: str

`fields`

The list of columns that make up the object. Every field is validated on deploy; an unknown attribute or an unsupported type fails the deploy.

Attribute	Type	Default	Description
`name`	string	—	Field name (required).
`type`	string	—	Field type (required). One of the supported types.
`primary_key`	bool	`false`	Whether the field is part of the object’s primary key.
`optional`	bool	`false`	Whether the field is nullable / may be omitted on create.
`mutable`	bool	`true`	Whether the value can be changed after creation.
`default`	any	`null`	Default value applied at the database level when the field is omitted.
`db_column`	string	`null`	(Optional) Override the underlying ClickHouse column name.
`db_type`	string	`null`	(Optional) Override the underlying ClickHouse column type.
`relationship`	list	`null`	(Optional) Declares the field as a relationship to another object.
`options`	list	`null`	(Optional, `str` only) Allowed values; renders a dropdown and is validated on write. See Options.

Field types

Type	Description
`int`	Integer
`str`	String
`float`	Floating-point number
`bool`	Boolean
`datetime`	Timestamp
`date`	Calendar date

By default each type maps to a sensible ClickHouse column type. Use db_type to override the exact type.

Primary keys

At least one field must have primary_key: true. The combination of primary key fields uniquely identifies an instance, and it is used to compute the stable instance key (_key).

Primary key fields cannot be optional.
Primary key fields are immutable — attempting to change one through the API is an error. A different primary key is a different instance.

fields:
  - name: order_id
    type: int
    primary_key: true
  - name: line_no
    type: int
    primary_key: true   # composite primary key
  - name: quantity
    type: int

Defaults

default sets a database-level default that ClickHouse applies whenever the field is omitted from an insert. This means the default is enforced regardless of how the instance is created — through the API, or directly against the table. Because it is a database expression, you can use functional defaults:

fields:
  - name: created_at
    type: datetime
    default: now()        # evaluated by the database on insert
  - name: status
    type: str
    default: active
  - name: is_active
    type: bool
    default: true

A field with a default may be omitted when creating an instance — the database fills it in. Functional defaults such as now() can only be produced at insert time, so the client should leave the field out rather than sending a value.

Mutability

Set mutable: false to freeze a field after the instance is created. Non-primary-key fields are mutable by default.

fields:
  - name: external_ref
    type: str
    mutable: false   # set once at creation, never updated

Custom database columns and types

Use db_column and db_type to control the underlying ClickHouse storage independently of the field name and logical type:

fields:
  - name: amount
    type: float
    db_type: Decimal(18, 2)   # store as an exact decimal
  - name: label
    type: str
    db_column: display_label  # store under a different column name

Relationships

A relationship field points at another object’s instance. It is metadata only — there is no database-level foreign key. The field itself is a plain string that stores the target instance’s key (_key).

The field’s type must be str.
relationship must reference exactly one target object, by name.

name: Company
fields:
  - name: id
    type: int
    primary_key: true
  - name: name
    type: str
  - name: owner
    type: str
    optional: true
    relationship:
      - object: Person   # `owner` stores the _key of a Person instance

At read time you can ask the API to resolve relationships (one level deep) via the add_relationships flag — see the Instance API. In the UI, a relationship field is rendered as a picker over the target object’s instances, using the target’s label_column for display.

Options

A str field can declare a fixed set of allowed values with options. The UI renders it as a dropdown instead of a free-text input, and the API rejects any create/update whose value is outside the list.

fields:
  - name: gender
    type: str
    options:
      - male
      - female
      - other

options is only valid on str fields, and must not be empty.
Writing an instance with a value not in options returns 400.

`settings`

Object-level settings. All are optional.

Attribute	Type	Default	Description
`object_type`	string	`STANDALONE`	`STANDALONE` (managed instances) or `BACKED` (backed by a dataset).
`backed_dataset`	string	`null`	Alias of the backing dataset — required when `object_type` is `BACKED`.
`store_versions`	bool	`false`	Whether previous instance versions are retained.
`icon`	string	`null`	Icon name used to represent the object in the UI.
`label_column`	string	`null`	Which field to display as an instance’s human label in the UI.

settings:
  icon: users
  label_column: name
  store_versions: true

label_column must name one of the object’s fields. It is used wherever an instance is shown by name — most importantly in relationship pickers.
icon is purely for UI presentation.
store_versions keeps superseded versions of an instance available in history. With it off, old versions may be compacted away over time (history becomes best-effort).

BACKED objects (object_type: BACKED, backed by a dataset) are not yet generally available. Define STANDALONE objects — the default — for managed instances.

`actions`

Actions bind a named operation on the object to a Python handler function in your repository.

Attribute	Type	Description
`name`	string	Action name (required).
`description`	string	(Optional) Human-readable description.
`handler`	string	Reference to the handler, in the form `path/to/file.py:function`.

actions:
  - name: send_welcome_email
    description: Send a welcome email to the employee.
    handler: objects/employee_actions.py:send_welcome_email

The handler must point at a Python file and function in your repository. Changing an object’s actions does not trigger a schema migration — only field and setting changes do.

Executing actions via the API is on the roadmap; today, actions are declared and validated as part of the object definition.

Full example

objects/employee.yaml

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: department
    type: str
    optional: true
    relationship:
      - object: Department
  - name: salary
    type: float
    db_type: Decimal(18, 2)
  - name: hired_at
    type: datetime
    default: now()
  - name: is_active
    type: bool
    default: true

settings:
  icon: users
  label_column: name
  store_versions: true

actions:
  - name: send_welcome_email
    description: Send a welcome email to the employee.
    handler: objects/employee_actions.py:send_welcome_email

Deploying multiple objects

To define more than one object in a single file, separate documents with ---:

objects/hr.yaml

name: Department
fields:
  - name: id
    type: int
    primary_key: true
  - name: name
    type: str
settings:
  label_column: name
---
name: Employee
fields:
  - name: id
    type: int
    primary_key: true
  - name: department
    type: str
    relationship:
      - object: Department

Each object still becomes its own identity, definition, and ClickHouse table. Object names must be unique within the file and within the project.

Next steps

Overview — concepts, branching, and the lifecycle.
Instance API — managing instances of your objects.

​Knowledge Object YAML Reference

​Top-level structure

​fields

​Field types

​Primary keys

​Defaults

​Mutability

​Custom database columns and types

​Relationships

​Options

​settings

​actions

​Full example

​Deploying multiple objects

​Next steps

Knowledge Object YAML Reference

Top-level structure

`fields`

Field types

Primary keys

Defaults

Mutability

Custom database columns and types

Relationships

Options

`settings`

`actions`

Full example

Deploying multiple objects

Next steps