# Queries

Commerce Layer Metrics API lets you retrieve metric data and statistics through four types of queries:

{% content-ref url="queries/breakdown" %}
[breakdown](https://docs.commercelayer.io/metrics/getting-started/queries/breakdown)
{% endcontent-ref %}

{% content-ref url="queries/date-breakdown" %}
[date-breakdown](https://docs.commercelayer.io/metrics/getting-started/queries/date-breakdown)
{% endcontent-ref %}

{% content-ref url="queries/stats" %}
[stats](https://docs.commercelayer.io/metrics/getting-started/queries/stats)
{% endcontent-ref %}

{% content-ref url="queries/search" %}
[search](https://docs.commercelayer.io/metrics/getting-started/queries/search)
{% endcontent-ref %}

{% content-ref url="queries/export" %}
[export](https://docs.commercelayer.io/metrics/getting-started/queries/export)
{% endcontent-ref %}

**Breakdown**, **date breakdown**, and **stats** queries return aggregated metrics computed on the values of specific fields, based on selected [operators](#query-operators). The **search** query is an actual *search*, returning the specified fields of the matching records. The **export** query enables you you to export the results of a search query as a CSV file.

{% hint style="info" %}
The examples in the following pages will be focused on the [query](https://docs.commercelayer.io/metrics/api-specification#query) part of the request. The `orders` endpoint will be used as a reference and no specific [filter](https://docs.commercelayer.io/metrics/api-specification#filter) or [meta](https://docs.commercelayer.io/metrics/api-specification#meta) options will be defined (i.e. all the results will be filtered by the [default filter](https://docs.commercelayer.io/metrics/filters#default-filter) and the response won't include the request payload). See the [use cases](https://docs.commercelayer.io/metrics/getting-started/use-cases) section for more complex combinations of queries and filters.
{% endhint %}

### Query operators

To perform [breakdown](https://docs.commercelayer.io/metrics/getting-started/queries/breakdown), [date breakdown](https://docs.commercelayer.io/metrics/getting-started/queries/date-breakdown), and [stats](https://docs.commercelayer.io/metrics/getting-started/queries/stats) queries you need to specify the operator you want to use to compute the calculation on the selected field. The valid operators depend on the field itself, hence on the resource you're doing statistics on. You can find here below the complete list of the available operators for the Metrics API queries (see the related tables to check the subset of valid operators by field for [orders](https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/orders/breakdown#operators-and-field-values), [returns](https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/returns/breakdown#operators-and-field-values), or [carts](https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/carts/breakdown#operators-and-field-values)).

| Operator          | Computed value type | Description                                                                                                                                                                                                                              |
| ----------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`avg`**         | Float               | A single-value metrics aggregation that computes the average of numeric values extracted from specific numeric fields of the aggregated records.                                                                                         |
| **`cardinality`** | Integer             | A single-value metrics aggregation that calculates an approximate count of distinct values.                                                                                                                                              |
| **`max`**         | Float               | A single-value metrics aggregation that keeps track and returns the maximum value among the numeric values extracted from specific numeric fields of the aggregated records.                                                             |
| **`min`**         | Float               | A single-value metrics aggregation that keeps track and returns the minimum value among the numeric values extracted from specific numeric fields of the aggregated records.                                                             |
| **`percentiles`** | Float               | A multi-value metrics aggregation that calculates one or more percentiles (i.e. the point at which a certain percentage of observed values occurs) over numeric values extracted from specific numeric fields of the aggregated records. |
| **`stats`**       | Object              | A multi-value metrics aggregation that computes stats over numeric values extracted from specific numeric fields of the aggregated records. The stats that are returned consist of: `count`, `min`, `max`, `avg`, and `sum`.             |
| **`sum`**         | Float               | A single-value metrics aggregation that sums up numeric values extracted from specific numeric fields of the aggregated records.                                                                                                         |
| **`value_count`** | Integer             | A single-value metrics aggregation that counts the number of values extracted from specific fields of the aggregated records.                                                                                                            |