---
title: "Visual Query Builder"
slug: "introduction-to-the-query-builder"
updated: 2025-12-10T19:46:46Z
published: 2025-12-10T19:46:46Z
canonical: "docs.unqork.io/introduction-to-the-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.

# Visual Query Builder

The Visual Query Builder tool enables Creators and administrators to target specific data captured by their [applications](/v1/docs/introduction-to-unqork-applications). The Visual Query Builder is similar to a SQL builder tool in that you create a logic statement to retrieve specific information from a database. The information can then be retrieved into a module using a [Plug-In](/v1/docs/plug-in-component) component.

The Visual Query Builder is optimized for accessing data stored against [Data Model schemas](/v1/docs/introduction-to-unqork-data-modeling), reducing the need to build complex data workflows for targeting and retrieving data.

## Benefits of the Visual Query Builder Tool

Retrieving data from an unstructured or large database can be a slow and inefficient process. In Unqork, utilizing [Data Models](/v1/docs/introduction-to-unqork-data-modeling) and the Visual Query Builder tool lets you retrieve and analyze data using SQL-like queries. With the Visual Query Builder, you build queries using logical and comparison operators on data fields. Then, you can reference these queries in a Plug-In component to retrieve data to display in a [Table](/v1/docs/vega-table-component) or [Grid](/v1/docs/grid-systems) component.

Benefits include the following:

- A simple-to-use interface for building and refining queries.
- Quickly build queries using logical and comparison operators to retrieve specific data without the need for complex data workflows.
- Optimize data retrieval time by targeting only the data you need.
- Easily refer to prebuilt queries using the Plug-In component in a module.

To learn more about the Visual Query Builder, click each of the tabs below:

Navigating the Visual Query BuilderCreate a Query

## Navigating the Visual Query Builder Tool

The Visual Query Builder tool is located at the Workspace level of your environment, under **Data Elements** to the left of the Workspaces page.

> [!WARNING]
> The Visual Query Builder tool requires Designer Administrator access to use.

### Accessing the Visual Query Builder Tool

To access the Visual Query Builder from the homepage:

1. Navigate to and select a **Workspace**.
2. From the left-side menu, under **Data Elements**, select Queries.

[![A static image displaying a Workspace, the Queries button is highlighted.](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/Query_Builder_Workspace_thumb_0_0.jpg?sv=2026-02-06&spr=https&st=2026-11-09T03%3A51%3A18Z&se=2026-11-09T04%3A51%3A18Z&sr=c&sp=r&sig=bdGewW%2Fsc6JC%2FkB2V7UAiz1DUR6pbE6ogcjC9LjO2UQ%3D)](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/Query%20Builder%20Workspace.jpg?sv=2026-02-06&spr=https&st=2026-11-09T03%3A51%3A18Z&se=2026-11-09T04%3A51%3A18Z&sr=c&sp=r&sig=bdGewW%2Fsc6JC%2FkB2V7UAiz1DUR6pbE6ogcjC9LjO2UQ%3D)

### Navigating the Queries Page

The Queries page displays a list of all active and archived queries in the workspace. From this page, you can create a new query and review, modify, or delete an existing one.

[![A static image displaying the Queries page.](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/Query_Builder_Queries_thumb_0_0.jpg?sv=2026-02-06&spr=https&st=2026-11-09T03%3A51%3A18Z&se=2026-11-09T04%3A51%3A18Z&sr=c&sp=r&sig=bdGewW%2Fsc6JC%2FkB2V7UAiz1DUR6pbE6ogcjC9LjO2UQ%3D)](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/Query%20Builder%20Queries.jpg?sv=2026-02-06&spr=https&st=2026-11-09T03%3A51%3A18Z&se=2026-11-09T04%3A51%3A18Z&sr=c&sp=r&sig=bdGewW%2Fsc6JC%2FkB2V7UAiz1DUR6pbE6ogcjC9LjO2UQ%3D)

