pi-semantic-query

Pi extension for working with governed semantic metrics from semantic-query-compiler.

It gives pi tools to discover metrics, inspect definitions, validate a model, and compile metric requests to SQL. It does not execute warehouse queries.

Requirements

• pi coding agent
• Node/npm for installing the pi package
• semantic-query-compiler >= 0.1.4 installed so the semantic CLI is on PATH
• a semantic model in the project, usually semantic.yml

Install the Python compiler first:

uv tool install 'semantic-query-compiler>=0.1.4'
semantic --version

Install in pi

From npm, after publishing:

pi install npm:@rasmusengelbrecht/pi-semantic-query

For local development:

pi install /absolute/path/to/pi-semantic-query

Or try without installing:

pi -e /absolute/path/to/pi-semantic-query

Tools

The package registers a bundled semantic-query skill plus these pi tools:

• semantic_metrics — list metrics with discovery metadata
• semantic_search_metrics — search metrics by id, name, description, synonyms, and teams
• semantic_describe — describe one metric definition
• semantic_validate — validate a semantic model
• semantic_compile — compile a metric request to SQL

The skill teaches pi the default workflow: search before guessing metric IDs, describe ambiguous metrics, validate model changes, prefer period, and never present compiled SQL as executed results.

All tools shell out to the local semantic CLI. If target relation flags fail with unrecognized arguments, upgrade the Python CLI:

uv tool install 'semantic-query-compiler>=0.1.4' --force

By default tools look for one of:

• semantic.yml
• semantic.yaml
• model.yml
• model.yaml
• semantic_layer.yml
• semantic_layer.yaml

Pass model explicitly when your file lives somewhere else.

Example prompt

List available semantic metrics in this repo, find the revenue metric, then compile revenue by country for the last 12 complete months.

The agent should:

1. call semantic_search_metrics
2. call semantic_describe for the chosen metric
3. call semantic_compile with an inline request shape and period

Example request shape for semantic_compile:

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

For target series, pass targetTable. semantic-query-compiler >= 0.1.4 accepts both core target column conventions (metric_id/target_series/metric_time/target_value and metric/series/time/value) on BigQuery. Use targetProject and targetSchema when the warehouse needs a qualified target relation but you want to keep the table name generic:

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

Safety boundary

This package is compile-only by design. semantic_compile returns SQL; it does not run the SQL. Query execution touches credentials, cost, and data access, so execution should stay in the caller's existing warehouse tooling or a separate explicitly configured integration.

Publishing

npm pack --dry-run
npm publish --access public

The pi-package keyword makes the package discoverable by pi package indexes.