Datagraph Objects

Overview

A Datagraph Object is a named SQL query over the Datagraph model, with declared parameters and inferred output columns. Open DataHub → Datagraph → Objects — Manage datagraph objects for your account. The OBJECTS listing shows Name, Status, and Last update. Its description is Manage datagraph objects for your account. Select CREATE OBJECT to open a new Draft. The empty state says No objects yet.

Before You Begin

The Datagraph Schema must be published, because output columns are inferred against the Live model. See Datagraph Schema.
Every Datasource referenced by the SQL needs a Live version.
Datasources protected by row-level filters cannot be queried from an Object.

Editor Layout

The editor breadcrumb is Datagraph > Objects. Its subtitle is Define and manage your datagraph object SQL query and options. The Object name field uses snake_case. The Edited object selector switches the version being edited. The side panels are INPUT / OUTPUT and VERSIONS. The SQL editor runs a preview against the selected Object. Results include up to 10 rows, a row count, and a Trace ID.

Field	Description
Object name	The Object identifier. Use snake_case, for example `top_products_bought`.
Description	What the Object answers, in business terms.

Writing the SQL

Datasource tables are referenced by their Datasource identifier, quoted:

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.

Object	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 Object with a real identifier before publishing, and relax the least critical condition when the result set is empty.

Parameters

Parameters are declared in INPUT / OUTPUT 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.

Suggested Values

Each parameter can carry a suggested value and a list of allowed values. Both are configuration hints for the Datagraph Object Node — see Datagraph Object. They change nothing when the SQL runs.

Suggested Value

Set under SUGGESTED VALUE → Source in the parameter editor:

Source	What it suggests	Available for
None	No suggestion (default).	All types
From context	A Context variable, picked with the Variable Picker. The list matches the workflow drawer for that type: `string` and `string[]` → user identifier, IP, ISP, device type, OS, referer, mail client, locale, day of the week; `number` and `number[]` → entrypoint index; `boolean` → user identified; `datetime` and `datetime_iso` → current date.	`string`, `number`, `boolean`, `datetime`, `datetime_iso`, `string[]`, `number[]`
From Team attribute	The values of a Team attribute. The key must start with a lowercase letter, followed by up to 63 lowercase letters, digits or underscores.	`string`, `string[]`
Fixed value	A static value, typed by the parameter type.	Scalar and list types

Dictionary types (string{}, number{}) cannot use From context.

Object option editor with the From context suggestion source selected and the Context Variable Picker open

Allowed Values

For string, number, string[] and number[] parameters, Allowed values lists the values the parameter may take, with no duplicates. The Datagraph Object Node renders them as a select or multi-select instead of a free input.

An invalid suggestion or allowed value is reported on the matching field when you save. When you change a parameter’s type, a suggestion or allowed value that no longer fits is dropped.

Output Columns

The INPUT / OUTPUT panel lists each output Column and Type. Displayed types include Text, Number, and Image URL. The list is computed from SQL against the Published Datagraph model and recalculated on every save.

Previewing Results

Save the Object before running a preview.
Click RUN QUERY to open QUERY PARAMETERS.
The modal says Fill in the object parameters before running the SQL preview. Each parameter shows its type and short description.
Select Fill sample values to find realistic values, then click 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 Queries page is available at DataHub → Datagraph → Queries. It runs Datagraph Object SQL queries and displays results. Select an Object and run it to see results; pages show 10 rows.

Publishing

Click Publish to open the Publish object dialog and publish the Draft. The previous Published version becomes Inactive, and a new Draft copy is created. Only published Objects are selectable in Workflows. The Delete object dialog warns that Workflows that query this object will stop resolving. Deleting an Object cannot be undone.

When the Object belongs to a published Datagraph Object Family, publishing fails with Entity group contract violated if the new output columns no longer satisfy the family contract. An Object listed in a published family cannot be deleted either.

Several Objects that answer the same question for different segments — one recommendation algorithm per Object, for example — can be bound to a Datagraph Object Family. The family declares the fields every member must return, and checks the Live version of each member against it. See Datagraph Object Families.

Using an Object in a Workflow

Add the Datagraph Object Data Node — Run a datagraph object query and expose its results to the workflow.

Setting	Description
Object	The published Object to run. Choose it from Select a published object.
Object parameters	One input per declared parameter. Each parameter’s short description appears above its input.

The empty selector message is No published object is available yet. Open object in Datahub opens the Object editor.

Only tech admins can configure Datagraph object query nodes.

The Result limit field is hidden by default. It appears only when a tech admin enables Datagraph Object: result limit under Workflow settings → Features. It accepts 1 to 200 rows.

The Node itself is documented in Datagraph Object.

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?

Object families

Bind several Objects to one shared output contract.

Schema

Add the columns and relations your SQL needs.

Schema views

Inspect the Diagram, Relations, and Datasources tabs on the Schema page.

Datasource Data Node

Compare with querying a single Datasource in a Workflow.

Datagraph Schema API

Manage the model programmatically.

Getting Started

DataHub Deep Dive

Advanced Workflows

Email Rendering

Transformations

Advanced Analytics

Overview

Before You Begin

Editor Layout

Writing the SQL

Worked Examples

Parameters

Suggested Values

Suggested Value

Allowed Values

Output Columns

Previewing Results

Publishing

Using an Object in a Workflow

What’s Next?

Object families

Schema

Schema views

Datasource Data Node

Datagraph Schema API

​Overview

​Before You Begin

​Editor Layout

​Writing the SQL

​Worked Examples

​Parameters

​Suggested Values

​Suggested Value

​Allowed Values

​Output Columns

​Previewing Results

​Publishing

​Sharing a Contract Across Objects

​Using an Object in a Workflow

​What’s Next?

Object families

Schema

Schema views

Datasource Data Node

Datagraph Schema API

Overview

Before You Begin

Editor Layout

Writing the SQL

Worked Examples

Parameters

Suggested Values

Suggested Value

Allowed Values

Output Columns

Previewing Results

Publishing

Sharing a Contract Across Objects

Using an Object in a Workflow

What’s Next?