| # | **Setting** | Description |
| --- | --- | --- |
| 1 | **+ Create Query** | Click to open the Create New Query page. |
|  | **Queries** | Displays a list of queries that exist in the workspace. |
| 2 | **Active Queries** | Sorts between active queries and archived queries. - **Active Queries**: Lists queries available to Creators in the workspace. Active queries be modified or archived to the Archived Queries list. - **Archived Queries**: Lists queries not available for use in [Plug-In](/v1/docs/plug-in-component) components or the workspace, but they can be modified or restored to the Actives Queries list. |
| 3 | **Name** | The name of the query. Click to view the query's logic page. |
| 4 | **Associated** **Data Model** **/** **Module** | The associated Data Model or module the query is using. Click to open the Data Model or module on a new page. |
| 5 | **Type** | Displays if the query is targeting submission data from a module or Data Model. |
| 6 | **Created** | The date and time when the query was created. This value is permanent and cannot be changed. |
| 7 | **Last Modified** | The date and time the query was last edited. This value changes whenever a query's logic is modified. |
| 8 | **Actions** | Click Archive to display a confirmation modal. Click **Yes, Archive** to move the query to the **Archived Queries** list. Archived queries can be modified, but cannot be used in a Plug-In component. To restore an archived query, set Active Queries to Archived Queries, then click Restore in the row of the query you want to restore. |

### Navigating the Create New Query Page

[![A static image displaying the Create New Query Page.](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/queryDashboard_thumb_0_0.jpg?sv=2026-02-06&spr=https&st=2026-11-09T03%3A51%3A18Z&se=2026-11-09T04%3A51%3A18Z&sr=c&sp=r&sig=bdGewW%2Fsc6JC%2FkB2V7UAiz1DUR6pbE6ogcjC9LjO2UQ%3D)](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/queryDashboard.jpg?sv=2026-02-06&spr=https&st=2026-11-09T03%3A51%3A18Z&se=2026-11-09T04%3A51%3A18Z&sr=c&sp=r&sig=bdGewW%2Fsc6JC%2FkB2V7UAiz1DUR6pbE6ogcjC9LjO2UQ%3D)

| # | **Setting** | Description |
| --- | --- | --- |
| 1 | **Last saved** | Displays the date and time the query was saved. If it is a new query, then it displays `never saved`. |
| 2 | **Name*** | Enter a name for the query. *This field is required to create a query. |
| 3 | **Query Type*** | Choose to query a Data Model or Submission Data. *This field is required to create a query. |
| 4 | **Data Model** **/** **Module******* | The associated Data Model or module that the query is using. Click to open the Data Model or module on a new page. *You must select a Data Model or module to create a query. |
| 5 | **Add Rule** | Creates a rule object inside the group object. The rule applies when querying the Data Model or module. Rules contain query parameters and logical operators that filter the Data Model or module's records. |
| 6 | **Add Group** | Creates a group object inside the original group. Each group can apply a different set of logical operators and contain rules. Groups can also contain another group. |
| 7 | **Logical Operators** | Logical operators are used to combine or manipulate the group conditions in a query. The Query Builder supports the following logical operators: **Not****:** Used to give the opposite result. For example, returning results for all clients that do **NOT** live in Canada. **And****:** Filters results on more than one condition. For example, returning results for all country names **AND** customer names that begin with the letter **S**. **Or****:** Filters results on one or more conditions. For example, returning results for all clients from Canada **OR** Mexico. |
| 8 | **Field** | Searches against record or data fields. Data Model data fields are defined in the model's schema. Submission Query data fields are defined in the module's submission data. > [!NOTE] > The Visual Query Builder tool's Submission Query fields are determined using the last 1,000 submissions. Modifying field IDs in a module might result in an older ID becoming unavailable in the Visual Query Builder tool. Queries can also search against record details, like the record ID, creation date, and so on. Submission Query record details include: - `_id:` The record's unique identifier. - `created:` The date and time the record was created. - `deleted:` The date and time the record was deleted. - `form:` The form's unique identifier. - `formArchive:` The form archive's unique identifier. - `isRevision:` If the record has a revision. - `metadata:` Data contained in the metadata array. This array can be empty. - `modified:` The date and time the record was last modified. - `moduleArchiveIdAtCreated:` The module archive's unique identifier at the time of creation. - `moduleArchiveIdAtModified:` The module archive's unique identifier after the last modification. This value can be NULL if the module has not been modified. - `owner:` The email address of the user who created the record. - `platformVersionAtCreated:` The platform version at the time of module creation. - `platformVersionAtModified:` The platform version after the last modification. This value can be NULL if the module has not been modified. - `validationErrors:` Data contained in the validationErrors array. This array can be empty. Model Query record details include: - `_id:` The record's unique identifier. - `created:` The date and time the record was created. - `modified:` The date and time the record was last edited. - `owner:` The email address of the user who created the record. - `archived:` Records that have been archived and are no longer active. |
| 9 | **Comparison Operator** | Comparison operators test the field against a constant string or variable name. Available comparison operators include: - `Is In:` Tests for values that are in the string. - `Is Not In:` Tests for values that are not inside the string. - `==` (**Equal To**): Tests for values that are equal to the string. - `!=` (**Not Equal To**): Tests for values that are not equal to the string. - `Contains:`Tests for values that contain the string. - `Not Contains:` Tests for values that do not contain the string. - `Starts With:` Tests for values that begin with the string. - `Ends With:` Tests for values that do not begin with the string. - `Is Empty:` Test for values containing empty strings. - `Is Not Empty:` Tests for all values that are not empty strings. - `Is Null:` Tests for NULL values. If a field in the submission data is optional, and its value is left blank, then the value is NULL. - `Is Not Null:` Tests for all values that are not NULL. |
| 10 | **Constant or Variable** | Choose if the field is a constant or a variable. Constants are predefined values, and variables are passed into the query from the [Plug-In](/v1/docs/plug-in-component) component's API call. |
| 11 | **Constant String or Variable Name** | The value of the constant or variable to filter by. |
| 12 | **Sort By** | When the query executes, choose what field the returned data sorts by. |
| 13 | **Sort Order** | When the query executes, choose the sorting order of the returned data. |
| 14 | **Projection** | Choose which fields to include in the response. By default, this setting includes all fields in the response. |
| 15 | **Populate From Another Collection** | Select an additional Data Model's data to include in the query. > [!NOTE] > Only Data Model collections are supported at this time. |
| 16 | **Default Limit** | Specify how many records are retrieved per query. The default maximum number of records retrieved at a time is 50. |
| 17 | **Join With Another Collection** | Include two or more data sets based on a related field. |

