> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reelevant.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Datagraph Entities
> Write parameterised SQL against the Datagraph model, preview results, and publish for Workflows
## Overview
A Datagraph Entity is a named SQL query over the Datagraph model, with declared parameters and inferred output columns. Open **DataHub → Datagraph → Entities** — *Manage datagraph entities for your account*.
The listing shows each Entity with its **Name**, **Status** (**Draft** or **Live**), and **Last update**, plus two actions: **Edit** and **Query**. **Create entity** opens the editor on a new Draft.
## Before You Begin
* The Datagraph Schema must be published, because output columns are inferred against the Live model. See [Datagraph Schema](/advanced-guide/datahub/datagraph/schema).
* Every Datasource referenced by the SQL needs a Live version.
* Datasources protected by row-level filters cannot be queried from an Entity.
## Editor Layout
| Panel | Content |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **SQL query** | The statement executed for this Entity. **Format SQL** re-indents it, and **Run query** executes it. |
| **Input / Output** | **Input** lists the parameters passed to the SQL query. **Output** lists the computed answer returned by the Entity, and is read-only. |
| **Preview & results** | A sample of query results, up to 10 rows, with the row count and a **Trace ID**. |
Both side panels can be collapsed, and the toolbar shows the keyboard shortcut for saving, formatting, and toggling each panel.
| Field | Description |
| --------------- | -------------------------------------------------------------------------- |
| **Entity name** | The Entity identifier. Use snake\_case, for example `top_products_bought`. |
| **Description** | What the Entity answers, in business terms. |
## Writing the SQL
Datasource tables are referenced by their Datasource identifier, quoted:
```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
SELECT
products.name,
products.image_url,
products.price
FROM "6a1f9c24e0b84f0f9a2d7c31" AS purchases
JOIN "8b53d7f1c2a94e6ea0b41d77" AS products
ON products.reference_id = purchases.product_reference
WHERE purchases.user_id = $1
ORDER BY purchases.purchased_at DESC
LIMIT 5
```
The statement must reference at least one Datasource table, otherwise the query is rejected.
## Worked Examples
The patterns below come from a property listings model built on five Datasources: users, listings, price-per-square-metre by area, pre-computed recommendations, and editorial content.
| Entity | Pattern | Parameters | Returns |
| -------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------- |
| `listings_matching_search` | Join users to listings on the searched area, then filter on the user budget. | `user_id` (`string`) | Listings ordered by quality score, limited to 6. |
| `listings_price_drop` | Filter listings of one area on a minimum price variation, computed from the previous price. | `zone_id` (`string`), `min_drop_pct` (`number`) | Listings ordered by drop percentage. |
| `market_prices_area` | Read the market table for the area a user is searching, with the 12-month trend. | `user_id` (`string`) | One row: median price per square metre, trend, average selling time. |
| `recommended_listings` | Join a pre-computed recommendation table to listings, keeping the algorithm rank. | `user_id` (`string`) | Recommended listings ordered by rank. |
| `editorial_content_area` | Filter editorial content on the area, restricted to items whose publication window is open. | `zone_id` (`string`) | Guides and market articles for that area. |
The same patterns transfer to other models: last items purchased by a customer, remaining stock in a preferred store, best sellers of a category, or complementary products of an order.
Filters that combine several user preferences — budget range plus minimum number of rooms, for example — can legitimately return zero rows. Preview each Entity with a real identifier before publishing, and relax the least critical condition when the result set is empty.
## Parameters
Parameters are declared in the **Input** panel and bound to SQL placeholders. Click **Add** to create one.
| Field | Description |
| ------------------------- | -------------------------------------------------------------------------------- |
| **Name** | The parameter name, for example `user_id`. |
| **Short description** | Displayed in the UI. Maximum 100 characters. |
| **Full description** | Optional detailed description. |
| **Type** | The scalar type accepted at query time. |
| **Optional** | When enabled, the parameter can be omitted or left empty when running the query. |
| **SQL placeholder index** | Maps the parameter to `$1`, `$2`, … in the SQL query. |
Accepted parameter types:
| Type | Expected value |
| ----------------------- | ------------------------------------------------------------- |
| `string` | A text value. A bare number is rejected. |
| `number` | A numeric value. |
| `boolean` | `true` or `false`. |
| `datetime` | A datetime value. |
| `datetime_iso` | An ISO 8601 datetime, for example `2024-01-01T00:00:00.000Z`. |
| `string[]` / `number[]` | A JSON array of strings or numbers. |
| `string{}` / `number{}` | A JSON object whose values are strings or numbers. |
A NULL parameter compared with `=` or `<>` never matches. The editor flags it and asks you to use `IS NULL` or `IS NOT NULL` in the SQL query instead.
## Output Columns
The **Output** panel lists the **Column** and **Type** of every value the Entity returns, under **Return types**. The list is computed from the SQL against the Live Datagraph model and recalculated on every save — it cannot be edited by hand. An empty list means the SQL has not been resolved yet, or that it references an unknown column.
## Previewing Results
1. Save the Entity — a preview cannot run on unsaved changes only. The editor shows *Save the entity before running a preview*.
2. Click **Run query**.
3. In the **Query parameters** dialog, fill each parameter. **Fill sample values** looks up realistic values in the data for you.
4. Confirm with **Run query**.
The **Preview** panel returns up to 10 rows with the row count and a **Trace ID** for support requests.
| Editor message | Meaning |
| ------------------------------------------------------------------------ | ------------------------------------------------------ |
| *Write a query with FROM "datasource-id" and click run to see a preview* | The SQL does not reference a Datasource yet. |
| *Column "…" does not exist in the datasource* | The column is not part of the Live Datagraph model. |
| *Enter a valid ISO 8601 datetime* | A `datetime_iso` parameter value is malformed. |
| *Unable to find sample values from the data* | No sample could be derived; enter the values manually. |
The **Entity queries** page — reachable with the **Query** action or **Open query page** — runs a saved Entity on its own, outside the editor. Results are paginated at 10 rows per page.
## Publishing
Click **Publish** to promote the Draft to Live. The previous Live version becomes Inactive, and a new Draft copy is created so editing can continue. Only Live Entities are selectable in Workflows.
## Using an Entity in a Workflow
Add the **Query an entity** Data Node — *Run a datagraph entity query and expose its results to the workflow*.
| Setting | Description |
| --------------------- | --------------------------------------------------------------------------------------------------------- |
| **Entity** | The published Entity to run. The dropdown shows *No published entity is available yet* until one is Live. |
| **Entity parameters** | One input per declared parameter. Values can be static or taken from a Workflow variable. |
| **Result limit** | The maximum number of rows exposed to the Workflow. |
**Open entity in Datahub** jumps from the Node to the Entity editor. Only tech admins can configure the Node. The Node itself is documented in [Query an Entity](/advanced-guide/workflows/data-nodes/datagraph).
Parameter values coming from Workflow variables are converted to the declared parameter type. A variable that cannot be converted — free text into a `number` parameter, for example — makes the Node fail at execution time rather than at configuration time.
## What's Next?
Add the columns and relations your SQL needs.
Check that a join actually overlaps before you rely on it.
Compare with querying a single Datasource in a Workflow.
Manage the model programmatically.