Querying Data

Semaphor MCP provides two query tools for executing queries, each designed for different use cases.

Standard Mode

semaphor_query_spec uses Semaphor's card-config format — the same query engine that powers Semaphor dashboards.

Best for: Structured analytics that benefit from full security policy enforcement.

Key characteristics:

Uses Semaphor's card-config JSON format for query specification
Respects all security policies: CLS, SLS, and RLS
Automatic join resolution via the semantic model
Requires a connectionId, chartType, cardConfig, and cardDataSource

Standard mode example

{
  "connectionId": "conn_abc123",
  "chartType": "bar",
  "cardConfig": {
    "dimensions": [{ "column": "region", "dataType": "string" }],
    "metrics": [{ "column": "total_amount", "aggregation": "SUM" }]
  },
  "cardDataSource": {
    "type": "semantic",
    "domainId": "dom_abc",
    "datasetName": "orders"
  }
}

Standard mode uses the same query engine that powers Semaphor dashboards. If it works on a dashboard, it works through MCP.

Dev Mode

semaphor_query_sql is a SQL-first tool for advanced analysis.

Best for: Complex queries, multi-table joins, window functions, and ad-hoc analysis.

Key characteristics:

Pass a SQL string directly
Respects all security policies: CLS, SLS, and RLS
Optional Python post-processing for data transformations
Requires a connectionId and sql string

Dev mode example

{
  "connectionId": "conn_abc123",
  "sql": "SELECT date_trunc('month', order_date) AS month, COUNT(*) AS orders, SUM(total_amount) AS revenue FROM orders WHERE order_date >= '2025-01-01' GROUP BY 1 ORDER BY 1"
}

Python Post-Processing

Dev mode supports optional Python code to transform query results:

Dev mode with Python

{
  "connectionId": "conn_abc123",
  "sql": "SELECT region, revenue, cost FROM regional_summary",
  "python": "df['margin'] = (df['revenue'] - df['cost']) / df['revenue'] * 100"
}

Choosing Between Modes

	Standard Mode	Dev Mode
Query format	Card config (JSON)	Raw SQL
Security policies	CLS + SLS + RLS	CLS + SLS + RLS
Join resolution	Automatic via semantic model	Manual (you write the JOINs)
Python support	No	Yes (optional)
Best for	Business analytics, governed queries	Advanced analysis, complex SQL

Both standard and dev mode enforce all three security layers (CLS, SLS, RLS).

Response Format

Both query tools accept a response_format parameter:

"json" (default) — Machine-readable response with full data records, column metadata, and row counts
"markdown" — Human-readable summary with formatted tables

Choose "json" when building programmatic integrations. Choose "markdown" when the AI is presenting results conversationally.

Tips

Discover before querying — Always use the discovery workflow to learn available datasets and schemas before writing queries
Prefer standard mode for governed data — When working with semantic domains, standard mode provides automatic join resolution
Use dev mode for flexibility — When you need window functions, CTEs, or multi-table joins that go beyond the card-config format
Start with semaphor_get_analysis_context — It recommends whether to use the semantic or physical path, which informs your query approach