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.)