Query Building

/**
 * Builds query context for timeseries data fetching
 * Supports time comparison, forecasting, and complex aggregations
 * @param formData - Form data configuration
 * @returns Array of query contexts for data fetching
 */
function buildQuery(formData: QueryFormData): QueryContext[];

import { buildQuery } from "@superset-ui/plugin-chart-echarts";

const queryContexts = buildQuery({
  // Basic query configuration
  datasource: "1__table",
  viz_type: "echarts_timeseries",
  metrics: ["sum__value"],
  groupby: ["category"],
  
  // Time configuration
  time_range: "Last 30 days",
  time_grain_sqla: "P1D",
  
  // Time comparison
  time_compare: ["1 year ago"],
  
  // Advanced features
  rolling_type: "mean",
  rolling_periods: 7,
  // ... other configuration
});

/**
 * Query context containing complete query configuration
 */
interface QueryContext {
  /** Base query object with metrics and filters */
  queries: QueryObject[];
  /** Form data configuration */
  form_data: QueryFormData;
  /** Result format specification */
  result_format: string;
  /** Result type specification */
  result_type: string;
}

interface QueryObject {
  /** Metrics to aggregate */
  metrics: QueryFormMetric[];
  /** Columns to group by */
  columns: QueryFormColumn[];
  /** Series columns for multi-series charts */
  series_columns: QueryFormColumn[];
  /** Time series flag */
  is_timeseries?: boolean;
  /** Ordering specification */
  orderby: QueryFormOrderBy[];
  /** Time offset for comparisons */
  time_offsets: string[];
  /** Post-processing operations */
  post_processing: PostProcessingRule[];
}

/**
 * Post-processing operations applied to query results
 */
interface PostProcessingRule {
  operation: string;
  options: Record<string, any>;
}

/**
 * Pivot operator for data restructuring
 */
type PostProcessingPivot = PostProcessingRule & {
  operation: 'pivot';
  options: {
    index: string[];
    columns: string[];
    values: string[];
    aggfunc?: string;
  };
};

/**
 * Time comparison configuration
 */
interface TimeComparisonConfig {
  /** Time periods to compare */
  time_compare: string[];
  /** Comparison type */
  comparison_type?: 'values' | 'difference' | 'percentage' | 'ratio';
}

/**
 * Forecasting configuration
 */
interface ForecastingConfig {
  /** Enable forecasting */
  forecastEnabled: boolean;
  /** Number of periods to forecast */
  forecastPeriods: number;
  /** Confidence interval percentage */
  forecastInterval: number;
  /** Seasonality patterns */
  forecastSeasonalityDaily?: null | boolean;
  forecastSeasonalityWeekly?: null | boolean;
  forecastSeasonalityYearly?: null | boolean;
}

/**
 * Rolling window operation configuration
 */
interface RollingWindowConfig {
  /** Rolling window type */
  rolling_type: 'mean' | 'sum' | 'std' | 'count' | 'min' | 'max';
  /** Number of periods for rolling calculation */
  rolling_periods: number;
  /** Minimum periods required */
  min_periods?: number;
}

/**
 * Contribution calculation types
 */
enum ContributionType {
  Absolute = null,
  Row = 'row',
  Column = 'column',
}

/**
 * Series configuration
 */
interface SeriesConfig {
  /** Maximum number of series to display */
  series_limit: number;
  /** Series limit metric for ranking */
  series_limit_metric?: QueryFormMetric;
  /** Order by configuration */
  orderby: QueryFormOrderBy[];
  /** Descending order flag */
  order_desc: boolean;
}

/**
 * Time configuration for queries
 */
interface TimeConfig {
  /** Time range specification */
  time_range: string;
  /** Time granularity */
  time_grain_sqla: TimeGranularity;
  /** Time column override */
  granularity_sqla?: string;
  /** Time zone */
  time_zone?: string;
}

type TimeGranularity = 
  | 'PT1S'   // 1 second
  | 'PT1M'   // 1 minute
  | 'PT5M'   // 5 minutes
  | 'PT30M'  // 30 minutes
  | 'PT1H'   // 1 hour
  | 'P1D'    // 1 day
  | 'P1W'    // 1 week
  | 'P1M'    // 1 month
  | 'P1Y';   // 1 year