Intelligent App YAML Reference

This page provides a detailed reference for all attributes available in Intelligent App YAML definitions. Use this as a guide when authoring or reviewing your app configuration files.

Top-Level Structure

app:
  name: string                # App display name
  description: string         # App description
  config:                     # App configuration (see below)
  layout:                     # Layout definition (see below)
  components:                 # App components (see below)

config Section

AttributeTypeDescription
cacheboolEnable/disable caching of query results
cache_ttlintCache time-to-live in seconds (default: 3600)
hide_llmbool(Optional) Hide the LLM assistant (Orion AI) in the app UI
hide_insightsbool(Optional) Hide the Insights panel in the app UI
llm_modelstring(Optional) LLM model for AI features (see below for options)
llm_instructionstring(Optional) Custom instruction for the LLM (prompt customization)

layout Section

Defines the structure of the app (tabs, items, chart groups).

layout:
  tabs:
    - name: string           # Tab identifier
      title: string          # Tab display title
      filters: [string]      # (Optional) List of filter names
      items:                 # List of layout items (see below)

Layout Items

AttributeTypeDescription
typestringchart, chart-group, text, table
namestringUnique item name
spanint(Optional) Grid span (width)
heightint(Optional) Height in px
entitieslist(For chart-group) Nested layout items

components Section

Holds the main building blocks: charts, variables, filters.

Charts

charts:
  - type: string             # `number`, `line`, `bar`, `pie`, `table`, `data_table`, `composed`
    name: string             # Unique chart name
    title: string            # Chart title
    description: string      # (Optional) Description
    query: string            # SQL query (Jinja supported)
    axis:                    # (Optional, for line, bar, composed)
      - name: string         # Axis name (e.g., left, right)
        position: string     # (Optional) Axis position (e.g., right)
    dimensions:              # (Optional) List of dimensions
      - name: string
        label: string
        number_format: string      # (Optional) Number format for this dimension
        table_align: left|right   # (Optional) Table alignment for this dimension
        affected_filter: string   # (Optional, bar/pie only) Filter to update when this dimension is clicked
    metrics:                 # (Optional) List of metrics
      - name: string
        label: string
        format: string            # (Optional) Number format string
        icon: string              # (Optional, number charts only) Lucide icon name (see https://lucide.dev/icons/)
        icon_variant: string      # (Optional, number charts only) One of: "default", "neutral", "success", "warning", "error"
        axis_name: string         # (Optional, for line, bar, composed) Axis to use for this metric
        composed_type: string     # (Optional, for composed) "line" or "bar"
    show_labels: bool        # (Optional, default: true)

Composed Chart Example

- type: composed
  name: top_products_composed
  title: Top Performing Products
  description: Top 10 products by revenue
  query: |
    SELECT 
      ProductName as product,
      SUM(OrderLineTotalAmount) as revenue,
      AVG(OrderLineTotalAmount) as avg_revenue
    FROM consolidated_sales_df_299ceb 
    WHERE 1=1
    {% if region_filter is defined %}
    AND CustomerRegion = '{{ region_filter }}'
    {% endif %}
    {% if product_group_filter is defined %}
    AND ProductGroup = '{{ product_group_filter }}'
    {% endif %}
    GROUP BY ProductName
    ORDER BY revenue DESC
    LIMIT 10;
  axis:
    - name: left
    - name: right
      position: right
  dimensions:
    - name: product
      label: Product
  metrics:
    - name: revenue
      label: Revenue
      axis_name: "left"
      composed_type: "bar"
      format: "$0,0.00"
    - name: avg_revenue
      label: "Average Revenue"
      axis_name: "right"
      composed_type: "line"
      format: "0,0[.]00 $"

Example: Bar Chart with Click-to-Filter

type: bar
name: sales_by_country
title: Sales by Country
query: SELECT country, sum(amount) as total FROM sales GROUP BY country
axis:
  - name: left
dimensions:
  - name: country
    label: Country
    affected_filter: country_filter
metrics:
  - name: total
    label: Total Sales

Example: Pie Chart with Click-to-Filter

type: pie
name: sales_distribution
title: Sales Distribution
query: SELECT category, sum(amount) as total FROM sales GROUP BY category
dimensions:
  - name: category
    label: Category
    affected_filter: category_filter
metrics:
  - name: total
    label: Total Sales

Variables

variables:
  - name: string             # Variable name
    type: string             # `string`, `integer`, `float`, `boolean`, `date`

Filters

filters:
  - type: string             # `text`, `number`, `dropdown`, `date`
    name: string             # Filter name
    title: string            # Display label
    affected_variable: str or [str] # Variable(s) updated
    default_value: any       # (Optional) Default value
    options:                 # (For dropdown)
      type: string           # `static` or `sql`
      values:                # (For static)
        - value: string
          label: string
      query: string          # (For sql)
    placeholder: string      # (Optional)

Supported LLM Models

  • GPT_4O
  • GPT_4O_MINI
  • CLAUDE_35_SONNET
  • CLAUDE_35_HAIKU
  • CLAUDE_37_SONNET

Example:

config:
  cache: true
  cache_ttl: 3600
  llm_model: GPT_4O
  llm_instruction: "You are a helpful assistant."

Example

app:
  name: Clubwise Billing Collection Dashboard
  description: Clubwise Billing Collection is a service that collects billing data from various sources and processes it for further analysis
  config:
    cache: true
    cache_ttl: 3600
  layout:
    tabs:
      - name: billing_data
        title: Billing Data
        filters: [product_group, membership_type_filter]
        items:
          - type: chart-group
            name: kpis
            span: 12
            entities:
              - type: chart
                name: total_count
                span: 4
          - type: chart
            name: detailed_table
            span: 12
  components:
    charts:
      - type: number
        name: total_count
        title: Total Row Count
        query: select count(*) as row_count from PROCESSED_Sales_Order;
        metrics:
          - name: row_count
            label: Row Count
    variables:
      - name: order_date
        type: date
    filters:
      - type: date
        name: order_date_filter
        title: Order Date Filter
        affected_variable: order_date
        default_value: '2024-04-01'

Example for Number Chart Metrics

charts:
  - type: number
    name: completed_tasks
    title: Completed Tasks
    query: SELECT count(*) as completed FROM tasks WHERE status = 'done';
    metrics:
      - name: completed
        label: Completed Tasks
        icon: check
        icon_variant: success
        format: "0"
  • For a full list of Lucide icons, see lucide.dev/icons.
  • icon_variant must be one of: default, neutral, success, warning, error.

Notes