---
title: Query the Metric data type
source: https://docs.newrelic.com/docs/data-apis/understand-data/metric-data/query-metric-data-type
---

When metrics are reported to New Relic via the [Metric API](https://docs.newrelic.com/docs/data-ingest-apis/get-data-new-relic/metric-api/introduction-metric-api) (including from integrations that use that API), the data is reported as the [`Metric` data type](https://docs.newrelic.com/docs/data-apis/understand-data/metric-data/metric-data-type) and is available for querying.

This doc explains:

-   How to [view and query your metrics](#view-and-query)
-   [Example metric queries](#example-metric-queries)
-   How to [query multiple metrics with wildcards](#query-multiple-metrics-wildcards)
-   How to [explore metric data](#explore-metric-data)

## Query APM metric timeslice data [#metric-timeslice]

APM reports a specific type of data that we call metric timeslice data. For how to query that, see [Query metric timeslice data](https://docs.newrelic.com/docs/query-data/nrql-new-relic-query-language/nrql-query-tutorials/query-metric-timeslice-data-nrql).

> #### ⚠️ IMPORTANT
>
> You cannot query timeslice metrics in conjunction with dimensional metrics or event data. Any query involving `newrelic.timeslice.value` or an `apm.*` metric can only return APM metrics.

For information about other types of metrics, see [Metric data types](https://docs.newrelic.com/docs/using-new-relic/data/understand-data/new-relic-data-types#metrics-new-relic).

## View and query your metrics [#view-and-query]

You can use [NRQL](https://docs.newrelic.com/docs/query-data/nrql-new-relic-query-language/getting-started/introduction-nrql) to query your metric data in the [query builder](https://docs.newrelic.com/docs/chart-builder/use-chart-builder/get-started/introduction-chart-builder) or using our [NerdGraph API](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph).

To query a metric, you can use the following query format:

```sql
FROM Metric SELECT function(metric_name) WHERE attribute=value FACET attribute TIMESERIES
```

For information about what functions are supported for what metric data types, see [Metric data structure](https://docs.newrelic.com/docs/data-apis/understand-data/metric-data/metric-data-type).

Add the names of the metrics you want to chart with the appropriate value functions in the `SELECT` clause. The `WHERE` and `FACET` clauses can be used with attribute values. Remember to include the keyword `TIMESERIES` if you want to chart the data.

This example demonstrates how you could chart the CPU usage in seconds for cluster `foo` . This query breaks down CPU usage by container, given a `count` metric named `container_cpu_usage_seconds_total` with the attributes `containerName` and `clusterName`:

```sql
FROM Metric SELECT sum(container_cpu_usage_seconds_total) 
WHERE clusterName = 'foo' 
FACET containerName 
TIMESERIES
```

If you want the CPU usage per minute (the rate of change), then you can add the rate function to the query above.

```sql
FROM Metric SELECT rate(sum(container_cpu_usage_seconds_total), 1 minute) 
WHERE clusterName = 'foo' 
FACET containerName 
TIMESERIES
```

## View example metric queries [#example-metric-queries]

The previous examples demonstrate basic forms of metric queries, but NRQL can also be used to chart, explore, and analyze metric data.

**Chart multiple metrics**

Chart multiple metrics using a single query by providing a comma-separated list of metrics in the `SELECT` clause. For example, to chart the memory usage for a container along with the memory limit metric, use the following query:

````sql
FROM Metric 
SELECT latest(container_memory_usage_bytes), latest(container_spec_memory_limit_bytes) 
WHERE containerName = 'inventory' 
TIMESERIES
```

You can also do this using [wildcards](#query-multiple-metrics-wildcards), as explained below.

````

**Perform mathematical operations on metric data**

Perform math operations on one or more metrics to compute a new, derived metric. To monitor available memory, you can calculate the percentage of available memory from the two metrics used in the previous example:

````sql
FROM Metric 
SELECT (latest(container_spec_memory_limit_bytes) - latest(container_memory_usage_bytes)) 
  / latest(container_spec_memory_limit_bytes) 
  * 100 
  AS '% Memory Available' 
WHERE containerName = 'inventory' 
TIMESERIES
```

You can also do this using [wildcards](#query-multiple-metrics-wildcards), as explained below.

````

**Use filters to select specific time series**

In addition to using a `WHERE` clause which applies to everything in `SELECT`, NRQL provides another aggregation function called `filter` which can be used to select a specific time series to be charted or operated on.

The following example charts a memory usage metric labeled `"Total (k8s)"` which is computed by adding together the memory usage of two specific containers within a pod:

````sql
FROM Metric 
SELECT filter(
  latest(container_memory_usage_bytes), 
  WHERE containerName = 'discovery') 
+ filter(
  latest(container_memory_usage_bytes), 
  WHERE containerName = 'my-proxy') 
AS 'Total (k8s)' 
WHERE clusterName = 'my-cluster' AND podName LIKE 'my-pilot-%' 
TIMESERIES
```

````

**View the raw metric data points**

When querying metric data using `FROM Metric`, New Relic automatically selects the specific aggregate to use in the query, depending on the length of the query window and any bucket size specified as an argument to the `TIMESERIES` keyword. This ensures efficient querying and chart resolution. If you want to override this behavior to view or operate on the raw metric data points, use the optional `RAW` keyword in your query.

When querying these raw metric data points, there is a query time window limit of 48 hours. Any query attempting to access more than 48 hours of raw metric data will result in a query error.

This example shows how to list the last 20 data points received for a particular metric:

````sql
FROM Metric SELECT * WHERE metricName = 'container_fs_usage_bytes' LIMIT 20 RAW
```

````

## Query multiple metrics with wildcards [#query-multiple-metrics-wildcards]

Wildcards are represented in NRQL by the `%` character. If you want to query multiple metrics that use a standard naming convention, you can use the wildcard feature to return results for all of them without having to specify each metric name individually.

Wildcards can help you:

-   Aggregate metrics together and chart the results
-   `FACET` results by metric name in a chart
-   Find and chart all metrics matching a given naming convention

Wildcards are particularly helpful if you later add new metrics matching an existing naming convention. By using `%` instead of writing out each metric name in your query, you won't have to rewrite the query when you add new metrics.

Let's say you have multiple algorithms that perform a similar task. You can define the following metrics, which show the duration of the different algorithms:

-   `myNeatProcess.algorithm1.duration`
-   `myNeatProcess.algorithm2.duration`
-   `myNeatProcess.algorithm3.duration`

If used in a query, `myNeatProcess.%.duration` will return results for all three of the algorithms above. If you later create new algorithms named `algorithm4`, `algorithm5`, and `algorithm6`, the same query will return results for all six algorithms.

**Chart multiple metrics with wildcards**

You can chart multiple metrics using a single query by using wildcards (`%`) in the `SELECT` clause. For example, to query all the algorithms in the example above and plot a line on the chart for each algorithm's average duration, use the following query:

````sql
FROM Metric 
SELECT average(myNeatProcess.%.duration) 
FACET metricName TIMESERIES
```

````

**Perform mathematical operations on metric data with wildcards**

You can also use wildcards to perform math operations on multiple metrics and compute a new metric. You can calculate the mean duration for all algorithms listed in the example above:

````sql
FROM Metric 
SELECT average(myNeatProcess.%.duration) 
TIMESERIES
```

You can calculate what percentage of overall runtime a single algorithm takes:

```sql
FROM Metric 
SELECT myNeatProcess.algorithm1.duration / sum(myNeatProcess.%.duration) 
TIMESERIES
```

````

## Return results for individual fields using `getField()` [#use-getField]

There are [multiple types of `Metric` data](https://docs.newrelic.com/docs/data-apis/understand-data/metric-data/metric-data-type/#metric-types) (for example, `gauge` and `count`) and each type has several associated **fields**. For details on the types of fields available, see [`getField()`](https://docs.newrelic.com/docs/query-your-data/nrql-new-relic-query-language/get-started/nrql-syntax-clauses-functions/#func-getfield).

You can use `getField()` to extract those fields. For example, if you want to use a single value within a metric to do a comparison in a `WHERE` clause, you can use `getField(metricName, field)` or the shorthand syntax `metricName[field]`.

**List all metric names for a particular host**

The average value of a metric is computed as `total` over `count`, so the following query returns metric data where the result of the `average()` value function is greater than 2.

````sql
FROM Metric 
SELECT average(apm.service.transaction.duration) 
WHERE appName = 'MyApp' 
AND getField(apm.service.transaction.duration, total) / getField(apm.service.transaction.duration, count) > 2
```

Or, you can use the shorthand:

```sql
FROM Metric 
SELECT average(apm.service.transaction.duration) 
WHERE appName = 'MyApp' 
AND apm.service.transaction.duration[total] / apm.service.transaction.duration[count] > 2
```

````

**List of gauge metrics**

This example query returns a list of gauge metrics:

````sql
FROM Metric 
SELECT uniques(metricName) 
WHERE getField(%, type) = 'gauge'
```

Or, you can use the shorthand:

```sql
FROM Metric 
SELECT uniques(metricName) 
WHERE %[type] = 'gauge'
```

Note the use of the `%` wildcard to target any matching `metricName`.

````

## Explore metric data [#explore-metric-data]

The NRQL `keyset` and `uniques` functions can be used together with the `metricName` attribute (available on all metrics) to perform tasks like listing all the available metrics in your account or discovering the attributes available on a particular metric.

**List all metric names in an account**

````sql
FROM Metric SELECT uniques(metricName)
```

````

**List all metric names for a particular host**

````sql
FROM Metric SELECT uniques(metricName) WHERE hostname = 'host1.mycompany.com'
```

````

**Show the attribute keys for a specific metric**

````sql
FROM Metric SELECT keyset() WHERE metricName = METRIC_NAME
```

````