/**
 * Query-builder-path planning for to-one relationship joins.
 *
 * When a dataset/metric query references relationship-qualified fields
 * (`<relationship>.<field>`), the builder path aliases the joined target with
 * the relationship name, table-qualifies base columns with the base source
 * name, and aliases joined selections back to their quoted qualified name. When
 * no qualified field is referenced, no context is produced and the builder path
 * behaves exactly as before.
 */
import type { AnyDatasetInstance, DatasetQuery, ExecutionContext, MetricQuery } from '../types.js';
import type { QueryBuilderLike } from '../query-builder-protocol.js';
import { type TenantPredicate } from './tenant-runtime.js';
export interface ResolvedBuilderJoin {
    /** Relationship name, used as the joined table's SQL alias. */
    relationship: string;
    /** Physical target source table. */
    source: string;
    /** Base join column (unqualified). */
    from: string;
    /** Target join column (unqualified). */
    to: string;
    /** Tenant predicate applied to the joined target, when active. */
    tenant?: TenantPredicate & {
        field: string;
    };
}
export interface RelationshipBuilderContext {
    baseSource: string;
    joins: ResolvedBuilderJoin[];
    joinByRelationship: Map<string, ResolvedBuilderJoin>;
}
type QueryLike = Pick<DatasetQuery & MetricQuery, 'dimensions' | 'filters' | 'orderBy'>;
/**
 * Builds the join context for a query, or returns undefined when the query
 * references no relationship-qualified fields. Validation runs first, so any
 * qualified name that fails to resolve here is skipped defensively.
 */
export declare function buildRelationshipBuilderContext(ds: AnyDatasetInstance, query: QueryLike, context?: ExecutionContext): RelationshipBuilderContext | undefined;
/** Qualifies a base physical column with the base source when joins are active. */
export declare function qualifyBaseColumn(ctx: RelationshipBuilderContext | undefined, column: string): string;
/**
 * Resolves a relationship-qualified field to its SQL column reference
 * (`<relationship>.<targetColumn>`). Throws if the name cannot be resolved,
 * which should be unreachable after validation.
 */
export declare function resolveQualifiedColumn(ds: AnyDatasetInstance, name: string): string;
/**
 * Applies each relationship LEFT JOIN to the builder and, when runtime tenancy
 * is active on a target, scopes the joined rows with the tenant predicate.
 * Builders that support single-match joins (`leftAnyJoin`, e.g. ClickHouse
 * `LEFT ANY JOIN`) get them so duplicate target keys cannot fan out aggregates.
 */
export declare function applyRelationshipJoins(qb: QueryBuilderLike, ctx: RelationshipBuilderContext | undefined): QueryBuilderLike;
export {};
//# sourceMappingURL=relationship-builder-plan.d.ts.map