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.

Refer to Use named queries for more information on using named queries for integration.

The content of Data notifications is produced by named queries. Refer to Prepare the named query to use a named query for data notifications.

Named query structure

A named query is structured as an Object (linked to an entity) containing Properties.

Properties are of the following types:

  • Value: A simple value, computed from SemQL expressions using the entity’s attributes.

  • Multi Records: A filtered and sorted list of records related to the entity. For example, the list of Contacts attached to the Customer.

  • Single Record: A single record the entity relates to. For example, the AccountManager to which the Customer is attached.

Multi Records and Single Record are also Objects, and have their own properties.

Typically:

  • Values represent attributes of the entity.

  • Multiple Records represent referencing (child) records with their properties.

  • Single-Records represent referenced (parent) records with their properties.

A Multi Records or Single Record property can refer to an object that already exists in the named query. Use this capability to create recursive structures.

Create a named query

To create a named query:

  1. Right-click the Named Queries node and select Add Named Query…. The Create New Named Query wizard opens.

  2. In the Create New Named Query wizard, enter the following values:

    • Name: Internal name of the object.

    • Description: Description of the named query.

    • Entity: Root entity of the named query.

  3. Click Next. In the second wizard step, provide a Name for the root object of the query.

  4. Click Next. In the third wizard step, select:

    • Simple Attributes, to create properties of type Value.

    • Foreign Attributes, to create properties of type Single-Record.

    • Reference Relationship, to create properties of type Multiple-Records.

  5. Click Finish to close the wizard. The Named Query editor opens.

  6. Configure an optional Filter condition applied to the data retrieved by the query.

  7. Configure an optional Sort expression applied to the data returned by the query.

  8. Press Control+S (or Command+S on macOS) to save the editor.

Add a property

To add a property to an object:

  1. In the Object Properties tree table, select the object you wish to add a property to.

  2. Click the Add Property button in the tree table toolbar. The Create New Object Property wizard opens.

  3. In the Create New Object Property wizard, enter the following values:

    • Property Type: Select the type of the property.

    • SemQL Expression: Enter or build 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.

  4. If you create a Value property, click Finish to close the wizard. The property is added to the object.

  5. If you create a Multi Record or Single Record property:

    1. Click Next.

    2. In the second wizard step, 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 that you just created.

    5. In the Properties view, you can configure:

      • A Filter condition applied to the data returned in a Single or Multi Record property.

      • A Sort expression applied to the records returned in a Multi Record property.

      • A Default Limit to define 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:

  1. 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.

  2. In the Create New Query Parameter wizard, enter the following values:

    • Name: Internal name of the object.

    • Binding Name: Name used to refer to this variable in the filter conditions, sort and SemQL expressions.

    • Parameter Data Type: Type of the parameter.

    • Default Value: Configure a default value for the parameter.

    • Mandatory: If the parameter has no default value, indicate whether it is mandatory for the query.

    • Click Finish the parameter is added to the list.

You can use a query parameter by specifying its Binding Name prefixed by a colon (:).

For example, to filter products using the ID passed in a parameter which binding name is QUERY_PARAM_SEARCHED_ID:

ProductID = :QUERY_PARAM_SEARCHED_ID
Refer to Configure data notifications for more information on using named queries for data notifications.