---
name: cloud-logs-query-about
title: About running queries in IBM Cloud Logs
description: 'Consider the following information when you run a query in IBM Cloud Logs:'
last-updated: 2026-11-03
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/cloud-logs?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# About running queries in IBM Cloud Logs
{: #query-about}

Consider the following information when you run a query in IBM Cloud Logs:
{: shortdesc}

## About the data in IBM Cloud Logs
{: #query-about-data}

Logs that are ingested and stored in IBM Cloud Logs in the Priority insights backend or in your IBM Cloud Object Storage (COS) bucket are referred as raw data.

When you build a query using Lucene or DataPrime or use widgets inside a custom dashboard, you get raw logs before you apply any transformations. For example, when you first drag a Dynamic Widget onto a dashboard, it opens in a table view displaying raw data in JSON format.

When you apply transformations that combine responses into a summary form such as percentages or totals, the data returned by the query is known as aggregated data.

In IBM Cloud Logs, you aggregate data by using the DataPrime query language to transform raw logs into aggregated data. For example, you can aggregate data by using any of the following aggregation methods:

- *Global Aggregation method*: Use this method to compute totals, averages, minimums, maximums, or counts as a single group using the aggregate command. For more information, see [DataPrime aggregation expressions](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-dataprime-ref-expressions-agg&format=markdown).

- *Grouping Data method*: Use this method to split data into distinct categories or shared values using the groupby command. For more information, see [Group by](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-dataprime-ref-operators&format=markdown#groupby).

- *Multi-Grouping method*: Use this method to combine multiple grouping statements or concatenate queries using multigroupby for efficient single-scan execution. For more information, see [multigroupby](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-dataprime-ref-operators&format=markdown#multigroupby).



### Using large numeric values in IBM Cloud Logs
{: #query-about-8}

DataPrime supports numeric values up to a maximum of `2^53` (9,007,199,254,740,992). Using larger numbers may result in precision loss or unexpected behavior in queries.
{: note}

Limitations in binary precision as defined by the IEEE 754 standard may cause certain decimal values to be **stored or displayed imprecisely**, even if they appear simple.


### Keyword data type in search queries in IBM Cloud Logs
{: #query-data-ui-explorer-keyword}

Keywords represent text that does not pass through the analyzer before indexing.

The keyword data type is suitable for regular expressions, aggregation, and sorting. For more information, see [Using RegEX to query data](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-query-regex&format=markdown).

The syntax to use the keyword data type in your query is:

```text
<fieldName>.keyword
```
{: codeblock}

IBM Cloud Logs can not create a keyword type when a field is longer than 256 characters.
{: important}


### Quering an empty array in IBM Cloud Logs
{: #query-about-7}

When you run a DataPrime query on Priority insights data, the query is translated into a Lucene query by the DataPrime engine.

In Lucene, an empty array is treated the same as a key with a value. In DataPrime, an empty array is treated as a `null` value. Depending on how you write your query, you might encounter inconsistencies running the query.

To work with empty arrays and avoid inconsistencies running the same query in *Priority Insights* or *All Logs*, use the following syntax to explicitly check the array length instead of relying on `null`:

```text
filter arrayLength($d.my_array) == 0
```
{: codeblock}


Do not use the following syntax:

```text
filter $d.my_array == null
```
{: codeblock}



##  Considerations when querying Priority insights data
{: #query-about-frequent-search}

There are considerations when querying log data in the IBM Cloud Logs Priority insights pipeline:

- You can query logs that are ingested and processed through the [Priority insights data pipeline](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-tco-optimizer&format=markdown) by using a Lucene query or a DataPrime query.
- Filtering can be used in conjunction with searching using [Lucene](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-query-data-lucene&format=markdown) or [DataPrime](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-query-data-dataprime&format=markdown).
- Logs in the [Priority insights pipeline](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-tco-optimizer&format=markdown) are indexed. If your instance reaches its maximum amount of indexed fields, additional fields are unavailable to query. For more information on indexing and data mapping, see [Understanding indexing and field mapping](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-indexing_mapping&format=markdown).
- You can get a mapping exception when data that is ingested through the Priority insights data pipeline detects the same field sent by different log records with different types. Mapping exceptions make fields unavailable to query. For more information, see [Mapping exceptions](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-query-mapping-exceptions&format=markdown).


## Refining query results (recommendations building queries)
{: #query-about-refine-query}

In IBM&reg; Cloud Logs, you can refine a query by adding filters, narrowing timeframes, using dynamic variables, creating parsing rules, and using exact matches.

For more information, see [Refining query results in IBM Cloud Logs](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-query-refine&format=markdown).


## Querying data through the UI in IBM Cloud Logs
{: #query-about-ui-ov}
{: ui}

In IBM Cloud Logs, you can query data in the UI through the *Explorer Logs* page, a custom dashboard, or by running an archive query. You can query log data by using Lucene queries, DataPrime queries, or by querying directly data from an IBM Cloud Object Storage (COS) bucket.

You can also apply [filtering](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-query-data-filter&format=markdown) in conjunction with searching using Lucene or DataPrime.

After you define a query, you can save it for later reuse by creating a view. For more information, see [Launching views](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-custom_views&format=markdown#custom_views_launch) and [Creating custom views](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-custom_views&interface=ui&format=markdown#create_view){: external}.

### Querying data synchronously through the Logs Explorer UI in IBM Cloud Logs
{: #query-about-ui-explorer}
{: ui}

In IBM Cloud Logs, you can query data through the *Logs Explorer* page by using any of the following options:

- You can monitor Priority insights data through the *Priority Insights* option.

- You can monitor data through the *All Logs* option that is available in the COS data bucket and ingested through any data pipeline.

- You can [search log data by using Lucene queries](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-query-data-lucene&format=markdown)

- You can [search log data by using DataPrime queries](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-query-data-dataprime&format=markdown)

### Querying data asynchronously through the UI in IBM Cloud Logs
{: #query-about-ui-archive}
{: ui}

In IBM Cloud Logs, you can query data asynchronously that is stored in the IBM Cloud Object Storage data bucket through the **Logs Explorer > Archive** page.



## Querying data by using CLI commands in IBM Cloud Logs
{: #query-about-cli-ov}
{: cli}

In IBM Cloud Logs, you can query log data synchronously by using the `ibmcloud logs query` CLI commands or asynchronously by using the `ibmcloud logs background-query` commands.


### Querying data asynchronously by using CLI commands in IBM Cloud Logs
{: #query-about-cli-ov-1}
{: cli}

In IBM Cloud Logs, you can query log data asynchronously by using the `ibmcloud logs background-query` commands.

The background query lets you run a query and fetch the results at a later point in time. The query results are prepared and, once ready, you can download the results as a file using the CLI or the API.

With the background query up to 1M records can be returned.

For more information, see [Managing background queries through the CLI](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-query-background&interface=cli&format=markdown#query-background-cli){: external}.


### Querying data synchronously by using CLI commands in IBM Cloud Logs
{: #query-about-cli-ov-2}
{: cli}

In IBM Cloud Logs, you can query log data synchronously by using the `ibmcloud logs query` CLI commands.

The `query` command is limited to returning 50K records.

For more information, see [Running synchronous queries through the CLI in IBM Cloud Logs](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-query-synch&format=markdown#query-sync-ov-cli).

## Querying data by using the API in IBM Cloud Logs
{: #query-about-api-ov}
{: api}

In IBM Cloud Logs, you can query log data synchronously by using the method `POST /v1/query` or asynchronously by using the method `POST /v1/background_query`.


### Querying data asynchronously by using the API in IBM Cloud Logs
{: #query-about-api-ov-1}
{: api}

In IBM Cloud Logs, you can query log data asynchronously by using the method `POST /v1/background_query`.

The background query lets you run a query and fetch the results at a later point in time. The query results are prepared and, once ready, you can download the results as a file using the CLI or the API.

With the background query up to 1M records can be returned.

For more information, see [Managing background queries through the API](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-query-background&interface=cli&format=markdown#query-background-api).

### Querying data synchronously by using the API in IBM Cloud Logs
{: #query-about-api-ov-2}
{: api}

In IBM Cloud Logs, you can query log data synchronously by using the method `POST /v1/query`.

The `query` command is limited to returning 50K records.

For more information, see [Running synchronous queries through the API in IBM Cloud Logs](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-query-synch&format=markdown#query-sync-ov-api).