motleyai/update-query-block

Update Query Block

Create or update numerical queries inside text or table blocks. Queries execute against a cube and make their results available as {query_name} variables in the parent block's user_prompt.

How It Works

1. You call update_query_block with a structured query describing the data you want
2. The query is validated and executed against the semantic layer
3. The query result becomes available as {query_name} in the parent text/table block's user_prompt
4. When the parent block is resolved (via update_text_block or update_table_block), the query value is substituted in

Returns: The query result — a single value for single_number mode, or a markdown table for table mode.

Query Modes

single_number (default)

Returns a single aggregate value. Use for KPIs, metrics, and inline numbers in text.

Example: A query with measures: [{name: "total_revenue", cube_name: "revenue"}] and no dimensions returns the total.

The result substitutes directly into text: Revenue grew to {total_revenue} this quarter.

table

Returns the full query result as a markdown table. Use when you need multi-row data for LLM analysis or table blocks.

Example: A query with measures + dimensions returns grouped results as a table.

Workflow

Important: You must create query blocks BEFORE referencing them in update_text_block or update_table_block.

1. Create queries with update_query_block:

   update_query_block(
       parent_location={doc_id: 42, slide_name: "Overview", block_name: "metrics_text"},
       query_name="total_revenue",
       query={
           measures: [{name: "total_revenue", cube_name: "revenue"}]
       }
   )
   

2. Then set the parent template referencing the query:

   update_text_block(
       location={doc_id: 42, slide_name: "Overview", block_name: "metrics_text"},
       user_prompt="Revenue reached {currency(total_revenue)} this quarter, up {percent(revenue_growth)} from last quarter."
   )
   

The query_name ("total_revenue") must match the {variable} reference in the parent's user_prompt.

Pivot and Transpose (Table Mode)

pivot_dimension

Pivots a dimension's values into column headers. Useful for creating cross-tab tables.

update_query_block(
    parent_location={doc_id: 42, slide_name: "Breakdown", block_name: "data_table"},
    query_name="revenue_by_region_month",
    query={
        measures: [{name: "total_revenue", cube_name: "revenue"}],
        dimensions: [{name: "region", cube_name: "revenue"}],
        time_dimension: {
            dimension: {name: "created_at", cube_name: "revenue"},
            granularity: "month"
        }
    },
    mode="table",
    pivot_dimension="created_at"
)

Result without pivot: | Region | Month | Revenue | |--------|-------|---------| | US | Jan | 100K | | US | Feb | 120K | | EU | Jan | 80K |

Result with pivot_dimension="created_at": | Region | Jan | Feb | |--------|-----|-----| | US | 100K | 120K | | EU | 80K | 90K |

transpose

Swaps rows and columns. Combine with pivot_dimension for flexible layouts.

update_query_block(
    ...,
    mode="table",
    pivot_dimension="created_at",
    transpose=true
)

Examples

Single Number — KPI

update_query_block(
    parent_location={doc_id: 42, slide_name: "Executive Summary", block_name: "kpi_text"},
    query_name="active_users",
    query={
        measures: [{name: "active_user_count", cube_name: "users"}]
    }
)

Single Number — Comparison Value

update_query_block(
    parent_location={doc_id: 42, slide_name: "Executive Summary", block_name: "kpi_text"},
    query_name="prev_active_users",
    query={
        measures: [{name: "active_user_count", cube_name: "users"}],
        filters: [{"member": "users.period", "operator": "equals", "values": ["previous"]}]
    }
)

Then in the parent: Active users: {active_users} ({percent((active_users - prev_active_users) / prev_active_users)} vs previous period)

Table — Monthly Breakdown

update_query_block(
    parent_location={doc_id: 42, slide_name: "Trends", block_name: "trend_table"},
    query_name="monthly_data",
    query={
        measures: [
            {name: "total_revenue", cube_name: "orders"},
            {name: "order_count", cube_name: "orders"}
        ],
        time_dimension: {
            dimension: {name: "created_at", cube_name: "orders"},
            granularity: "month"
        },
        limit: 12,
        order: [{column: {name: "created_at", cube_name: "orders"}, order: "ASC"}]
    },
    mode="table"
)

Table — Pivoted Cross-Tab

update_query_block(
    parent_location={doc_id: 42, slide_name: "Comparison", block_name: "comparison_table"},
    query_name="region_quarterly",
    query={
        measures: [{name: "total_revenue", cube_name: "revenue"}],
        dimensions: [{name: "region", cube_name: "revenue"}],
        time_dimension: {
            dimension: {name: "created_at", cube_name: "revenue"},
            granularity: "quarter"
        },
        limit: 20
    },
    mode="table",
    pivot_dimension="created_at"
)

Related Skills

• For exploring models before writing queries: see the explore-model skill
• For expression syntax in templates: see variable-reference-syntax.md
• For context variables: see resolution-context.md