Query Builder

The Query Builder is a visual tool for creating, editing, and executing reusable queries against workspace data. Creators use the Query Builder to construct complex data retrieval logic without writing code. Queries can filter records, join related data, sort results, and limit output through a visual interface.

Queries are workspace-level resources. Once saved, a query can be referenced by modules, workflows, or other workspace features that need to retrieve data.

When to Use the Query Builder

Use the Query Builder when any of the following apply:

• Multiple modules need the same data retrieval logic. A saved query defines the filter, sort, and projection logic once and applies it consistently wherever the query is referenced.
• Data retrieval logic is complex. The Query Builder handles multi-condition filters, lookups across Data Models, and union queries. This logic would be error-prone to duplicate in multiple places.
• Results must be previewed before use. The Preview feature lets Creators test queries in non-production environments before deploying them to production modules or workflows.
• Data retrieval must be managed independently of module logic. Queries are versioned workspace resources. Updating a query updates every module or workflow that references it.

For simple, one-off data retrieval unlikely to be reused, inline module or workflow configuration might be more direct.

Query Types

The Query Builder supports two query types:

• Model Query: Retrieves records from a Data Model. Model queries support lookups and unions.
• Submission Query: Retrieves submissions from an application module. Submission queries support filters, sorting, projection, and limits, but not lookups or unions.

The query type determines which data source options display in the Data Source drop-down and which advanced features are available.

Accessing the Query Builder

The Query Builder is accessible from the Explorer panel on the right side of the Unqork platform. In the Explorer panel, expand the Utilities folder, then expand the Query Builder folder. The Query Builder folder displays all queries in the current workspace, including active and archived queries. Each query displays as an individual row showing its name.

Creating a Query

To create a query:

1. In the Explorer panel, right-click the Query Builder folder and select Create Query from the context menu.
2. In the Query Details dialog, enter a name in the Name field.
3. From the Query Type drop-down, select a query type.
4. From the Data Source drop-down, select a data source. The options displayed depend on the selected query type. Model queries display Data Models. Submission queries display application modules.
5. Select Create Query.

The newly created query opens in edit mode. The system assigns a unique Query ID automatically.

Editing a Query

Select a query from the Query Builder folder in the Explorer panel to open its detail page. The query editor displays the query header fields and configuration sections for filters, lookups, unions, projection, sorting, and limits.

Query Header

Filter Builder

The Filter Builder provides a visual interface for constructing query filters. Filters determine which records the query returns. A query with no filters returns all records from the data source.

Rules and Groups

Filters are built from rules and groups:

• Rule: A single condition that compares a field to a value. For example, Status equals "Active" or Created Date is after "2024-01-01".
• Group: A container that holds multiple rules or other groups, combined with an AND or OR operator.

Groups can be nested. This lets Creators build complex logic like "Status equals Active AND (Priority equals High OR Severity equals Critical)".

Adding Rules

To add a rule:

1. In the Filter Builder, select Add Rule.
2. From the Field drop-down, select a field. The available fields come from the selected data source.
3. From the Operator drop-down, select an operator. The available operators depend on the field type. For example, text fields support operators like equals, contains, and starts with. Number fields support equals, greater than, less than, and range operators.
4. Enter a value in the Value field. The input type changes based on the field type: text fields display a text input, date fields display a date picker, and boolean fields display a toggle.

The rule is applied immediately. The query returns only records that match the rule.

Adding Groups

To add a group:

1. In the Filter Builder, select Add Group.
2. From the AND/OR toggle, select AND or OR. AND requires all rules in the group to match. OR requires at least one rule in the group to match.
3. Add rules or nested groups inside the group.

Removing Rules and Groups

To remove a rule or group, select the delete icon at the right side of the rule or group row.

Warning: Removing a group removes all rules and nested groups inside it. This action cannot be undone.

Field Operators by Type

The operators available for each field depend on the field's data type:

Lookups

Note: Lookups are only available for Model queries. This feature is not available for Submission queries.

A lookup joins data from another Data Model into the query results. Lookups are similar to SQL joins. They match records from the current Data Model with related records from a different Data Model based on a shared field value.

When to Use Lookups

Use lookups when query results need to include data from multiple related Data Models, like the following:

• An Order query must include Customer details, and both are stored in separate Data Models with a shared customerId field.
• A Task query must include Assignee information from a User Data Model.

Adding a Lookup

To add a lookup:

1. In the Lookup section, select Add Lookup.
2. From the Source Collection drop-down, select a Data Model. This is the Data Model to join into the query results.
3. From the Foreign Field drop-down, select a field. This is the field in the source Data Model that will be matched against the local field.
4. From the Local Field drop-down, select a field. This is the field in the current Data Model that will be matched against the foreign field.
5. Enter a name in the Field Name field. This is the name of the field that will contain the joined data in the query results.

The lookup is applied when the query executes. Each record in the query results includes a new field with the specified output name, containing the matching records from the source Data Model.

Lookup Options

Each lookup supports the following optional settings:

Removing a Lookup

To remove a lookup, select the delete icon at the right side of the lookup row.

Warning: Removing a lookup removes the joined data from query results. Modules or workflows that reference this query might break if they depend on the joined fields. This action cannot be undone.

Unions

Note: Unions are only available for Model queries. This feature is not available for Submission queries.