## Create and Use a Query

This example assumes you have a Data Model and some submission records to query against. For this example, the Data Model contains the fields **firstName** and **lastName**. Let's create a simple Data Model query that targets the **lastName** field. Then, use a [Plug-In](/v1/docs/plug-in-component) component to execute the query and display it in a [ViewGrid](/v1/docs/viewgrid-component) component.

#### What You Need

To configure a query, you need the following:

- 1 [Workspace](/v1/docs/introduction-to-workspaces) with Administrator access
- 1 [Data Model](/v1/docs/introduction-to-unqork-data-modeling)
- 1 [Module](/v1/docs/what-is-a-module)

### Creating a Query

> [!TIP]
> To learn more about using Schemas and Data Models, view our [Introduction to Data Modeling](/v1/docs/introduction-to-unqork-data-modeling) article.

To create a query targeting a field called **lastName**:

1. Navigate to the Workspace page of an application that has your Data Model and records data.

> [!WARNING]
> Creator Administrator access is required to access the Data Model and Visual Query Builder pages.
2. Select Queries to the left of the page.
3. Click **+ Create Query**.
4. In the **Name*** field, enter `Last Name Query`.
5. From the **Query Type*** drop-down, select **Model Query**. The **Data Model******* drop-down displays.
6. From the **Data Model******* drop-down, select the Data Model that contains the field you want to target.
7. Click **Add Rule****.** The **Not**, **And**, **Or**, and **Select Field** options display.
8. From the **Select Field** drop-down, select the **lastName** field.

> [!NOTE]
> The **lastName** field is specific to this example, but you can choose any field that is available in the Data Model.
9. From the **==** (**Comparison Operators**) drop-down, choose operators to test the field against. See the Comparison Operator list for operator descriptions.
10. Change the **Constant** drop-down to **Variable****.**
11. In the `Variable Name` field, enter `lastName`.
12. Click **Save Query**. The query **Id** field displays next to the query **Name*** field. You'll use the **Id** to execute the query in a Plug-In component.

