---
title: Creating Queries
description: The following sections describe how to use the Query Tool. You can then create queries to use in Dashboards, Actions, and SmartLabels. Because queries allow you to find data in the Lucidum database, you might find it helpful to learn…
url: "https://lucidum.io/docs/creating-queries-2/"
updated: "2025-09-17"
category: Using Queries
---

# Creating Queries

The following sections describe how to use the Query Tool. You can then create queries to use in Dashboards, Actions, and SmartLabels.

Because queries allow you to find data in the Lucidum database, you might find it helpful to learn about and view the available date in Lucidum. For details about viewing the available data in Lucidum, see:

- [Viewing Details about Individual Assets, Users, or Vulnerabilities](https://lucidum.io/docs/viewing-details-about-individual-assets-users-or-vulnerabilities/)
- [Viewing Data About All Assets, All Users, and All Vulnerabilities](https://lucidum.io/docs/viewing-data-about-all-assets-all-users-and-all-vulnerabilities/)
- [Viewing Details About Data Sources for Assets and Users](https://lucidum.io/docs/viewing-details-about-data-sources-for-assets-and-users/)

## Accessing the Query Tool

To create a query, either click the button in the feature you are using or click the **Query** button in the upper right of any page in Lucidum.

- ***Charts in Dashboards***. Clicking the [**Configure Filters** button](https://lucidum.io/docs/creating-a-chart/#creating_a_chart_generic_steps) leads to the Query Tool.
- ***Actions***. Clicking the [**Configure Filters**](https://lucidum.io/docs/overview-of-actions/#create_a_new_action) button leads to the Query Tool.
- ***SmartLabels***. Clicking the [**Add Rule** or **Edit Rule**](https://lucidum.io/docs/creating-and-managing-smart-labels/#creating_a_smart_label_in_the_smart_label_management_page)button leads to the Query Tool.
- ***Dashboards***. Clicking the [**Refine Scope** icon](https://lucidum.io/docs/creating-queries-2/#creating_a_global_filer) leads to the Query Tool, where you can create a [global filter](https://lucidum.io/docs/creating-queries-2/#creating_a_global_filer) that applies a pre-filter to all charts in the dashboard.

1. The Query Tool appears.

   ![build_a_query1_updated.png](https://lucidum.cloud/docs/build_a_query1_updated.png)
2. The **Build a Query**page appears. In the **Build a Query**page, define the following fields:

   - **Type of Data.**This is the top-level category for each query and specifies the type of Lucidum object you want to get information about. Choices are:

     - *Asset*. Retrieve information about assets.
     - *Asset-IP Mapping*. Lucidum uses proprietary machine-learning algorithms to align each asset with an IP address. You can retrieve information about these asset/IP pairs.
     - *User. Retrieve information about users.*
     - *User-IP Mapping*. Lucidum uses proprietary machine-learning algorithms to align each user with an IP address. You can retrieve information about these user/IP pairs.
     - *Vulnerability*. Retrieve information about vulnerabilities.
   - **Time Range**. You must first select whether you are interested in current values or historic values. The choices are:

     - *Current*. The default value is from the present day to 7 days old.
     - *History*. Older than current.
              **NOTE**: You can customize or view the **Time Range** values in Settings > System Settings > Data Settings. *Current*uses the value of ***Data Lookback in Days***.
   -  
3. In the **Build a Query**page, click the **Next**button. The **Build a Current Asset Query** page appears.

   ![build_a_query_updated.png](https://lucidum.cloud/docs/build_a_query_updated.png)
4. Follow the steps in the section [Building the Query](https://lucidum.io/docs/building-queries/#operators/#building_the_query).

## Building the Query

1. In the both the **Build a Query** page and the **Configure Filters**pages, you follow the same steps to build a query.

   ![build_a_query2_updated.png](https://lucidum.cloud/docs/build_a_query2_updated.png)
2. Provide values in the following fields:

   - ***Field***. In this field, you select a field for the query. Fields are one or more properties of an asset or user, like first time seen”, “ip address”, “county code”, or “risk score”. For details about fields, see [the section on Fields](https://lucidum.io/docs/building-queries/#fields). Fields map to column names in a Lucidum database table. For a list of possible fields, see the chapter on [Fields and Regular Expressions](https://lucidum.io/docs/appendix-fields-and-regular-expressions)
   - ***Operators***. In this field, you select an Operator. Operators define the relationship between the fields and the values. The list of operators is dependent on the value you selected in ***Field***. For example, if you select a numeric field, the operators include "equals", "less than". For details on operators for each data type, see the [section on Operators](https://lucidum.io/docs/building-queries/#operators). For a list of possible operators, see [Data Types and Operators](https://lucidum.io/docs/appendix-data-types-and-operators/).
   - ***Values***. In this field, you select a value. The value is the value stored in a field. For example, if the field is "email", the value might be "ted.krilly@craggy.org". The list of available values is dependent on the value you selected in ***Field***and the value you selected in ***Operators**.*
3. For the example query in the screen capture above, we specified:

   - ***Type of Data***. *Asset*. We are interested in assets.
   - ***Time Range***. *Current*. We will collect data from the database for the current .
   - ***Field***. *Risk Score*. We will examine the field “Risk Score”.
   - ***Operator***. *is greater than or equal to*. Because the Operator field includes operators for numeric values, we know “Risk Score” is a numeric value. We are looking for values of “Risk Score” that are greater than or equal to the value in ***Value***.
   - **Value**. *15.65*. Lucidum populates the list of values with all the values for “Risk Score” in the assets table for the current . We chose 15.65. So we are looking for values of “Risk Score” that are greater than or equal to 15.65.
4. To see the results of the query, click the **Show Result** button. The **Query Result** page appears.

   ![query_results_updated.png](https://lucidum.cloud/docs/query_results_updated.png)

## Fields

The ***Types of Data***field specifies an object to examine. Choices are:

- Asset
- Asset-IP Mapping
- User
- User-IP Mapping
- Vulnerability

When building a query, ***Fields***are characteristics of the Lucidum objects. For example, characteristics of a user are the user’s name and email address. A characteristic of an asset is the asset’s IP address. Usually, a field maps to a column name in a Lucidum database.

Lucidum ingests information about assets, users, and data from your environment. Lucidum correlates that information and uses machine learning to enrich that information to provide you with details about assets, users, asset-IP mapping, user-IP mapping, and vulnerabilities.

For details on the standard list of fields in Lucidum and special characters you can use in queries, see the appendix on [Fields and Regular Expressions](https://lucidum.io/docs/appendix-fields-and-regular-expressions).

**NOTE**: The list of fields is dependent upon the data you have collected with Lucidum connectors.

The list of fields that appear in your Lucidum system are the fields you can use to build queries.

You might see fields in the appendix that don’t appear in your Lucidum system. This means that Lucidum has not fetched that data from your environment, either because you have not yet configured the connector or because your environment doesn’t include that type of asset.

You might see fields called “Extra Fields” in your Lucidum system that don’t appear in the list of fields in the appendix. This means that Lucidum has fetched data from your environment that is either specific to your environment or not available in all environments.

### Creating Favorite Fields

Lucidum allows you to add frequently used fields to a list of **Favorites**.

If you frequently use a field, you can click the star icon next to the field name. The field then appears in the **Favorite**category at the top of the list of fields.
![query_favorites_updated.png](https://lucidum.cloud/docs/query_favorites_updated.png)

## Operators

Operators define the relationship between the fields and the values.

Operators are dependent upon the data type.

For example:

- Numeric data includes operators like “is equal to” or “is greater than”.
- Date and time data includes operators like “within past”.
- Text data includes operators like “match” or “is equal to”.

For details on each data type and its operators, see the appendix on [Data Types and Operators](https://lucidum.io/docs/appendix-data-types-and-operators/).

## Values

The list of values is dependent on the Lucidum object, the Field, and the Operator. Lucidum populates the list of Values after you select a Lucidum object, Field, and Operator.

You can also use regular expressions in the Values field. For details, see the appendix on [Fields and Regular Expressions](https://lucidum.io/docs/appendix-fields-and-regular-expressions).

For example, if you selected the following:

- ***Build Query from***(Lucidum object). *Asset*
- ***Field***. *Risk Score*
- ***Operator***. is greater than or equal to
- ***Value***. *15.65*

The ***Build Query from*** field indicates that we are interested in *Assets*.

***Field***indicates that we want to retrieve assets with a specific *Risk Score*.

Because ***Operators*** includes operators for numeric values, we know *Risk Score*is a numeric value.

Lucidum populates the ***Values*** with all the numeric values for all *Risk Scores*in the *Assets*database table. In our example above, we chose *15.65*.

## Writing Queries that Use AND and OR

Lucidum allows you to create multi-part queries. To do this, you can use AND and OR keywords.
![build_a_query2_updated.png](https://lucidum.cloud/docs/build_a_query2_updated.png)

- The link for ***AND*** creates an AND condition.
- The link for ***OR***creates an OR condition.

### AND Condition

An AND condition specifies that Lucidum should retrieve all records that match all conditions. You can specify as many conditions as you choose.

For example:
![query_and_updated.png](https://lucidum.cloud/docs/query_and_updated.png)

This query specifies that we are interested in all assets:

- where the OS is Windows Server 2019

AND

- the department is HR

Any asset that matches both criteria will be included in the **Query Results** page.
![query_and_results_updated.png](https://lucidum.cloud/docs/query_and_results_updated.png)

- On this Lucidum system, 747 assets are running Windows Server 2019.
- However, only 44 assets have both are running Windows Server 2019 and are in the HR department.
- Therefore, the **Query Results** page displays 44 assets.

### OR Condition

An OR condition specifies that Lucidum should retrieve all records that match at least one of multiple conditions. You can specify as many conditions as you choose.

For example:
![query_or_condition_updated.png](https://lucidum.cloud/docs/query_or_condition_updated.png)

This query specifies that we are interested in all assets that:

- have an Operation System of Windows Server 2016

OR

- have an Operation System of Windows Server 2019

Any asset that matches either of these criteria will be included in the**Query Results** page.

For example, using the query above, the **Query Results** page looks like this:
![query_or_results_updated.png](https://lucidum.cloud/docs/query_or_results_updated.png)

- 722 assets are running Windows Server 2016
- 747 assets are running Windows Server 2019
- The **Query Results** page displays 1469 assets

## Viewing Query Results

The **Show Results** (checklist) icon opens the **Query Results** page. The **Query Results** page displays a table populated with the results of the query for the chart.

Using an example query:

- This query specifies that we are interested in all assets that:

  - have an OS and Version that matches Windows Server 2016

OR

- - have an OS and Version that matches Windows Server 2019
- Any asset that matches the criteria will be included in the **Query Results** page.
- For example, using the query above, the **Query Results** page looks like this:

  ![query_results_changed_fields.png](https://lucidum.cloud/docs/query_results_changed_fields.png)
- The **Query Results** page displays a list of assets that are running either Windows 2019 or Windows 2016.

  - You can sort the page by the column headings.
  - To see additional details about an asset, user, or vulnerability, click the > (right arrow) to see the **Details** page.
  - Notice the ***Changed Fields***column. If a value appears in this column, you can view details about the changed fields in the **Field Change History** tab in the **Viewing Details** page. These are the changed fields between the latest ingestion and the ingestion before the last ingestion.

**NOTE**: If a column displays a list/array value, the column will display:

- - ***Empty***. The field does not include a value.
  - ***One value***. The field includes a single value.
  - ***Count***: <number of values in the array>. The field includes multiple values. To view the list of values, click the > icon to view details about the record.

In the **Query Results** page, you can perform the following:
![query_results_column_actions.png](https://lucidum.cloud/docs/query_results_column_actions.png)

For the current page of results, you can:

- ***Columns***. Add or remove columns from the page.
- ***Export***. Download the results as a CSV file..

For each column name, you can:

- ***Sort by ASC***. Sort the results by this column, in ascending order.
- ***Sort by DESC***. Sort the results by this column, in descending order.
- ***Pin to left***. The column is pinned to the left border. When you scroll left to right to view all the columns, this column stays on the left border.
- ***Pin to right***. The column is pinned to the right border. When you scroll left to right to view all the columns, this column stays on the right border.
- ***Filter***. Allows you to filter the table by one or more columns in the results table.
- ***Hide Column***. Removes the column from the page.
- ***Manage columns***. You can include or not include one or more columns in the results table.

If you select one or more checkboxes in the **Query Results**page, you can also:

- ***Create a recurring action with this query***. Use the results of the query to create an action. Upon selecting this option, Lucidum displays the **Create a new action** page, where you can define the action. For details on actions, see [Actions](https://lucidum.io/docs/overview-of-actions/).
- ***Create a one-time action with selected data***. You can select one or more records and create an action that uses selected records and runs only once. For details on actions, see [Actions](https://lucidum.io/docs/overview-of-actions/).
- ***Assign a Tag***. Apply a tag. Tags are defined in the **Tag Management** page (Settings > Tag Management), can be manually applied to assets and users, and can be selected as a fields in a query. For details, see the section on [tags](https://lucidum.io/docs/overview-of-tags/) in the manual ***Streamlining Queries with Smart Labels and Tags***.

### Details page

In Lucidum, you can view details about the data for a single asset, user, or vulnerability. When we go to the row for asset MOSGOOD-ZXBTNV5 and click on click on the **>** icon, we see the **Details** page.
![building_queries_details_page_zxbtnv5.png](https://lucidum.cloud/docs/building_queries_details_page_zxbtnv5.png)

There are three types of data in Lucidum, all of which you can view in Lucidum and use in dashboards:

- ***Data Source**.*Data sources map to connectors. For each asset, user, and vulnerability, you can view all the data sources from which Lucidum ingested data about the asset, user, or vulnerability. You can select a Data Source to exactly see which raw data was provided by that data source.
- ***Lucidum Data Group***. Enriched data about assets, user, and vulnerabilities. Lucidum ingests data from multiple data sources and uses machine learning to enrich and normalize that data. The Lucidum Data Group tab allows you to view this enriched data for each asset, user, and vulnerability. Data in the Lucidum Data Group appears as fields in the **Query**tool.
- ***Field Change History***.  Displays fields that have changed, each field's current value and each field's previous value. These are the fields that have changed in the last seven days.

For more information on the **Details** page and its tabs, see [Viewing Details about Individual Assets, Users, or Vulnerabilities](https://lucidum.io/docs/viewing-details-about-individual-assets-users-or-vulnerabilities/ ‎).

## Exporting a Query to a .CSV File

From the **Query** button, you can export queries to a .CSV file for use in reports or analysis outside of Lucidum.

To do this:

1. [Create a query](https://lucidum.io/docs/building-queries/#creating_a_query) or choose a [Saved Query](https://lucidum.io/docs/saved-queries-and-historical-queries/#using_a_historical_query)or choose a query from [Query History](https://lucidum.io/docs/saved-queries-and-historical-queries/#using_a_historical_query).
2. To see the results of the query, click the **Show Result** button. The **Query Result** page appears.
3. In the **Query Results** page, click the **Export**icon in the upper right corner. Choose ***Export***.

   ![query_results_export.png](https://lucidum.cloud/docs/query_results_export.png)
4. The query and its results are saved to a .CSV file on your local computer.

## Using Saved Queries and Query History

The **Query**page includes fields for re-using queries:

- **Saved Query**. Leads to a list of saved queries. Saved queries are associated with your login. You cannot view the saved queries from other Lucidum users.
- **Query History**. Leads to a list of cached queries. Query history is not associated with your login but instead includes all queries from all Lucidum users on the current Lucidum system. Query history is deleted when the Lucidum system is rebooted or restarted.

For details on creating, using, and managing saved queries and historical queries, see [Saved Queries and Historical Queries](https://lucidum.io/docs/saved-queries-and-historical-queries/).

**NOTE**: Saved Queries are not dynamically updated. This means that if you include a Save Query in an Action or a Chart and then later update the definition of the Saved Query, the Action or Chart will continue to use the previous definition, not the updated definition.

## Using Smart Labels and Tags

Lucidum includes two types of user-defined, query-based fields to make repetitive tasks easier and to help organize assets and users. For details on creating, using, and managing Smart Labels and tags, see [Streamlining Queries with Smart Labels and Tags](https://lucidum.io/docs/introduction-to-tags-and-smart-labels/).

**NOTE**: Unliked Saved Queries, SmartLabels are dynamically updated. This means that if you include a SmartLabel in an Action or a Chart and then later update the definition of the SmartLabel, the Action or Chart will automatically use the updated definition.

## Creating a Global Filter for a Dashboard

A global filter is a parent filter that is applied to all queries and all charts in a specific Dashboard.

1. To create a global filter:
2. [Open the dashboard](https://lucidum.io/docs/viewing-a-dashboard/#viewing_a_dashboard) you want to add a filter to.

   ![global_filter1_updated.png](https://lucidum.cloud/docs/global_filter1_updated.png)
3. Click on the **Refine Scope**(funnel) button.
4. In the **Build a Query**page, [create a query](https://lucidum.io/docs/building-queries/#creating_a_query) as you normally would.

   ![global_filter_query_updated.png](https://lucidum.cloud/docs/global_filter_query_updated.png)
5. Click **Apply**to apply the query to all charts in the current dashboard.
6. The new filter appears to the left of the **Refine Scope**button.
7. The new filter is applied to all the charts and queries in the dashboard.

   ![global_filter2_updated.png](https://lucidum.cloud/docs/global_filter2_updated.png)
8. In our example, we created a query that filtered assets by the Country Code match United States. Notice how the value in the “Workstations” chart, the “Servers & VMn” chart, and the Containers & Microservices chart has changed after we applied the global filter. This is because all queries and charts include only assets with the Country Name “United States”.