/**
 * Warehouse Query Interface
 *
 * Unified query schema for cross-database operations across
 * traditional databases, graphs, and vector stores.
 */
import { IUnifiedWhereClause } from './where.interface';
import { IJoinClause } from './join.interface';
import { ISagaTransaction } from './transaction.interface';
/**
 * Types of data sources supported by the warehouse
 */
export type DataSourceType = 'database' | 'graph' | 'vector';
/**
 * Reference to a configured data source
 */
export interface IDataSource {
    /** Source type */
    type: DataSourceType;
    /**
     * Tag reference to configured data source
     * e.g., "users-postgres", "knowledge-neo4j", "embeddings-pinecone"
     */
    tag: string;
    /**
     * Entity within the source
     * - database: table name
     * - graph: node label
     * - vector: index/collection name
     */
    entity: string;
    /** Alias for use in joins and field references */
    alias?: string;
}
/**
 * Supported warehouse operations
 */
export type WarehouseOperation = 'select' | 'insert' | 'update' | 'delete' | 'upsert';
/**
 * Field mapping for projections
 */
export interface IFieldMapping {
    /** Source field path (e.g., "u.name") */
    source: string;
    /** Output alias */
    as?: string;
    /** Aggregate function */
    aggregate?: 'count' | 'sum' | 'avg' | 'min' | 'max';
}
/**
 * Aggregation specification
 */
export interface IAggregation {
    /** Aggregate function */
    function: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'count_distinct';
    /** Field to aggregate (use '*' for count) */
    field: string;
    /** Output alias */
    as: string;
}
/**
 * Order by specification
 */
export interface IOrderBy {
    /** Field path */
    field: string;
    /** Sort order */
    order: 'ASC' | 'DESC';
    /** Nulls position */
    nulls?: 'FIRST' | 'LAST';
}
/**
 * Unified warehouse query interface
 *
 * Supports querying across databases, graphs, and vector stores
 * with cross-database joins, aggregations, and transactions.
 */
export interface IWarehouseQuery {
    /** Operation type */
    operation: WarehouseOperation;
    /** Primary data source */
    from: IDataSource;
    /**
     * Fields to return (select)
     * Can be string paths or field mappings with aliases
     */
    fields?: (string | IFieldMapping)[];
    /**
     * Data for write operations (insert/update/upsert)
     * Single object or array for bulk operations
     */
    data?: Record<string, any> | Record<string, any>[];
    /** Cross-database joins */
    join?: IJoinClause[];
    /** Unified where clause (works across all data types) */
    where?: IUnifiedWhereClause;
    /** Aggregations */
    aggregate?: IAggregation[];
    /** Group by fields */
    groupBy?: string[];
    /** Having clause (for aggregations) */
    having?: IUnifiedWhereClause;
    /** Order by */
    orderBy?: IOrderBy[];
    /** Limit results */
    limit?: number;
    /** Offset for pagination */
    offset?: number;
    /**
     * Return inserted/updated data
     * Only applicable for write operations
     */
    returning?: boolean | string[];
    /**
     * Conflict keys for upsert operations
     * Columns to detect conflict on (unique keys)
     */
    conflictKeys?: string[];
    /**
     * Transaction context for cross-database transactions
     * Uses Saga pattern for distributed consistency
     */
    transaction?: ISagaTransaction;
    /** Execution hints for optimization */
    hints?: IExecutionHints;
}
/**
 * Hints for query optimization
 */
export interface IExecutionHints {
    /**
     * Preferred join strategy
     * - hash: Build hash table from smaller dataset
     * - nested_loop: Iterate outer, query inner per row
     * - sort_merge: Sort both sides and merge
     */
    joinStrategy?: 'hash' | 'nested_loop' | 'sort_merge' | 'auto';
    /** Maximum memory for join operations (bytes) */
    maxJoinMemory?: number;
    /** Enable parallel execution of independent sub-queries */
    parallel?: boolean;
    /** Timeout in milliseconds */
    timeout?: number;
    /** Enable result streaming for large datasets */
    streaming?: boolean;
    /** Cache results for this duration (seconds) */
    cacheTtl?: number;
    /** Force read from primary (not replicas) */
    readFromPrimary?: boolean;
}
/**
 * Unified query result
 */
export interface IWarehouseResult<T = Record<string, any>> {
    /** Result data */
    data: T[];
    /** Total count (if available) */
    count?: number;
    /** Affected rows (for write operations) */
    affectedRows?: number;
    /** Execution metadata */
    metadata: IQueryMetadata;
}
/**
 * Query execution metadata
 */
export interface IQueryMetadata {
    /** Total execution time in milliseconds */
    executionTime: number;
    /** Number of data sources queried */
    sourcesQueried: number;
    /** Breakdown by source */
    sourceStats: ISourceStats[];
    /** Join statistics (if applicable) */
    joinStats?: IJoinStats;
    /** Whether results were cached */
    cached: boolean;
    /** Query plan used */
    plan?: IExecutionPlan;
}
/**
 * Per-source execution statistics
 */
export interface ISourceStats {
    /** Data source tag */
    tag: string;
    /** Source type */
    type: DataSourceType;
    /** Execution time for this source */
    executionTime: number;
    /** Rows/nodes/vectors returned */
    rowsReturned: number;
}
/**
 * Join execution statistics
 */
export interface IJoinStats {
    /** Join strategy used */
    strategy: 'hash' | 'nested_loop' | 'sort_merge' | 'semantic';
    /** Left side row count */
    leftRows: number;
    /** Right side row count */
    rightRows: number;
    /** Result row count */
    resultRows: number;
    /** Join execution time */
    executionTime: number;
}
/**
 * Execution plan (for debugging/optimization)
 */
export interface IExecutionPlan {
    /** Plan steps */
    steps: IExecutionStep[];
    /** Estimated total cost */
    estimatedCost: number;
}
/**
 * Single execution step
 */
export interface IExecutionStep {
    /** Step type */
    type: 'scan' | 'filter' | 'join' | 'aggregate' | 'sort' | 'limit';
    /** Target source (if applicable) */
    source?: string;
    /** Estimated rows */
    estimatedRows: number;
    /** Estimated cost */
    estimatedCost: number;
    /** Step details */
    details?: Record<string, any>;
}