---
name: semantic-query
description: Compile and inspect governed semantic metrics with semantic-query-compiler from pi. Use when the user asks for semantic metrics, metric discovery, governed SQL compilation, semantic model validation, or SQL for a metric request.
---

# Semantic Query

Use the `semantic_*` tools from this package to discover governed metrics and compile inspectable SQL. These tools do **not** execute warehouse queries.

This package shells out to the local `semantic` CLI and expects `semantic-query-compiler >= 0.1.4`. If a tool reports `unrecognized arguments` for target relation flags, or target columns like `metric`/`series`/`time`/`value` are not recognized, tell the user to upgrade with `uv tool install 'semantic-query-compiler>=0.1.4' --force --refresh` and verify `semantic --version`.

## Default workflow

1. Start with `semantic_search_metrics` when the user describes a metric in business language.
2. Use `semantic_metrics` when they ask what metrics exist or when search is too narrow.
3. Use `semantic_describe` before compiling if the metric semantics, grain, filters, dimensions, teams, or formula are unclear.
4. Use `semantic_validate` after model edits, before trusting a new model, or when compile errors suggest the model may be invalid.
5. Use `semantic_compile` to generate SQL for the chosen metric and request.
6. Say clearly that compiled SQL is not executed results.

## Request guidance

Prefer period-based requests for CLI/agent workflows:

```json
{
  "metricId": "revenue",
  "period": "last 12 complete months",
  "dialect": "bigquery",
  "request": {
    "timeGrain": "monthly",
    "breakdownDimensionIds": ["country"]
  }
}
```

For target series, pass `targetTable`. BigQuery target joins accept both `metric_id`/`target_series`/`metric_time`/`target_value` and `metric`/`series`/`time`/`value` without explicit column flags on `semantic-query-compiler >= 0.1.4`. If the warehouse needs qualified table names, prefer generic relation parts instead of hard-coded company presets:

```json
{
  "metricId": "revenue",
  "period": "current year",
  "dialect": "bigquery",
  "targetProject": "warehouse-project",
  "targetSchema": "analytics",
  "targetTable": "metric_targets",
  "request": {
    "timeGrain": "monthly",
    "targetSeries": "budget_current"
  }
}
```

Use raw `fromDate` / `toDate` only when the user needs exact fixed boundaries or provides a request JSON shape that already has them.

## Safety boundary

`semantic_compile` returns SQL only. Do not claim row counts, metric values, parity, or dashboard results unless a separate warehouse/query tool actually executed the SQL.

If the user asks to run the query, use their normal warehouse tooling or ask which execution environment to use. This package intentionally does not handle credentials, warehouse cost, or data access.

## Model discovery

By default, tools look for common model filenames in the current project (`semantic.yml`, `model.yml`, `semantic_layer.yml`, and `.yaml` variants). Pass `model` explicitly when the model lives elsewhere.