--- title: "Query Builder" slug: "query-builder" tags: ["workspaces"] updated: 2026-09-15T19:58:53Z published: 2026-09-15T19:58:53Z canonical: "docs.unqork.io/query-builder" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.unqork.io/llms.txt > Use this file to discover all available pages before exploring further. # 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 must 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 the following 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 UnqorkAI 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 | Field | Description | | --- | --- | | **Query Name** | The display name of the query. Creators can edit this field to rename the query. | | **Query Type** | The query type: **Model Query** or **Submission Query**. This field cannot be changed after the query is created. | | **Data Source** | The Data Model or application module from which the query retrieves data. Once a query is saved with a data source selected, this field is locked and cannot be changed. To use a different data source, create a new query. | | **Query ID** | The unique identifier for this query. This field is read-only. | ## 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 the following constructs: - **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. > [!CAUTION] > 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: | Field Type | Available Operators | | --- | --- | | Text | `==`, `!=`, Contains, Not contains, Starts with, Ends with, Is in, Is not in, Contains (Case Insensitive), Not Contains (Case Insensitive), Is empty, Is not empty, Is null, Is not null | | Number | `==`, `!=`, `<`, `<=`, `>`, `>=`, Between, Not between, Is null, Is not null | | Date | `==`, `!=`, `<`, `<=`, `>`, `>=`, Between, Not between, Is null, Is not null | | Boolean | `==`, `!=`, Is null, Is not null; the value widget displays **Yes** and **No** options | | Select (single-select) | `==`, `!=`, Is null, Is not null | | Select (multi-select) | Is in, Is not in, Is null, Is not null | ## Lookups > [!NOTE] > Lookups are only available for Model 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 must return 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: | Setting | Description | | --- | --- | | **Limit** | Caps the number of joined records included per result record. By default, all matching records are included. | | **Projection** | Restricts which fields from the source Data Model are included in the joined data. By default, all fields are included. | | **Sort** | Controls the order of joined records when multiple records match. | ### Removing a Lookup To remove a lookup, select the delete icon at the right side of the lookup row. > [!CAUTION] > 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. 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 must return 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. > [!CAUTION] > 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. ## Query Actions The ![EllipsisVertical](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9ImN1cnJlbnRDb2xvciIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPjxjaXJjbGUgY3g9IjEyIiBjeT0iMTIiIHI9IjEiLz48Y2lyY2xlIGN4PSIxMiIgY3k9IjUiIHI9IjEiLz48Y2lyY2xlIGN4PSIxMiIgY3k9IjE5IiByPSIxIi8+PC9zdmc+) (**ellipsis**) on each query row in the Explorer panel and at the top right of the query detail page opens the query actions menu. The following actions are available: | Action | Description | Who can use it | | --- | --- | --- | | **Copy ID** | Copies the query's unique ID to the clipboard. | All Creators with access to the workspace | | **Copy Name** | Copies the query's display name to the clipboard. | All Creators with access to the workspace | | **Copy Link** | Copies a direct link to the query to the clipboard. | All Creators with access to the workspace | | **Preview** | Executes the query and displays results. Available in non-production environments only. | Creators with write access | | **Archive** | Moves the query to the archived list. Displays only on active queries. | Creators with write access | | **Restore** | Moves the query back to the active list. Displays only on archived queries. | Creators with write access | | **Delete Query** | Permanently removes the query. Requires confirmation. | Creators with delete access | ## Preview > [!NOTE] > Preview is only available in non-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 ![EllipsisVertical](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9ImN1cnJlbnRDb2xvciIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPjxjaXJjbGUgY3g9IjEyIiBjeT0iMTIiIHI9IjEiLz48Y2lyY2xlIGN4PSIxMiIgY3k9IjUiIHI9IjEiLz48Y2lyY2xlIGN4PSIxMiIgY3k9IjE5IiByPSIxIi8+PC9zdmc+) (**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 moves it from the active query list to the archived query list. Archived queries can still be opened and edited. Archiving does not change edit permissions. The only behavioral difference is the ellipsis menu displays **Restore** instead of **Archive**. Modules and workflows that reference an archived query continue to function. To archive a query: 1. In the query editor, select the ![EllipsisVertical](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9ImN1cnJlbnRDb2xvciIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPjxjaXJjbGUgY3g9IjEyIiBjeT0iMTIiIHI9IjEiLz48Y2lyY2xlIGN4PSIxMiIgY3k9IjUiIHI9IjEiLz48Y2lyY2xlIGN4PSIxMiIgY3k9IjE5IiByPSIxIi8+PC9zdmc+) (**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 ![EllipsisVertical](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9ImN1cnJlbnRDb2xvciIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPjxjaXJjbGUgY3g9IjEyIiBjeT0iMTIiIHI9IjEiLz48Y2lyY2xlIGN4PSIxMiIgY3k9IjUiIHI9IjEiLz48Y2lyY2xlIGN4PSIxMiIgY3k9IjE5IiByPSIxIi8+PC9zdmc+) (**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. > [!CAUTION] > 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 ![EllipsisVertical](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9ImN1cnJlbnRDb2xvciIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPjxjaXJjbGUgY3g9IjEyIiBjeT0iMTIiIHI9IjEiLz48Y2lyY2xlIGN4PSIxMiIgY3k9IjUiIHI9IjEiLz48Y2lyY2xlIGN4PSIxMiIgY3k9IjE5IiByPSIxIi8+PC9zdmc+) (**ellipsis**) at the top right of the page. 2. Select **Delete Query**. 3. In the confirmation dialog, 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. | Permission Level | Capabilities | | --- | --- | | **Read-Only** | View queries. Cannot create, edit, archive, or delete queries. The query editor displays in view-only mode. | | **Write** | Create, edit, archive, restore, and delete queries. Preview queries in non-production environments. | | **No Access** | Cannot view or access the Query Builder. | 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. --- **Changelog** | Date | Change | | --- | --- | | 2026-08-21 | Moved Query Block component section to standalone Query Component article. | | 2026-08-20 | Added Query Block component section (Description, Configuration, Outputs, Triggers). | | 2026-09-15 | Added Query Actions section (Copy ID, Copy Name, Copy Link); corrected operator table (symbols, Is null/not null, Boolean, single vs. multi-select); fixed archived query claim — editing is not blocked; added data source lock note (EN-8056). | | 2026-08-04 | Initial publication. | A query lets you retrieve, access, manipulate, and delete data in a database. Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. A query lets you retrieve, access, manipulate, and delete data in a database. A functionality of a software. For example, Copy and Paste is a feature of a computer's operating system. The Number data type accepts integer or floating point values. The number data type does not use quotes around numerical values. Data types are a classification of data that determines how it is stored and interpreted. The Boolean data type accepts one of two values: true, or, false. SQL (Structured Query Language) is language used in programming and designed for managing data contained in a relational database system. A place on your operating system that stores recently copied content. The clipboard only stores one item at a time. Enter outputs components and actions you want the component to perform.