Analysis Config Skill

This skill helps you create AnalysisConfig objects - the canonical format for persisting analysis state in Drizzle Cube. Use AnalysisConfig for:

Dashboard portlets (via analysisConfig field)
Share URLs
localStorage persistence

AnalysisConfig Overview

interface AnalysisConfig {
  version: 1                              // Always 1
  analysisType: 'query' | 'funnel' | 'flow'
  activeView: 'table' | 'chart'
  charts: {
    [K in AnalysisType]?: ChartConfig     // Per-mode chart settings
  }
  query: CubeQuery | MultiQueryConfig | ServerFunnelQuery | ServerFlowQuery
}

interface ChartConfig {
  chartType: ChartType
  chartConfig: ChartAxisConfig
  displayConfig: ChartDisplayConfig
}

Query Mode (analysisType: 'query')

For standard queries and multi-query analysis.

Single Query Example

const singleQueryConfig: QueryAnalysisConfig = {
  version: 1,
  analysisType: 'query',
  activeView: 'chart',
  charts: {
    query: {
      chartType: 'bar',
      chartConfig: {
        xAxis: ['Employees.department'],
        yAxis: ['Employees.count', 'Employees.avgSalary']
      },
      displayConfig: {
        showLegend: true,
        stackType: 'none'
      }
    }
  },
  query: {
    measures: ['Employees.count', 'Employees.avgSalary'],
    dimensions: ['Employees.department'],
    filters: [
      {
        member: 'Employees.isActive',
        operator: 'equals',
        values: [true]
      }
    ],
    order: {
      'Employees.count': 'desc'
    },
    limit: 10
  }
}

Multi-Query Example

Combine multiple queries with merge strategies:

const multiQueryConfig: QueryAnalysisConfig = {
  version: 1,
  analysisType: 'query',
  activeView: 'chart',
  charts: {
    query: {
      chartType: 'line',
      chartConfig: {
        xAxis: ['Orders.createdAt'],
        yAxis: ['Sales.totalRevenue', 'Returns.totalRefunds']
      },
      displayConfig: {
        showLegend: true,
        showGrid: true
      }
    }
  },
  query: {
    queries: [
      {
        measures: ['Sales.totalRevenue'],
        timeDimensions: [{
          dimension: 'Orders.createdAt',
          granularity: 'month'
        }]
      },
      {
        measures: ['Returns.totalRefunds'],
        timeDimensions: [{
          dimension: 'Returns.createdAt',
          granularity: 'month'
        }]
      }
    ],
    mergeStrategy: 'merge',
    mergeKeys: ['Orders.createdAt'],
    queryLabels: ['Revenue', 'Refunds']
  }
}

Merge Strategies:

'concat' - Append rows with __queryIndex marker (for separate series)
'merge' - Align data by common dimension key (for combined visualization)

Funnel Mode (analysisType: 'funnel')

For sequential step analysis with conversion tracking.

Funnel Example

const funnelConfig: FunnelAnalysisConfig = {
  version: 1,
  analysisType: 'funnel',
  activeView: 'chart',
  charts: {
    funnel: {
      chartType: 'funnel',
      chartConfig: {},
      displayConfig: {
        funnelStyle: 'funnel',           // 'funnel' or 'bars'
        funnelOrientation: 'horizontal', // 'horizontal' or 'vertical'
        showFunnelConversion: true,
        showFunnelAvgTime: true
      }
    }
  },
  query: {
    funnel: {
      // Binding key links steps together (user/entity ID)
      bindingKey: 'Events.userId',

      // Time dimension for ordering and time-to-convert
      timeDimension: 'Events.timestamp',

      // Sequential steps
      steps: [
        {
          name: 'Signup',
          cube: 'Events',
          filter: {
            member: 'Events.eventType',
            operator: 'equals',
            values: ['signup']
          }
        },
        {
          name: 'First Purchase',
          cube: 'Purchases',
          filter: {
            member: 'Purchases.amount',
            operator: 'gt',
            values: [0]
          },
          timeToConvert: 'P30D'  // Must convert within 30 days
        },
        {
          name: 'Repeat Purchase',
          cube: 'Purchases',
          filter: {
            member: 'Purchases.isRepeat',
            operator: 'equals',
            values: [true]
          },
          timeToConvert: 'P90D'
        }
      ],

      // Optional: track time metrics between steps
      includeTimeMetrics: true,

      // Optional: overall time window for the entire funnel
      globalTimeWindow: 'P180D'
    }
  }
}

