> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dqlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> What Query metrics are, how they run custom SQL expressions, and how to make them reusable with runtime parameters.

<script type="application/ld+json">
  {`{
            "@context": "https://schema.org",
            "@type": "TechArticle",
            "headline": "Query Metrics Overview",
            "description": "What Query metrics are, how they run custom SQL expressions, and how to make them reusable with runtime parameters.",
            "url": "https://docs.dqlabs.ai/architecture/metrics/query/usecases",
            "publisher": {
              "@type": "Organization",
              "name": "DQLabs Inc",
              "logo": "https://media.brand.dev/332adc35-5bc4-4d2b-bf78-256aa4a5e414.svg"
            }
            }`}
</script>

## What is a Query metric?

Query metrics are defined by a **SQL expression written directly by the user**, enabling arbitrary business logic that cannot be expressed through configuration-based rules. They give analysts and engineers full flexibility to define quality expectations using the same SQL they already write.

**Type:** User-defined — Query metrics are created manually. Navigate to **Metric → Add** and select **Subcategory: Query**.

Query metrics answer the question: *Does this data satisfy a custom quality check I can express in SQL?*

Prizm runs the SQL on each operational cycle, records the returned numeric value, and trends it over time. Anomaly detection activates once enough historical runs have been collected.

| Metric | Category | Sub Category | Asset Level | Description                                                                                                                                                                                                                     |
| ------ | -------- | ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Query  | Business | Query        | Table       | A user-defined metric that executes a SQL query against the target asset on each run. The query must return a single numeric value, which is trended over time and evaluated against an anomaly baseline or explicit threshold. |

***

## Parameterized Query Metrics

Any Query metric can be made **parameterized** by placing `{{param_name}}` tokens anywhere in the SQL. Instead of a hardcoded value, that position accepts a runtime input — supplied via a popup in the UI, or passed through the API or CLI.

```sql theme={null}
-- Standard query — fixed logic
SELECT COUNT(*) FROM orders WHERE status = 'failed'

-- Parameterized query — values injected at run time
SELECT COUNT(*) FROM {{table}} WHERE status = 'failed'
  AND business_date >= {{start_date}}
  AND region = {{region}}
```

When a parameterized metric is run from the UI, Prizm shows a **parameter input popup** listing every `{{token}}` that needs a value. Fill in the fields and click **Run** — Prizm validates, renders the SQL, and executes it. The resolved SQL and parameter values are stored in the audit record for every run.

Parameterized metrics are visually identified in the Metrics list by a **Parameterized** indicator tag — making it easy to audit which metrics use dynamic SQL.

### Parameter types

| Type         | How it resolves                                                         | Example tokens                                             |
| ------------ | ----------------------------------------------------------------------- | ---------------------------------------------------------- |
| **SOURCE**   | Auto-resolved from the asset bound to the metric — no user input needed | `{{table}}`, `{{schema}}`, `{{database}}`, `{{attribute}}` |
| **CONSTANT** | Pulled from an org-level constant defined in **Settings → Parameters**  | `{{Currency}}`, `{{Territory}}`                            |
| **METADATA** | Resolved from the platform metadata graph using dot-notation            | `{{Asset.Name}}`, `{{Metric.Tag}}`                         |

SOURCE parameters are always resolved automatically. CONSTANT and METADATA parameters can have defaults set at the metric level. Any parameter without a default and without a caller-supplied value blocks execution until a value is provided.

### Audit record

Every execution stores a complete run record for traceability.

| Field                      | Purpose                                                               |
| -------------------------- | --------------------------------------------------------------------- |
| `run_id`                   | Unique identifier for this execution                                  |
| `effective_params`         | Actual values used after merging caller input / metric default        |
| `resolved_sql`             | Fully rendered SQL sent to the warehouse                              |
| `status`                   | `PASS` \| `FAIL` \| `WARN` \| `EXECUTION_ERROR` \| `VALIDATION_ERROR` |
| `value`                    | Numeric output from the SQL                                           |
| `started_at / finished_at` | Execution timestamps                                                  |
| `triggered_by`             | User, API key, or scheduler that initiated the run                    |

***

## Metric Templates

When the same parameterized SQL logic should apply across multiple assets — each with its own parameter overrides — use a **Metric Template** (Rule Library). Write the rule once, assign it to many assets, and update all assignments in one edit.

<CardGroup cols={2}>
  <Card title="Setup" icon="sliders" href="/architecture/metrics/query/setup">
    Creating a query metric and adding runtime parameters.
  </Card>

  <Card title="Metric Template" icon="rectangle-stack" href="/architecture/metrics/metric-template/overview">
    Reusable parameterized rules across many assets — overview, use cases, and setup.
  </Card>
</CardGroup>