Skip to content
Monomer

Analyze a metric

← Analyze

For a question such as “What was revenue by week in August?”, use a semantic query to reuse your team’s revenue definition.

You need the Explorer role or higher, a metric, and a connector with its source tables. Open the metric first to confirm its meaning and reporting time dimension. This guide uses a simple revenue metric and an existing order-time dimension defined at DAY grain. Monomer groups and filters times in the Workspace’s Reporting time zone, UTC unless an Owner or Organization Admin changed it; see Time zones and dates. Discover the actual model and dimension names before using the example.

Weekly buckets and rows inside a month

Section titled “Weekly buckets and rows inside a month”

metricTimeRange selects an aggregation period. The engine aligns it to the query’s time grain: August 1–31, 2026 with WEEK can cover July 27–September 6. By itself, this range can include orders outside August.

To count only August orders while keeping weekly groups, also filter the existing order-time dimension by date: on or after 2026-08-01 and before 2026-09-01 (GREATER_THAN_OR_EQUAL and LESS_THAN for an agent). Both filters apply together before aggregation. A DAY dimension compares calendar days, so the exclusive next-month boundary includes all of August 31.

These boundaries select the days inside August in the Reporting time zone. A row labeled 2026-07-27 is the Monday-start week containing August 1–2; its revenue includes only those two August days after the filters. The 2026-08-31 row includes only August 31. Do not remove the July label: that would discard valid August revenue. If there are no orders inside August, do not report neighboring months’ orders as August revenue; an empty result is not an execution error.

Check the dimension’s grain and time basis. Typed filters compare the model’s time dimension at its declared grain, not necessarily the unmodified source timestamp. A dimension defined at day or coarser grain takes Date filters and compares calendar days in the Reporting time zone; a dimension defined at hour or finer grain takes Timestamp filters, and other filter types are rejected. A noon boundary, or a month in a time zone other than the Reporting time zone, cannot be represented exactly by a DAY dimension. Timestamp filter values carry an offset, such as 2026-08-01T00:00:00+09:00; Monomer converts each value to the Reporting time zone’s wall-clock time before comparing, so an offset does not change the grouping’s time zone. Timestamp filter values preserve up to 6 fractional second digits (microseconds), or may omit fractional seconds. Values with 7 or more digits are rejected before a run is created for every warehouse, including values with trailing zeros. Send at most 6 digits; Monomer does not round or truncate them. Do not change the metric or model definition to make a single query appear to match. Report an unsupported boundary explicitly.

What filters include

Section titled “What filters include”

Is not and is not one of keep rows with no value as well as rows whose value differs. Add is not empty if you also want to exclude missing values.

For Text, is empty includes missing values and blank text (""). Is not empty excludes both. Text containing only spaces still has a value. For other comparison types, empty means a missing value.

Date filters compare calendar days in the Reporting time zone after the dimension’s declared grain is applied. A DAY dimension backed by a timestamp compares its date in that zone; a MONTH dimension compares the date of its month bucket. Date filters do not restore time detail removed by the dimension’s grain.

For an agent, the corresponding operators are NOT_EQUALS, NOT_IN, IS_NULL, and IS_NOT_NULL. Text values must contain 1–256 characters and no NUL character; NUMBER values use the canonical decimal strings defined by the query schema.

Run the query

Section titled “Run the query”
  1. Open Explore → Metrics. The query has a row for each part: Metrics, Group by, Filters, and Time range with Sort and Limit. Before you run, the Metrics and Group by lists are open below the query.
  2. Choose your metric from the Metrics list, where metrics are listed under the model they read. In the Group by list, Metric time comes first; choose its Week grain for a weekly trend. Leave Group by empty for a total.
  3. Open Time range, choose Date, then set start to 2026-08-01 and end to 2026-08-31 for this example. Use View rendered SQL to confirm the effective time boundaries for the selected grain.
  4. For August-only orders, add two filters on the existing order-time dimension under Filters: is on or after 2026-08-01 and is before 2026-09-01. A day-level dimension compares dates, so its filter takes a date. The metric time range alone is insufficient.
  5. Set Sort and Limit as needed. The connector above the query comes from the metric: only connectors with source tables for every model it reads qualify. If several qualify, choose one. If you change metrics so that a grouping or filter no longer applies, it stays in the query marked as unavailable; remove it before you run.
  6. Select Run, wait for completion, and inspect the result under the query. The result names the time zone it used, such as Times in UTC.

Each row represents one returned group. Compare the period and filters with your original question. A low row limit may leave groups out; do not sum a truncated result as though it were complete.

When the exact query cannot run

Section titled “When the exact query cannot run”

A valid JSON request can still fail at the warehouse. In particular, BigQuery tables requiring a partition filter reject generated SQL whose time condition BigQuery does not recognize for partition elimination. On a TIMESTAMP partition column, a dimension defined at day or coarser grain keeps partition elimination in any Reporting time zone; one defined at hour or finer grain does not, because Monomer compares its wall-clock time in the Reporting time zone. A failure is not a zero or an empty month. See BigQuery’s partition-filter requirements.

Report the failed run and the limitation. Keep the original metric/model and the warehouse’s partition requirement intact. If SQL analysis is appropriate, use Run SQL to apply an explicit source-column range before weekly aggregation, and state that this is a SQL analysis, not a successful execution of the existing metric. Do not silently substitute a different definition or claim that a failed Semantic run answered the question.

If no metric appears, confirm the workspace or define one. If a grouping is absent, review the model’s dimensions and entities. A model whose definition MetricFlow rejects is left out of the options instead of blocking the query; Explore names it, and you can open the model to fix it. When a query can’t run, Explore names the broken model or metric it depends on, or sends you to Catalog to choose the tables its models read. If access is denied, follow Workspace role guidance. To download or revisit the output, see Work with results.

Tables that require a partition filter

Section titled “Tables that require a partition filter”

Explore leaves the default time range at Any time. If a selected metric or grouping field reads a BigQuery table that requires a partition filter, Explore offers a time range or matching dimension filter. The hint leaves Run available: Catalog metadata can be older than the warehouse setting.

For these tables, Monomer validates the rendered query with a BigQuery dry run before creating a run. If BigQuery requires a partition filter, add the suggested time range or filter and run again. The rejected start adds nothing to Runs. Agent requests receive PARTITION_FILTER_REQUIRED with partitionFilters containing the relevant model or time-spine addresses and keys. A time range is guidance, not a guarantee for every metric shape; BigQuery decides whether the query meets its partition rule.