Cross-Cube Funnel

When the binding key has different names in different cubes:

query: {
  funnel: {
    // Map the binding key across cubes
    bindingKey: [
      { cube: 'Signups', dimension: 'Signups.userId' },
      { cube: 'Purchases', dimension: 'Purchases.customerId' }
    ],
    timeDimension: [
      { cube: 'Signups', dimension: 'Signups.createdAt' },
      { cube: 'Purchases', dimension: 'Purchases.purchaseDate' }
    ],
    steps: [
      { name: 'Signup', cube: 'Signups', filter: {...} },
      { name: 'Purchase', cube: 'Purchases', filter: {...} }
    ]
  }
}

Time Window Formats (ISO 8601 Duration)

Format	Duration
`PT1H`	1 hour
`PT24H`	24 hours
`P1D`	1 day
`P7D`	7 days
`P30D`	30 days
`P90D`	90 days

Flow Mode (analysisType: 'flow')

For bidirectional path analysis with Sankey diagram visualization.

Flow Example

const flowConfig: FlowAnalysisConfig = {
  version: 1,
  analysisType: 'flow',
  activeView: 'chart',
  charts: {
    flow: {
      chartType: 'sankey',
      chartConfig: {},
      displayConfig: {}
    }
  },
  query: {
    flow: {
      // Binding key identifies entities
      bindingKey: 'Events.userId',

      // Time dimension for ordering events
      timeDimension: 'Events.timestamp',

      // Event dimension for node labels
      eventDimension: 'Events.eventType',

      // Starting step (anchor point)
      startingStep: {
        name: 'Purchase',
        filter: {
          member: 'Events.eventType',
          operator: 'equals',
          values: ['purchase']
        }
      },

      // Explore N steps before the starting step
      stepsBefore: 3,

      // Explore N steps after the starting step
      stepsAfter: 3,

      // Join strategy
      joinStrategy: 'auto'  // 'auto' | 'lateral' | 'window'
    }
  }
}

Flow Output Modes

Mode	Description	Use Case
`sankey`	Aggregate by (layer, event_type)	Standard flow visualization, paths converge
`sunburst`	Path-qualified nodes	Hierarchical tree, each path unique

Complete CubeQuery Reference

interface CubeQuery {
  // Core query fields
  measures?: string[]              // e.g., ['Sales.count', 'Sales.revenue']
  dimensions?: string[]            // e.g., ['Products.category']

  // Time dimensions with granularity
  timeDimensions?: Array<{
    dimension: string              // e.g., 'Orders.createdAt'
    granularity?: 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'
    dateRange?: string | [string, string]
    fillMissingDates?: boolean
    compareDateRange?: (string | [string, string])[]
  }>

  // Filters
  filters?: Filter[]

  // Ordering
  order?: { [key: string]: 'asc' | 'desc' }

  // Pagination
  limit?: number
  offset?: number

  // Missing date handling
  fillMissingDatesValue?: number | null
}

Filter Operators

type FilterOperator =
  // Equality
  | 'equals' | 'notEquals'
  // String matching
  | 'contains' | 'notContains' | 'startsWith' | 'endsWith'
  // Numeric comparison
  | 'gt' | 'gte' | 'lt' | 'lte' | 'between' | 'notBetween'
  // Array membership
  | 'in' | 'notIn'
  // Null checks
  | 'set' | 'notSet' | 'isEmpty' | 'isNotEmpty'
  // Date operations
  | 'inDateRange' | 'beforeDate' | 'afterDate'
  // Regex
  | 'regex' | 'notRegex'

