datajunction-query

DataJunction Query

Consumer-side workflow for DJ: find existing nodes, build SQL to query them, fetch data, visualize results. For the underlying concepts (node types, dimension links, star schema), invoke the datajunction skill.

DJ UI (Web)

For interactive exploration — browsing namespaces, inspecting a node's lineage / SQL / available dimensions, building queries by clicking dimensions on/off — the DJ web UI is usually the fastest path. It's hosted at the same URL as the DJ server (e.g. https://your-dj-server.example.com/).

Use the UI when:

• The user wants to look around — browse what exists, read a node's description, explore lineage visually
• They want to build a query interactively and copy the SQL out
• They're sharing a node or query with a teammate (UI URLs are shareable links)

Use the MCP tools / API (below) when:

• You need programmatic access — pulling node names into a script, generating SQL as part of a workflow, fetching data into a notebook
• The interaction is "give me this answer," not "let me explore"

Suggest opening the UI when the user's question is exploratory and you don't yet know the right node name. Suggest MCP tools when you have a name in hand and need data, lineage, or generated SQL.

Discovery & Exploration (Use MCP Tools)

When you need to explore the DJ semantic layer, use these MCP tools:

Find Available Nodes

Use MCP tool: search_nodes

• Search for metrics, dimensions, cubes by name or namespace
• Filter by node type
• Returns list of matching nodes

Example: search_nodes(query="revenue", node_type="metric", namespace="finance")

Get Node Details

Use MCP tool: get_node_details

• Get comprehensive information about a specific node
• Returns: SQL definition, description, available dimensions, lineage, tags
• Input: Full node name (e.g., "finance.total_revenue")

Example: get_node_details(name="finance.total_revenue")

What you get:

• Description and SQL definition
• All available dimensions (via dimension links)
• Metric metadata (unit, direction, required dimensions)
• Upstream dependencies
• Tags and collections

Check Common Dimensions

Use MCP tool: get_common

• Find dimensions shared across multiple metrics, or metrics shared across multiple dimensions (bidirectional)
• Essential before querying multiple metrics together
• Returns only entries shared by ALL of the specified inputs

Example: get_common(metrics=["finance.total_revenue", "growth.daily_active_users"])

When to use: Always check this before building queries with multiple metrics!

Get Node Lineage

Use MCP tool: get_node_lineage

• Get upstream dependencies (what data sources this uses)
• Get downstream dependencies (what will break if you change this)
• Direction: "upstream", "downstream", or "both"

Example: get_node_lineage(node_name="finance.total_revenue", direction="both")

---

Querying & SQL Generation (Use MCP Tools)

When you need to query metrics or generate SQL, use these MCP tools:

Build Metric SQL

Use MCP tool: build_metric_sql

• Generate executable SQL for querying metrics
• Supports filters, dimensions, ordering, limits
• Returns SQL query and metadata

Example:

build_metric_sql(
  metrics=["finance.total_revenue"],
  dimensions=["core.date.date"],
  filters=["core.date.date >= '2024-01-01'"],
  orderby=["core.date.date ASC"],
  limit=100,
  dialect="trino",
)

Returns:

• Generated SQL for specified engine
• Output columns with types
• Cube name (if materialized cube used)

Performance: always pass a filter on a date/time dimension. When the upstream cube has a temporal partition declared on that dimension, DJ pushes the filter down to the partition column, limiting the data scanned. Without a time filter, queries scan the full underlying table.

(Don't pass include_temporal_filters=True here — that's a parameter on get_query_plan for inspecting partition templates in materialization-plan SQL, not for live queries.)

Get Metric Data

Use MCP tool: get_metric_data

• Execute query and get actual data
• Returns query results as rows
• Scan-cost guardrail: materialized cubes always run; ad-hoc queries (e.g. against Trino) run only if DJ's scan estimate is under the safety threshold. Over-threshold queries are refused up front and the estimate is surfaced so you can narrow the query (tighter date range, fewer dimensions, lower limit) and retry.

Example:

get_metric_data(
  metrics=["finance.total_revenue", "finance.transaction_count"],
  dimensions=["core.date.date", "core.region.region_name"],
  filters=["core.date.date >= '2024-01-01'"],
  orderby=["core.date.date ASC"],
  limit=1000
)

Best practices:

• Always set a reasonable limit
• Use specific date range filters — they drive partition pushdown and keep the scan estimate below the guardrail threshold
• Check common dimensions first for multi-metric queries
• If you're not sure how heavy a query will be, run get_query_plan first (see below) — it returns the scan estimate without executing

Visualize Metrics

Use MCP tool: visualize_metrics

• Query metrics and generate ASCII chart visualization
• Creates terminal-friendly charts (line, bar, scatter)
• Same scan-cost guardrails as get_metric_data

Example:

visualize_metrics(
  metrics=["finance.total_revenue"],
  dimensions=["core.date.date"],
  filters=["core.date.date >= '2024-01-01'"],
  orderby=["core.date.date ASC"],
  limit=90,
  chart_type="line"
)

Chart types:

• line: Time series (default)
• bar: Categorical comparisons
• scatter: Correlation analysis

Pre-Flight: Get Query Plan

Use MCP tool: get_query_plan

• Returns how DJ decomposes the requested metrics into grain groups and components, AND the scan estimate, without executing anything
• Use it before get_metric_data / visualize_metrics if you suspect the query might be expensive — the same scan estimate that drives the refusal guardrail is surfaced here, so you can iterate on filters until the estimate is reasonable

Example:

get_query_plan(
  metrics=["finance.total_revenue"],
  dimensions=["core.date.date"],
  filters=["core.date.date >= '2024-01-01'"],
)

When to use:

• "Will this query work?" — check before fetching
• "Why is this fetch refused?" — re-run the same args here to see the estimate
• "What grain group will this go through?" — useful for understanding multi-metric queries

---

API Reference (Educational Context)

The MCP tools call the DJ REST and GraphQL APIs under the hood. Here's what they're doing:

REST API Endpoints

Node discovery:

GET /nodes?node_type=metric&namespace=finance
GET /nodes/{node_name}

SQL generation (⚠️ Always use V3):

GET /sql/metrics/v3    # Generate query SQL
GET /sql/measures/v3   # Generate pre-aggregation SQL

Dimension compatibility:

GET /metrics/common/dimensions

GraphQL API

Available at /graphql:

query {
  nodes(nodeType: METRIC, namespace: "finance") {
    name
    description
    dimensions { name type }
  }

  commonDimensions(nodes: ["finance.revenue", "growth.users"]) {
    name
    type
  }
}