A union combines results from multiple queries into a single result set. Each union is a complete sub-query with its own data source, filters, lookups, sorting, projection, and limit.

When to Use Unions

Use unions when query results need to include records from multiple Data Models that share a similar structure, like the following:

• A report must combine Customer records from both a Domestic Customers Data Model and an International Customers Data Model.
• A search feature must retrieve records from multiple Data Models that all contain a name field.

Adding a Union

To add a union:

1. In the Union section, select Add Union.
2. Configure the union query using the same sections available for the main query: Data Source, Filter Builder, Lookups, Projection, Sort, and Limit.

Union results are appended to the main query results. The combined result set includes all records that match the main query, followed by all records that match each union query.

Union Field Compatibility

Union queries must return compatible fields. If the main query and a union query select different fields, the combined result set includes only the fields that exist in both queries.

Tip: Use the Projection section in each union to ensure field names and types align with the main query.

Removing a Union

To remove a union, select the delete icon at the right side of the union header.

Warning: Removing a union removes all records from that union query from the combined result set. This action cannot be undone.

Projection

The Projection section controls which fields display in query results. By default, queries return all fields from the data source. Creators can restrict the output to specific fields to improve performance or simplify the result structure.

Adding Fields to Projection

To add a field to the projection:

1. In the Projection section, select Add Field.
2. From the Field drop-down, select a field.

Only fields added to the projection list display in the query results. Fields not in the projection list are excluded.

Removing Fields from Projection

To remove a field from the projection, select the delete icon at the right side of the field row.

Clearing Projection

To return all fields in the query results, remove all fields from the projection list. An empty projection list means the query returns all available fields.

Sort

The Sort section controls the order of records in query results. By default, queries return records in the order they are stored in the data source.

Adding a Sort Rule

To add a sort rule:

1. In the Sort section, select Add Sort.
2. From the Field drop-down, select a field.
3. From the Direction drop-down, select Ascending or Descending.

Queries can sort by multiple fields. Records are sorted by the first field, then by the second field when the first field values are equal, and so on.

Removing a Sort Rule

To remove a sort rule, select the delete icon at the right side of the sort rule row.

Limit

The Limit section sets a maximum number of records the query returns. By default, queries return all records that match the configured filters.

Setting a Limit

To set a limit:

1. In the Limit section, enter a number in the Limit field.

The query returns at most the specified number of records. If fewer records match the filters, the query returns all matching records.

Removing a Limit

To remove a limit, clear the value in the Limit field. The query returns all matching records.

Preview

Note: Preview is only available in non-production environments. This feature is not available in production environments.

The Preview feature lets Creators test a query and view its results before referencing it in a module or workflow. Preview executes the saved query server-side and displays the results in a dialog.

Running a Preview

To run a preview:

1. In the query editor, select the (ellipsis) at the top right of the page.
2. Select Preview.
3. If the query includes variables, enter values for each variable in the Preview dialog.
4. Select Execute.

The Preview dialog displays the query results in a table. Each row represents a record. Each column represents a field.

Preview Limitations

Preview always executes the saved version of the query. Unsaved changes to the query are not reflected in preview results. Save the query before running a preview to test the latest changes.

Preview is limited to non-production environments. Creators working in production environments do not see the Preview option.

Saving Changes

The Query Builder automatically validates the query as Creators edit it. The Save Changes button is enabled when the query is valid and has unsaved changes.

A query is valid when all of the following are true:

• The query has a name.
• The query has a selected data source.
• All rules in the Filter Builder are complete. Incomplete rules have missing fields, operators, or values.
• All lookups have a source collection, foreign field, local field, and output field name.
• All union queries are valid. Each union must have a data source and complete filter rules.

When a required field is missing or a rule is incomplete, the Save Changes button is disabled. No inline error messages are displayed. Creators must complete the missing fields to enable saving.

Selecting Cancel discards all unsaved changes and reloads the query from its last saved state. This action cannot be undone.

Archiving a Query

Archiving a query removes it from the active query list. Archived queries are read-only and cannot be edited or previewed. Modules and workflows that reference an archived query continue to function, but Creators cannot modify the query logic.

To archive a query:

1. In the query editor, select the (ellipsis) at the top right of the page.
2. Select Archive.
3. In the confirmation dialog, select Archive.

The query is moved to the archived queries list and remains visible in the Query Builder folder with an archived badge.

Restoring an Archived Query

To restore an archived query:

1. In the Explorer panel, locate the archived query in the Query Builder folder. Archived queries display with an archived badge.
2. Select the archived query to open its detail page.
3. In the query editor, select the (ellipsis) at the top right of the page.
4. Select Restore.

The query is moved back to the active queries list and can be edited.

Deleting a Query

Deleting a query permanently removes it from the workspace.

Warning: Deleting a query is permanent and cannot be undone. Modules, workflows, or other workspace features that reference the deleted query will fail when they attempt to execute it. Verify that the query is not in use before deleting it.

To delete a query:

1. In the query editor, select the (ellipsis) at the top right of the page.
2. Select Delete.
3. In the confirmation dialog, enter the query name to confirm.
4. Select Delete.

The query is permanently removed from the workspace.

Permissions

Access to the Query Builder is controlled by workspace-level permissions. Creators must have the appropriate role to view, create, edit, or delete queries.

Creators without access to a query's data source cannot edit the query, even if they have Write permissions for the Query Builder. Data source access is checked separately.