Using the Query Builder

About the Query Builder

Instead of completely relying on the system to generate your query, you can write your own query in the Edit Query window. In this window, you can write a query for the Advanced Form Search control, Object Lookup control, organization-defined searches, and the Find Similar toolbar button.

In the Edit Query window, you can add several types of placeholders, depending on which control you are configuring:

• PLACEHOLDER(): Use this placeholder if you defined any placeholders by adding form items.
• DATECALC(): Use this placeholder to insert a date.
  Note: This type of placeholder is available only for configuring the Object Lookup control.
• VALUEOF(<user field>): Use this placeholder to return a value from the identities service.
• FIELDVALUE(): Use this placeholder to insert the value of a field.
  Note: This type of placeholder is available only for configuring the Object Lookup control and the Find Similar toolbar button.
• Current user value: Use this placeholder to add a placeholder for the current user’s identifier.

Build a Query by Using the Query Builder

1. In the Insert drop-down list in the Edit Query window, select a placeholder type.
2. Do one of the following, depending on the placeholder type that you selected:
   • For PLACEHOLDER(): Select the placeholder that you configured when you added a form item by using the Placeholder drop-down list. You can also enter a fallback value to use in the query if the user does not enter a value for that particular form item. If the user does not enter a value into a placeholder control, and no fallback value is specified, then the placeholder is replaced with the configured default placeholder. For more information, see Setting the Default Search Placeholder. However, if no data is stored in one of the fields being searched, no objects are returned.
   • For DATECALC(): In the Value drop-down list, select Now if you want to insert the current date, or select Field Value if you want to use the contents of a field.
     Note: If you select Field Value, you must edit the Query box to complete the FIELDVALUE() function.

     You can also enter a duration, which is either a positive or negative number that is added to or subtracted from the returned date and that uses the unit of time that you select in the Offset drop-down list. You can also choose to specify the date format.

   • For VALUEOF(): In the Value drop-down list, select the user information that you require. Select Id to show the short form of the user name, such as jsmith. Select Username to show the user’s full name, such as John Smith. Select Email to show the user’s email address.
   • For FIELDVALUE(): In the Field drop-down list, select the field that you want to use in your query.
     Note: You can use any of the entity's fields in your query. However, if you reference a field that is not associated with a control on the current page, the query does not function as expected.

     You can also set a fallback value that is used if the field is empty. If the field is empty and no fallback value is specified, then the configured default placeholder is used. For more information, see Setting the Default Search Placeholder.

3. Click to add the placeholder to the Query box, either at the position of the cursor in this box if the cursor is visible, or at the end of the query.

   The search query syntax that results from your selections is displayed in the Example query box. Entities that you specified when you configured your control or search, and any modifiers that you set when you defined form items are included in the results, but automatic form items are not included. You can also manually edit the contents of the Query box if required.

4. Add additional placeholders as required.
5. Click OK when you have finished adding placeholders.

   Your updated query is displayed, and the Example query box is updated to show the complete search query, incorporating both the manual and automatic query elements.