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

> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the SDK. To install or publish skills from a terminal, use the `aireg` CLI; `aireg --map json` prints its command map. The `atlanai` CLI is deprecated. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.
> These docs cover Atlan AI Registry, Atlan's hosted product. The AI registry specification and aireg CLI are maintained separately. /open-source lists publicly reachable signed installers and explains that the source repository and hosted CLI reference currently require GitHub access. Do not claim the repository or its reference docs are publicly accessible. Use these docs for Atlan-specific setup such as the adapter, sign-in and workspaces.

# Manage knowledge records

> Keep policies and controls as governed records with effective dates, publish them as a record set, and let agents read what was in force on any date.

<Badge color="orange">Preview</Badge>

Knowledge records let you keep a small inventory of policies, controls or procedures inside the ontology, each with the dates it is in force. Agents can then ask what applied on a given day, for example which return policy covered an order placed last March.

Records are for directly managed rules, not warehouse data. Customers and orders stay in your warehouse; a retail return policy by region is a good fit.

## Before you begin

* Your ontology has a published release. **Knowledge records** appears under **Data** only once a release exists.
* The release includes an object type for the records. For the retail example, add a `Return policy` object type with `policy_code` (**Text**, identifier), `region` (**Text**) and `return_window_days` (**Whole number**, unit `days`), then publish. Adding a type is a compatible change, so Studio suggests `1.1.0`.

<Steps>
  <Step title="Create a record">
    1. Open **Knowledge records** and choose **New record**.
    2. In **New governed record**, choose the **Released logical type** **Return policy**. Studio locks the record to that release and type version, so its meaning can't drift.
    3. Enter a **Name** such as `EU returns 2026`, then fill in the **Governed values**: `policy_code` `EU-RET`, `region` `EU`, `return_window_days` `30`.
    4. Set **Effective from** to the date the policy starts. Leave **Effective until** empty while it remains in force.
    5. Keep **Lifecycle** on **Active**, then choose **Create record**.

    A record left in **Draft** stays out of record-set releases, and other records can't link to it. Use **Add relationship** to link a record to another record through a link type, or switch **Authoring mode** to **JSON** to edit the whole record.
  </Step>

  <Step title="Change a policy without rewriting history">
    When the EU return window changes from 30 to 14 days on 1 July:

    1. Select the record and choose **Change validity**.
    2. Choose **Replace**, set **Change takes effect** to 1 July, and enter the **Replacement values**.
    3. Choose **Create successor**.

    The original record becomes **Superseded** and ends on 1 July. The successor starts at the same instant and records which record it supersedes. An agent asking about an order from 15 June still gets the 30-day policy. To end a policy with no replacement, choose **Retire** and then **Retire record**.

    A draft record can still be edited with **Edit draft**. An active record is changed only through **Change validity**, and a superseded or retired record is closed.
  </Step>

  <Step title="Publish the record set">
    1. Choose **Publish record set…**.
    2. Enter a **Semantic version** such as `1.0.0` and choose **Publish**.

    The first publication creates the record set. Publishing checks that the records are consistent with each other, then freezes every active, superseded and retired record at its current version as the new latest release. Existing releases never change, so publish again after each round of edits.

    To publish from a script, call `POST /ontology/v1/record-set-releases` with the `record_set_id`, the new `release`, and optionally the `base_release_id` you expect to replace.
  </Step>

  <Step title="Query records as of a date">
    In **Knowledge records**, set **Valid as of** to the business date you care about and filter by **Record type**, **Lifecycle** or **Search records**. Switch between **Working records** and **Current release** to compare drafts with what is published.

    Agents open a session with `mcp__initialise`, then call `extension__ontology__get_records`. Replace the example ontology and session IDs with your values:

    ```json theme={null}
    {
      "ontology_id": "ontology_01example",
      "as_of": "2026-06-15T00:00:00Z",
      "query": "EU",
      "include_relationships": true,
      "session_id": "mcp_session_<your-session-id>",
      "rationale": "Find the EU policies in force on the requested business date."
    }
    ```

    To read a frozen record-set release instead of current record versions, call `POST /ontology/v1/record-queries` with both `record_set_id` and `record_set_release_id`.
  </Step>
</Steps>

## How valid time works

Each record has a business-valid period, separate from when it was saved. The period includes **Effective from** and excludes **Effective until**, so a record is returned for `as_of` when:

* `effective_from` is at or before `as_of`, and
* `effective_to` (**Effective until**) is empty or after `as_of`.

| Query input | Default | Notes |
| - | - | - |
| `as_of` | Now | An RFC 3339 instant. Studio sends your local time as UTC. |
| `lifecycle_states` | Active only | Add `superseded`, `retired` or `draft` to see more. |
| `query` | None | Up to 256 characters, matched against record names and governed values. |
| `limit` | 50 | 1 to 100 per page. Studio's Ask tab shows 20 per page. |

A text search inspects at most 5,000 candidate records. When it stops early, the response sets `scan_truncated: true`, and Studio says the results aren't a complete inventory. Narrow the type or term and search again.

A record can also cite exact versions of supporting documents. A released record keeps citing the version it was published with, even after the document changes. Pass `include_knowledge_references: true` to return those citations.

## Publication rules and limits

Publishing a record set is refused when:

| Rule | Message |
| - | - |
| The set has no non-draft records | A record set release must contain at least one governed record. |
| A record is locked to a different ontology release than the set | Every record in the set must pin the record set's exact ontology release. |
| Two records share an API name | A record set cannot contain duplicate record api\_name values. |
| A relationship or supersession points outside the set | A record set contains a relationship or supersession target outside the set. |
| Superseding records overlap in time | Superseding record business-valid intervals must not overlap. |
| A relationship outlives a retired target | A relationship cannot remain valid after its target record is retired. |
| The version already exists with different content | This record set release label already exists with different content. |

| Limit | Value |
| - | - |
| Records per record-set release | 50,000, stored in shards of up to 500 |
| Governed values per record | 256, up to 1 MiB encoded |
| Relationships per record | 512 |
| Supporting-document citations per record | 64 |
| Records one record supersedes | 64 |

A superseded or retired record must have an **Effective until**.

## Verify

* **Knowledge records** shows the record set's **Current release** with its version and **Release checksum**.
* With **Valid as of** before 1 July, the 30-day policy is listed; after 1 July, the 14-day successor is.
* `extension__ontology__get_records` with the same `as_of` returns the same records.

## Related

* [Ontology concepts](/ontology/concepts#record): records, record sets and releases.
* [Read governed records](/tools/mcp/ontology/references/ontology-get-records): the MCP tool's inputs and response.
* [Use Ontology with agents](/ontology/how-tos/use-with-agents): where records fit in an agent's flow.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.