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

# Bindings

> Bindings tell agents which tables, columns and joins hold each type in an ontology release, without connecting to your warehouse.

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

A binding maps one exact ontology release to the physical data that implements it. The ontology says what a Customer is; the binding says that Customers live in `retail.core.customers`, one row per customer. An agent that asks for binding context gets both, then writes and runs its own query with its own connection.

```mermaid theme={null}
flowchart LR
  subgraph L["Ontology release 1.0.0"]
    C["Customer"] -- places --> O["Order"]
  end
  subgraph B["Binding release 1.0.0 · locked to ontology 1.0.0"]
    CM["Object mapping<br/>retail.core.customers<br/>one row per customer"]
    OM["Object mapping<br/>retail.core.orders"]
    LM["Link mapping<br/>join on customer_id"]
  end
  C -.-> CM
  O -.-> OM
  CM --- LM --- OM
```

## Mapping types

A **binding family** groups the mappings from one ontology release to one source. It records the ontology release it is locked to, a **Source scope** that names the source, and a **Versioning policy**. Inside it, you declare three kinds of mapping:

| Mapping | Declares | Retail example |
| - | - | - |
| **Object** | Which relation holds one object type, and its **Grain**: what one row means and which logical properties make it unique. | Customer → `retail.core.customers`, "One row per customer", unique by `customer_id` |
| **Property** | Which field holds one property of a mapped object, or which registered transformation computes it and which field it outputs. | `status` → `retail.core.customers.status` |
| **Link** | Two object mappings and the join keys between them, as pairs of property mappings. | `places` → join Customer `customer_id` to Order `customer_id` |

## What a mapping can point at

Physical names are declared as qualified names, such as `catalog.schema.table.column`. The binding stores them as governed text and never checks them against a live source.

| Target | How to declare it |
| - | - |
| **Table or view** | An object mapping with **Direct table or view** and a relation name such as `retail.core.orders`. |
| **Column** | A property mapping with a field name such as `retail.core.orders.ordered_at`. |
| **Transformation** | A property mapping with a registered transformation and its output field. Use it for a derived property such as `total_spend`; a plain field mapping doesn't implement a derivation. |
| **Governed join** | A link mapping with one or more join keys between the two object mappings. |
| **SQL-backed relation** | An object mapping with **SQL-backed virtual relation**: one read-only `SELECT` or `WITH … SELECT` in a declared dialect, with named outputs and declared dependencies. |

A SQL-backed relation suits a type that no single table holds, such as active customers only. The dialect is ANSI, BigQuery, Databricks SQL, PostgreSQL or Snowflake. The binding refuses wildcards, unnamed outputs, comments, parameters, and anything other than one read-only query. The SQL is versioned metadata: the binding never runs it.

## Why a new ontology release needs a new binding release

A binding is locked to one exact ontology release, and each object and link mapping pins the exact version and checksum of the definition it maps. That way a mapping can never silently describe a definition that has since changed.

When you publish ontology `1.1.0`, binding releases for `1.0.0` keep working against `1.0.0`. For `1.1.0`:

* **Nothing you mapped changed.** An agent can pass the newer release as `ontology_release_id` when it asks for binding context. Reuse works only when every definition the binding references has the same version and checksum in the newer release. Otherwise the request is refused with `source_unavailable`, never answered with stale mappings.
* **A mapped definition changed.** In **Data bindings**, choose the new **Ontology release**, create a binding family and map it, then validate and publish a binding release. To carry existing mappings over, export the old binding release as portable JSON and import it against the new ontology release, which creates a new binding family from it.

## Rules

* **Declarations, not verification.** Validation checks that mappings resolve and agree with the ontology. It doesn't confirm a table exists, a join is correct, or a query runs.
* **No credentials or endpoints.** A binding holds qualified names, grain, joins and SQL text only. Agents use their own, separately governed connection.
* **Releases are fixed.** Like ontology releases, a binding release has a semantic version and never changes. Saving a mapping adds a draft version; published releases keep theirs.
* **Gaps are reported.** Binding context includes a handoff report that names each unmapped object, unmapped property or link with no join keys, with a fix for each.
* **Size.** One binding release holds up to 5,000 mappings.

## Related

* [Publish bindings through the API](/cookbooks/how-tos/ontology-bindings): create, validate, publish, export and import bindings, in Studio or from scripts.
* [Use Ontology with agents](/ontology/how-tos/use-with-agents): when an agent should call binding context.
* [Get bounded ontology-binding context](/tools/mcp/ontology/references/ontology-binding-get-context): the MCP tool's inputs and response.
* [Ontology concepts](/ontology/concepts): object types, properties and links.


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