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

# Building Entities from Tables

> Create semantic entities from your Table Catalog to power the Semantic Catalog.

Entities are the core business objects in your Semantic Catalog — they represent the things your organization cares about, like users, orders, sessions, or transactions. Entities are built from tables in your Table Catalog.

## What Is an Entity?

An entity maps one or more database tables to a business concept. It contains:

* **Dimensions** — All the properties that describe the entity — attributes, measures, and grouping axes. Anything you can say about an entity is a dimension: country, platform, revenue amount, session duration, user email, plan name.

For example, a `users` table might become a **Users** entity with dimensions like `country`, `signup_source`, `lifetime_value`, `email`, and `plan_name`.

## How to Build Entities

<Steps>
  <Step title="Select tables from the Table Catalog">
    Open the Table Catalog and select the tables you want to create entities from. You can select multiple tables at once.
  </Step>

  <Step title="Send to the Builder">
    The agent inspects the selected tables — sampling data, understanding the grain of each table, and identifying relationships between them.
  </Step>

  <Step title="Review the agent's proposals">
    The agent suggests one or more entities based on the tables you selected, each with a name, description, SQL, and proposed dimensions. A single table may become one entity, or multiple tables may be combined into one entity with joins.
  </Step>

  <Step title="Approve and refine">
    Review each proposed entity and its dimensions. You can accept them as-is, ask the agent to adjust names, descriptions, or dimensions, or remove entities you don't need.
  </Step>
</Steps>

## Best Practices

* **Start with your most queried tables** — Build entities for the tables your team asks about most
* **Use meaningful names** — Entity and property names should reflect business terminology, not database column names
* **Dimension descriptions come from the Table Catalog** — The descriptions you approved on columns in the Table Catalog carry over to dimensions automatically, so invest in good column descriptions early
* **Review nested fields** — For tables with STRUCT/RECORD columns, select the specific nested fields that matter rather than including the entire structure

## Adding Dimensions to Existing Entities

When new columns are discovered in the Table Catalog — for example, after a schema change or a daily discovery job — they don't automatically become dimensions on existing entities. You need to add them manually.

From the Table Catalog, select the new columns and choose an existing entity to add them to. The agent creates the dimensions using the column descriptions from the Table Catalog.

<Tip>
  When new columns are discovered by [daily discovery jobs](/context-layer/table-catalog/daily-discovery-jobs), you'll be notified and they'll appear in the Missing Description Wizard. Once described and approved, add the relevant ones as dimensions to your entities so the agent can use them in analyses.
</Tip>