Configure named queries

Named queries define integration endpoints to consume structured information from the data hub using a REST API. Each named query is exposed as a REST endpoint, supporting complex structures as query parameters.

For more information about using named queries for integration, see Use named queries.

The content of data anotifications is produced by named queries. To use a named query for data notifications, see Prepare the named query.

Named query structure

A named query consists of an object linked to an entity and contains various properties.

Properties can be of the following types:

Value expression: a simple value computed from SemQL expressions using the entity’s attributes.
Multi-record expression: a filtered and sorted list of records associated with the entity (e.g., the list of Contacts records attached to the Customer entity).
Single-record expression: a single record associated with the entity (e.g., the AccountManager record relating to the Customer entity).

Both multi-record and single-record types are considered objects and possess their own properties. Typically:

Value properties represent the attributes of the entity.
Multi-record properties represent referencing (i.e., child) records along with their properties.
Single-record properties represent referenced (i.e., parent) records along with their properties.

A multi-record or single-record property can reference an object that already exists within the named query. This capability allows for the creation of recursive structures.

Create a named query

To create a named query:

Right-click the Named Queries node and select Add Named Query.
The Create New Named Query wizard opens.
In the wizard, enter the following values:
- Name: the internal name of the object.
- Description: a description of the named query.
From the Entity drop-down menu, select the root entity of the named query.
Click Next to move to the second wizard step.
In the Name field, provide a name for the root object of the query.
Click Next to move to the third wizard step.
From the Create New Object Properties list, select:
- Simple attributes to create properties of type Value expression.
- Foreign attributes to create properties of type Single-record expression.
- Reference relationship to create properties of type Multi-record expression.
Click Finish to close the wizard.
The Named Query editor opens.
(Optional) In the Filter field, configure a filter condition for the data retrieved by the query.
(Optional) In the Sort field, configure a sorting expression for the data returned by the query.
Press Control+S (or Command+S on macOS) to save the editor.

Add a property

To add a property to an object:

In the Object Properties tree table, select the object to which you want to add a property.
Click the Add Property button in the tree table toolbar.
The Create New Object Property wizard opens.
In the wizard, enter the following values:
- Property Type: select the type of the property.
- SemQL Expression: enter or define the SemQL expression corresponding to a single record, multi-record, or value expression, according to the property type.
- Name: provide a name for the property.
If you are creating a value property, click Finish to close the wizard.
The property is added to the object.
If you are creating a multi-record or single-record property:
1. Click Next.
2. In the second step of the wizard, select the object the multi-record or single-record property should point to:
  - Create New Object to create and name a new object.
  - Use Existing Object to point to an object that already exists in the named query.
3. Click Finish to close the wizard.
  The property is added to the object.
4. Select the multi-record or single-record property you just created.
5. In the Properties view, you can configure the following:
  - Filter: a filter condition that appliies to the data returned in either a single-record or multi-record property.
  - Sort: a sorting expression that applies to the records returned in a multi-record property.
  - Default Limit: a default limit that defines the maximum number of root records returned by the named query (default value: 100`). This limit can be overridden on each query using the $limit parameter.

You can also use the Add Properties action to add multiple properties by selecting simple attributes, foreign attributes, or reference relationships.

Create query parameters

Query parameters are used to store the values passed to a request made to the query. They are defined for the query and can be used in the filter conditions, sort expression, and the properties' SemQL expressions.

To add a query parameter:

In the Named Query editor, scroll down to the Query Parameters table, and click the Add Query Parameter button.
The Create New Query Parameter wizard opens.
In the wizard, enter the following values:
- Name: the internal name of the object.
- Binding Name: a name used to refer to this variable in filter conditions, sorting expressions, and SemQL expressions.
- Parameter Data Type: the type of the parameter.
- Default Value: configure a default value for the parameter.
- (Optional) If the parameter has no default value, select the Mandatory checkbox if you want to make it mandatory for the query.
Click Finish.
The parameter is added to the list.

You can reference a query parameter by prefixing its binding name with a colon (:). For example, to filter products by an ID passed through a parameter with the binding name QUERY_PARAM_SEARCHED_ID, you would use:

ProductID = :QUERY_PARAM_SEARCHED_ID

For more information about using named queries for data notifications, see Configure data notifications.