Business Intelligence Query Builder

/**
 * Creates an empty query structure with default values
 *
 * @param exploreName - Name of the data model to query
 * @returns A query object with empty arrays and default limit
 */
export function createQuery(exploreName: string): Query;

/**
 * Adds dimensions to group by in the query
 *
 * @param query - The query object
 * @param dimensions - Array of dimension field IDs
 * @returns Updated query with dimensions
 */
export function addDimensions(query: Query, dimensions: string[]): Query;

/**
 * Adds metrics to compute in the query
 *
 * @param query - The query object
 * @param metrics - Array of metric field IDs
 * @returns Updated query with metrics
 */
export function addMetrics(query: Query, metrics: string[]): Query;

/**
 * Sets the maximum number of rows to return
 *
 * @param query - The query object
 * @param limit - Maximum number of rows
 * @returns Updated query with limit
 */
export function setLimit(query: Query, limit: number): Query;

/**
 * Adds a sort field to the query
 *
 * @param query - The query object
 * @param fieldId - Field to sort by
 * @param descending - Whether to sort in descending order
 * @returns Updated query with sort configuration
 */
export function addSort(query: Query, fieldId: string, descending: boolean): Query;

/**
 * Adds dimension filters with AND logic to the query
 *
 * @param query - The query object
 * @param filterRules - Array of filter rules to combine with AND
 * @returns Updated query with dimension filters
 */
export function addDimensionFilters(query: Query, filterRules: FilterRule[]): Query;

/**
 * Adds dimension filters with OR logic to the query
 *
 * @param query - The query object
 * @param filterRules - Array of filter rules to combine with OR
 * @returns Updated query with dimension filters
 */
export function addDimensionFiltersOr(query: Query, filterRules: FilterRule[]): Query;

/**
 * Adds an additional custom metric to the query
 *
 * @param query - The query object
 * @param name - Metric name
 * @param sql - SQL expression for the metric
 * @param table - Table name the metric belongs to
 * @param aggregationType - Type of aggregation (e.g., 'sum', 'count', 'average')
 * @returns Updated query with additional metric
 */
export function addAdditionalMetric(
    query: Query,
    name: string,
    sql: string,
    table: string,
    aggregationType: string
): Query;

/**
 * Adds a custom binned dimension to the query
 *
 * @param query - The query object
 * @param name - Custom dimension name
 * @param baseDimensionId - Field ID of the dimension to bin
 * @param table - Table name
 * @param binCount - Number of bins to create
 * @returns Updated query with custom dimension
 */
export function addBinnedDimension(
    query: Query,
    name: string,
    baseDimensionId: string,
    table: string,
    binCount: number
): Query;

/**
 * Adds a table calculation to the query
 *
 * @param query - The query object
 * @param name - Calculation name
 * @param displayName - Display name for the calculation
 * @param sql - SQL expression for the calculation
 * @returns Updated query with table calculation
 */
export function addTableCalculation(
    query: Query,
    name: string,
    displayName: string,
    sql: string
): Query;

/**
 * Query structure for BI operations
 */
export interface Query {
    exploreName: string;
    dimensions: string[];
    metrics: string[];
    filters: Filters;
    sorts: Sort[];
    limit: number;
    tableCalculations: TableCalculation[];
    additionalMetrics?: AdditionalMetric[];
    customDimensions?: CustomDimension[];
}

/**
 * Filter structure with nested groups
 */
export interface Filters {
    dimensions?: FilterGroup;
    metrics?: FilterGroup;
    tableCalculations?: FilterGroup;
}

/**
 * Filter group with AND or OR logic
 */
export type FilterGroup = {
    id: string;
    and?: FilterRule[];
    or?: FilterRule[];
};

/**
 * Individual filter rule
 */
export interface FilterRule {
    id: string;
    target: { fieldId: string };
    operator: string;
    values?: any[];
}

/**
 * Sort configuration
 */
export interface Sort {
    fieldId: string;
    descending: boolean;
}

/**
 * Additional custom metric
 */
export interface AdditionalMetric {
    name: string;
    sql: string;
    table: string;
    type: string;
}

/**
 * Custom dimension (binned or SQL)
 */
export interface CustomDimension {
    id: string;
    name: string;
    type: string;
    dimensionId?: string;
    binType?: string;
    binNumber?: number;
    table: string;
}

/**
 * Table calculation
 */
export interface TableCalculation {
    name: string;
    displayName: string;
    sql: string;
}