/**
 * Join Interface
 *
 * Defines cross-database join operations including standard SQL-style joins,
 * semantic joins (vector similarity), and graph traversal joins.
 */
import { IDataSource } from './query.interface';
import { IUnifiedWhereClause } from './where.interface';
/**
 * Standard join types
 */
export type StandardJoinType = 'inner' | 'left' | 'right' | 'full' | 'cross';
/**
 * Extended join types including semantic/vector joins
 */
export type JoinType = StandardJoinType | 'semantic' | 'graph';
/**
 * Standard join condition (equality or comparison)
 */
export interface IJoinCondition {
    /** Left side field path (e.g., "u.id") */
    left: string;
    /** Right side field path (e.g., "o.userId") */
    right: string;
    /**
     * Comparison operator
     * @default '='
     */
    operator?: '=' | '!=' | '>' | '<' | '>=' | '<=';
}
/**
 * Multiple join conditions with logical operator
 */
export interface ICompoundJoinCondition {
    /** Logical operator */
    logic: 'AND' | 'OR';
    /** Individual conditions */
    conditions: IJoinCondition[];
}
/**
 * Semantic join configuration (vector similarity)
 */
export interface ISemanticJoinConfig {
    /**
     * Field containing embedding or text to embed
     * If text, will be embedded on-the-fly
     */
    embedField: string;
    /**
     * Minimum similarity threshold (0-1 for cosine)
     * @default 0.7
     */
    similarityThreshold?: number;
    /**
     * Maximum similar items to return per row
     * @default 10
     */
    topK?: number;
    /**
     * Distance metric
     * @default 'cosine'
     */
    metric?: 'cosine' | 'euclidean' | 'dot_product';
    /**
     * Embedding model to use if embedField contains text
     * Required if embedField is not already a vector
     */
    embeddingModel?: string;
}
/**
 * Graph traversal join configuration
 */
export interface IGraphJoinConfig {
    /**
     * Relationship type to traverse
     */
    relationship: string;
    /**
     * Traversal direction
     * @default 'outgoing'
     */
    direction?: 'outgoing' | 'incoming' | 'both';
    /**
     * Minimum traversal depth
     * @default 1
     */
    minDepth?: number;
    /**
     * Maximum traversal depth
     * @default 1
     */
    maxDepth?: number;
    /**
     * Filter for intermediate nodes
     */
    nodeFilter?: IUnifiedWhereClause;
    /**
     * Filter for relationships
     */
    relationshipFilter?: IUnifiedWhereClause;
}
/**
 * Join clause for cross-database joins
 *
 * @example
 * // Standard inner join
 * {
 *   type: 'inner',
 *   source: { type: 'database', tag: 'orders-mongo', entity: 'orders', alias: 'o' },
 *   on: { left: 'u.id', right: 'o.userId' }
 * }
 *
 * @example
 * // Semantic join (vector similarity)
 * {
 *   type: 'semantic',
 *   source: { type: 'vector', tag: 'products-pinecone', entity: 'products', alias: 'similar' },
 *   semantic: {
 *     embedField: 'p.description',
 *     similarityThreshold: 0.8,
 *     topK: 5
 *   }
 * }
 *
 * @example
 * // Graph traversal join
 * {
 *   type: 'graph',
 *   source: { type: 'graph', tag: 'social-neo4j', entity: 'Person', alias: 'friend' },
 *   graph: {
 *     relationship: 'FRIENDS_WITH',
 *     direction: 'both',
 *     maxDepth: 2
 *   },
 *   on: { left: 'u.id', right: 'friend.userId' }
 * }
 */
export interface IJoinClause {
    /** Join type */
    type: JoinType;
    /** Data source to join */
    source: IDataSource;
    /**
     * Join condition for standard joins
     * Required for 'inner', 'left', 'right', 'full' joins
     */
    on?: IJoinCondition | ICompoundJoinCondition;
    /**
     * Semantic join configuration
     * Required when type is 'semantic'
     */
    semantic?: ISemanticJoinConfig;
    /**
     * Graph traversal configuration
     * Required when type is 'graph'
     */
    graph?: IGraphJoinConfig;
    /**
     * Additional filter to apply to joined data
     */
    where?: IUnifiedWhereClause;
    /**
     * Fields to select from this join source
     * If not specified, all fields are included
     */
    select?: string[];
    /**
     * Alias prefix for all fields from this source
     * Helps avoid naming conflicts
     */
    fieldPrefix?: string;
}
/**
 * Result of a join operation
 */
export interface IJoinResult<T = Record<string, any>> {
    /** Joined data */
    data: T[];
    /** Join statistics */
    stats: {
        /** Left side row count */
        leftRows: number;
        /** Right side row count */
        rightRows: number;
        /** Matched pairs */
        matchedPairs: number;
        /** Result row count */
        resultRows: number;
        /** Join strategy used */
        strategy: 'hash' | 'nested_loop' | 'sort_merge' | 'semantic' | 'graph';
        /** Execution time in milliseconds */
        executionTime: number;
    };
}
/**
 * Check if a join condition is compound
 */
export declare function isCompoundCondition(condition: IJoinCondition | ICompoundJoinCondition): condition is ICompoundJoinCondition;
/**
 * Check if a join is a standard SQL-style join
 */
export declare function isStandardJoin(type: JoinType): type is StandardJoinType;
/**
 * Parse a field path into alias and field name
 *
 * @example
 * parseFieldPath('u.name') // { alias: 'u', field: 'name' }
 * parseFieldPath('name')    // { alias: undefined, field: 'name' }
 */
export declare function parseFieldPath(path: string): {
    alias?: string;
    field: string;
};
/**
 * Build a field path from alias and field name
 */
export declare function buildFieldPath(alias: string | undefined, field: string): string;
/**
 * Extract all source aliases from a list of join clauses
 */
export declare function extractJoinAliases(joins: IJoinClause[]): string[];
/**
 * Validate join clause configuration
 */
export declare function validateJoinClause(join: IJoinClause): string[];