Filter Examples

// Simple filter
{
  member: 'Products.category',
  operator: 'equals',
  values: ['Electronics']
}

// Numeric range
{
  member: 'Orders.amount',
  operator: 'between',
  values: [100, 500]
}

// Date range
{
  member: 'Orders.createdAt',
  operator: 'inDateRange',
  values: ['2024-01-01', '2024-12-31']
}

// Grouped filters (AND/OR)
{
  type: 'and',
  filters: [
    { member: 'Products.isActive', operator: 'equals', values: [true] },
    {
      type: 'or',
      filters: [
        { member: 'Products.category', operator: 'equals', values: ['A'] },
        { member: 'Products.category', operator: 'equals', values: ['B'] }
      ]
    }
  ]
}

Supported Chart Types

Chart Type	Best For	Required Config
`bar`	Comparisons	xAxis, yAxis
`line`	Trends over time	xAxis, yAxis
`area`	Trends with volume	xAxis, yAxis
`pie`	Proportions	yAxis (single measure)
`scatter`	Correlation	xAxis, yAxis
`radar`	Multi-dimensional	yAxis (multiple measures)
`table`	Detailed data	None
`funnel`	Conversion flows	Funnel query
`sankey`	Path analysis	Flow query
`kpiNumber`	Single value	yAxis (single measure)
`kpiDelta`	Change indicator	yAxis, previous period
`markdown`	Text content	displayConfig.content
`bubble`	3+ dimensions	xAxis, yAxis, sizeField
`activityGrid`	Heatmap	dateField, valueField

Default Config Factories

Use these to create default configs:

import {
  createDefaultQueryConfig,
  createDefaultFunnelConfig,
  createDefaultFlowConfig,
  createDefaultConfig
} from 'drizzle-cube/client'

// Create default for specific type
const queryConfig = createDefaultQueryConfig()
const funnelConfig = createDefaultFunnelConfig()
const flowConfig = createDefaultFlowConfig()

// Or use generic factory
const config = createDefaultConfig('query')  // 'query' | 'funnel' | 'flow'

Type Guards

import {
  isQueryConfig,
  isFunnelConfig,
  isFlowConfig,
  isMultiQuery,
  isValidAnalysisConfig
} from 'drizzle-cube/client'

// Check analysis type
if (isQueryConfig(config)) {
  // config.query is CubeQuery | MultiQueryConfig
}

if (isFunnelConfig(config)) {
  // config.query is ServerFunnelQuery
}

if (isFlowConfig(config)) {
  // config.query is ServerFlowQuery
}

// Check if multi-query
if (isQueryConfig(config) && isMultiQuery(config)) {
  // config.query is MultiQueryConfig with queries[]
}

// Validate unknown data
if (isValidAnalysisConfig(unknownData)) {
  // unknownData is AnalysisConfig
}

Period Comparison

Compare data across time periods:

{
  measures: ['Sales.revenue'],
  timeDimensions: [{
    dimension: 'Sales.createdAt',
    granularity: 'month',
    dateRange: ['2024-01-01', '2024-03-31'],
    compareDateRange: [
      ['2023-01-01', '2023-03-31']  // Previous year comparison
    ]
  }]
}

Workspace Persistence

For localStorage persistence across mode switches:

interface AnalysisWorkspace {
  version: 1
  activeType: AnalysisType
  modes: {
    query?: QueryAnalysisConfig
    funnel?: FunnelAnalysisConfig
    flow?: FlowAnalysisConfig
  }
}

// Create default workspace
import { createDefaultWorkspace } from 'drizzle-cube/client'
const workspace = createDefaultWorkspace()

dc-analysis-config