Skip to main content
Query an entity Data Node configured with a published Entity, a bound parameter and a result limit

​
Overview

The Query an entity Data Node executes the Live version of a Datagraph Entity and exposes the returned rows to downstream Nodes. It is the only way to consume the Datagraph model inside a Workflow. Unlike a Datasource Node, which reads a single Datasource, this Node runs the joined SQL prepared in the Entity. Filtering, joining, and ordering therefore live in the Entity, not in the Node.
The Datagraph is in beta, and the Node is restricted to tech admins. Other users do not see it in the Data menu of the editor.

​
Adding the Node

Hover the Data button in the editor toolbar and select Query an entity. See Data Nodes for the general procedure. Data menu of the Workflow editor with the Query an entity option at the bottom of the list

​
Configuration

The icon next to the Entity field opens the Entity in DataHub → Datagraph → Entities, in a new tab and in the current account scope. Changing the selected Entity clears the parameter values already set, because parameter names belong to the Entity definition.
Publishing a new Entity version that renames or adds a parameter does not update Nodes already configured. Re-open each Node to bind the new parameters, otherwise the mandatory ones are missing at execution time.

​
Binding Parameters

Each parameter is bound either to a static value or to a value produced upstream in the Workflow, through the Variable Picker. The input control follows the declared parameter type. Parameter value picker of the Query an entity Node, with a typed value and the Datasources available in the Workflow A parameter takes a single value. Multiple values for one parameter are not supported. Mandatory parameters must be bound. If a mandatory parameter has no value at execution time, the Entity is rejected with an invalid parameter error rather than returning an empty result.
When the Entity declares a client_id parameter and the Workflow resolves exactly one tracked person, that identifier is used for client_id if you left the field empty. Any value you bind explicitly always wins.

​
Output

The Node returns a list of rows. Each row holds the output columns inferred by the Entity, with text, numeric, or empty values. Those columns are exposed to downstream Nodes in the Variable Picker, under the name of the Entity, and can feed a Content or a Condition. The canvas Node displays the name of the selected Entity, so a Workflow using several Entities stays readable. Query an entity Node on the Workflow canvas, showing the name of the selected Entity

​
Worked Example

A property listings Datagraph joins users, listings, recommendations, and market prices. The Entity listings_matching_a_user_search declares one parameter, user_id, and returns one row per matching listing with its reference, surface, city, and price. In the Workflow:
  1. A URL Parameter Node captures user_id from the call made by the sending tool.
  2. A Query an entity Node selects listings_matching_a_user_search, binds user_id to that URL Parameter, and sets Result limit to 6.
  3. The Content iterates over the returned rows to build a six-listing block.
Because the joins live in the Entity, the same Node configuration works for every recipient, and the model can be corrected without touching the Workflow.

​
Operational Notes

  • Keep the result limit aligned with what the Content renders. Rows that are fetched but never displayed still cost execution time.
  • Test the Entity with Run query in the Entity editor before wiring it into a Workflow, using the same parameter values.
  • Relations with a low join match produce sparse results. Review them in the Datagraph Explorer before blaming the Node.
  • An Entity whose Datasources are protected by row-level filters cannot be executed from a Workflow.

Datagraph Entities

Write the parameterised SQL, infer output columns, and publish an Entity.

Datagraph Overview

Understand the model the Entities are built on.