> [!WARNING]
> Improperly configured queries produce [Status Code 500 - Server Error Response](/v1/docs/http-status-codes#server-error-responses) in the DevTools Console.

### Create a Last Name Search Dashboard

Build a dashboard to search for last names using the query you built in the Creating a Query steps. To build a dashboard, create a module in the same workspace as the query.

#### What You Need

To configure this module, you need:

- 1 [Text Field component](/v1/docs/text-field-component)
- 1 [Button component](/v1/docs/button-component)
- 1 [Plug-In component](/v1/docs/plug-in-component)
- 1 [Data Workflow component](/v1/docs/data-workflow-component)
- 1 [Hidden component](/v1/docs/hidden-component)
- 1 [ViewGrid component](/v1/docs/viewgrid-component)

#### Configure the Text Field Component

This [Text Field](/v1/docs/text-field-component) component lets end-users enter last names to filter by.

1. In the Module Builder, drag and drop a **T****ext Field** component onto the canvas.
2. In the **Property ID** field, enter `searchLastName`.
3. In the **Label Text** field, enter `Enter a Last Name`.
4. Click **Save Component**.

#### Configure the Button Component

The [Button](/v1/docs/button-component) component triggers the [Plug-In](/v1/docs/plug-in-component) component to use the query with the `searchLastName` **T****ext Field** component's value as its input.

1. Drag and drop a **Button** component onto your canvas, placing it below the `searchLastName` **T****ext Field** component.
2. In the **Property ID** field, enter `btnSearch`.
3. In the **Label Text** field, enter `Search`.
4. Navigate to the **Actions** settings.
5. Set the **Action Type** to **Event**.
6. In the **On Click** field, enter `plugGet`. You'll build the `plugGet` **Plug-In** component in the next step.

[![A static image displaying the Button component's Actions settings.](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/buttonGet_thumb_0_0.jpg?sv=2026-02-06&spr=https&st=2026-11-09T03%3A51%3A18Z&se=2026-11-09T04%3A51%3A18Z&sr=c&sp=r&sig=bdGewW%2Fsc6JC%2FkB2V7UAiz1DUR6pbE6ogcjC9LjO2UQ%3D)](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/buttonGet.jpg?sv=2026-02-06&spr=https&st=2026-11-09T03%3A51%3A18Z&se=2026-11-09T04%3A51%3A18Z&sr=c&sp=r&sig=bdGewW%2Fsc6JC%2FkB2V7UAiz1DUR6pbE6ogcjC9LjO2UQ%3D)
7. Click **Save Component**.

#### Configure the Plug-In Component

This [Plug-In](/v1/docs/plug-in-component) component targets the `searchConfigs` endpoint using a `Post` Request Type. You'll refer to the Query ID created during the Creating a Query steps.

1. Drag and drop a **Plug-In** component onto your canvas, placing it below the `btnSearch` **Button** component.
2. In the **Property ID** field, enter `plugGet`.
3. In the **Canvas Label Text** field, enter `plugGet`.
4. In the **Data Source URL** field, enter `fbu/uapi/searchConfigs/queryId/execute`, where `queryId` is the value displayed on the query's parameters page.
5. Set the **Request Type** to **Post**.

[![A static image displaying the Plug-In component's Data settings.](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/plugGet_thumb_600_0.jpg?sv=2026-02-06&spr=https&st=2026-11-09T03%3A51%3A18Z&se=2026-11-09T04%3A51%3A18Z&sr=c&sp=r&sig=bdGewW%2Fsc6JC%2FkB2V7UAiz1DUR6pbE6ogcjC9LjO2UQ%3D)](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/plugGet.jpg?sv=2026-02-06&spr=https&st=2026-11-09T03%3A51%3A18Z&se=2026-11-09T04%3A51%3A18Z&sr=c&sp=r&sig=bdGewW%2Fsc6JC%2FkB2V7UAiz1DUR6pbE6ogcjC9LjO2UQ%3D)
6. In the **Inputs** table, enter the following:

|  | Property ID | Mapping |
| --- | --- | --- |
| 1 | **searchLastName** | lastName |
7. Navigate to the **Actions** settings.
8. In the **Post Trigger** field, enter `dwfSet`. You'll build the **dwfSet** **D****ata Workflow** component next.
9. Click **Save Component**.

#### Configure the Data Workflow Component

The [Data Workflow](/v1/docs/data-workflow-component) component retrieves the data from the `plugGet` **Plug-In** component and sends it to a [Hidden](/v1/docs/hidden-component) component so the [ViewGrid](/v1/docs/viewgrid-component) component can reference it.

1. Drag and drop a **D****ata Workflow** onto the canvas, placing it below the `plugGet` **Plug-In** component.
2. In the Property ID field, enter `dwfSet`.
3. In the Label Text field, enter `dwfSet`.

##### Configure the Input Operator

The [Input](/v1/docs/input-operator) operator brings the data from the `plugGet` **Plug-In** component into the Data Workflow component.

1. Drag and drop an **Input** operator onto your **D****ata Workflow** canvas.
2. Configure the operator's **Info** window as follows:

| Info |
| --- |
| Category | Input |
| Component | plugGet |
| Required | Yes |
| Source | Default |

##### Configure the Output Operator

The [Output](/v1/docs/output-operator) operator sends the data to the **hiddenRecords** **H****idden** component to store it.

1. Drag and drop an **Output** operator onto your **D****ata Workflow** canvas.
2. Configure the operator's **Info** window as follows:

| Info |
| --- |
| Category | Output |
| Component | hiddenRecords |
| Action | value |
3. Connect the output port (right) of the `plugGet` **Input** operator to the input port (left) of the `hiddenRecords` **Output** operator.
4. Click **Save Component**.

Your completed Data Workflow looks like the following:

[![A static image displaying the dwfSet component's settings.](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/dwf_thumb_500_0.jpg?sv=2026-02-06&spr=https&st=2026-11-09T03%3A51%3A18Z&se=2026-11-09T04%3A51%3A18Z&sr=c&sp=r&sig=bdGewW%2Fsc6JC%2FkB2V7UAiz1DUR6pbE6ogcjC9LjO2UQ%3D)](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/dwf.jpg?sv=2026-02-06&spr=https&st=2026-11-09T03%3A51%3A18Z&se=2026-11-09T04%3A51%3A18Z&sr=c&sp=r&sig=bdGewW%2Fsc6JC%2FkB2V7UAiz1DUR6pbE6ogcjC9LjO2UQ%3D)

#### Configure the Hidden Component

The [Hidden](/v1/docs/hidden-component) component stores the data retrieved from the Data Workflow component. The [ViewGrid](/v1/docs/viewgrid-component) component uses the Hidden component to reference the query data.

1. Drag and drop a **H****idden** component onto the canvas, placing it below the **dwfSet** **D****ata Workflow** component.
2. In the **Property ID** field, enter `hiddenRecords`.
3. In the **Label Text** field, enter `hiddenRecords`.
4. Click **Save Component**.

#### Configure the ViewGrid Component

The [ViewGrid](/v1/docs/viewgrid-component) component displays the data stored in the **records****H****idden** component.

1. Drag and drop a **ViewGrid** component onto the canvas, placing it below the `hiddenRecords` **H****idden** component.
2. In the **Property ID** field, enter `vgRecords`.
3. In the **Canvas Label Text** field, enter `vgRecords`.
4. In the **Inputs** table, enter the following:

| # | id | required |
| --- | --- | --- |
| 1 | hiddenRecords | ☐ (unchecked) |
5. In the **Display** table, enter the following:

|  | id | formula | heading |
| --- | --- | --- | --- |
| 1 | id |  | Record ID |
| 2 | firstName |  | First Name |
| 3 | lastName |  | Last Name |

[![A static image displaying the View Grid component's Input and Display settings.](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/viewGrid_thumb_0_0.jpg?sv=2026-02-06&spr=https&st=2026-11-09T03%3A51%3A18Z&se=2026-11-09T04%3A51%3A18Z&sr=c&sp=r&sig=bdGewW%2Fsc6JC%2FkB2V7UAiz1DUR6pbE6ogcjC9LjO2UQ%3D)](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/viewGrid.jpg?sv=2026-02-06&spr=https&st=2026-11-09T03%3A51%3A18Z&se=2026-11-09T04%3A51%3A18Z&sr=c&sp=r&sig=bdGewW%2Fsc6JC%2FkB2V7UAiz1DUR6pbE6ogcjC9LjO2UQ%3D)
6. Navigate to the **Actions** settings.
7. In the **Action** field, enter `null`.
8. Click **Save Component**.
9. **Save** your module

Preview your module in Express View. You'll see the following functionality:

[Video](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/Query_Builder_ExpressView(1).webm?sv=2026-02-06&spr=https&st=2026-11-09T03%3A51%3A18Z&se=2026-11-09T04%3A51%3A18Z&sr=c&sp=r&sig=bdGewW%2Fsc6JC%2FkB2V7UAiz1DUR6pbE6ogcjC9LjO2UQ%3D)

Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform.

SQL (Structured Query Language) is language used in programming and designed for managing data contained in a relational database system.

A query lets you retrieve, access, manipulate, and delete data in a database.

Also known as Record Data. Submission data consists of information saved by Unqork components. View submission data by using the angular command, or in Record Collections.

A modal is a window that appears on top of the content you are currently viewing.

APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services.

The DevTools Console helps you securely store, build, test, and deploy your software.

End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.

A Property ID is the unique field ID used by Unqork to track and link components in your module.

Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field.

Canvas Label Text indicates the purpose of the corresponding field or component. For non-input components, the Canvas Label Text isn't end-user facing, and only appears in the .

Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View.