/**
 * Semantic dataset client internals.
 *
 * Public callers use `createDatasetClient(...).execute(...)`. The implementation
 * stays database-agnostic via query-builder and backend protocol interfaces.
 */
import type { MetricRef, GrainedMetricRef, MetricQuery, MetricQueryFor, MetricResult, MetricResultFor, DatasetQuery, DatasetQueryFor, DatasetQueryResult, DatasetQueryResultFor, ExecutionContext, AnyDatasetInstance, DatasetInstance } from './types.js';
import type { QueryBuilderFactoryLike, QueryBuilderFactoryInput } from './query-builder-protocol.js';
import type { PlanNode, SemanticBackend } from './semantic-plan.js';
import { type ValidationResult } from './validation.js';
import { type DatasetQueryExecutionOptions } from './dataset-query.js';
import { type SemanticCacheOptions, type SemanticCacheStats } from './cache/semantic-query-cache.js';
export interface MetricQueryEngineOptions {
    /** Query builder factory for executing metrics. */
    builderFactory: QueryBuilderFactoryInput;
}
export interface CreateDatasetClientOptions {
    /** Query builder factory for executing semantic metric and dataset queries. */
    queryBuilder?: QueryBuilderFactoryInput;
    /**
     * Semantic backend for executing neutral semantic plans.
     *
     * @deprecated Use `queryBuilder` instead — the query-builder path is
     * canonical. The plan/backend path is frozen (bug fixes only) and will not
     * gain new features.
     */
    backend?: SemanticBackend;
    /**
     * Result-cache defaults for this client. Results are keyed by the canonical
     * query signature (target, dimensions, measures, filters, ordering,
     * pagination, grain, and tenant scope). Individual calls can override or
     * bypass via `ExecutionContext.cache`; per-call `{ cache: { ttlMs } }` works
     * even when this option is omitted.
     */
    cache?: SemanticCacheOptions;
}
export type SemanticTarget = MetricRef | GrainedMetricRef | AnyDatasetInstance;
export type SemanticQuery<TTarget extends SemanticTarget> = TTarget extends AnyDatasetInstance ? DatasetQuery : MetricQuery;
export type SemanticResult<TTarget extends SemanticTarget, TRow = Record<string, unknown>> = TTarget extends AnyDatasetInstance ? DatasetQueryResult<TRow> : MetricResult<TRow>;
type TypedDataset<TDatasetName extends string = string> = DatasetInstance<any, any, any, TDatasetName>;
type TypedMetricRef<TDatasetName extends string, TMetricName extends string, TDataset extends TypedDataset<TDatasetName>> = MetricRef<TDatasetName, TMetricName, any, TDataset>;
type TypedGrainedMetricRef<TDatasetName extends string, TMetricName extends string, TDataset extends TypedDataset<TDatasetName>> = GrainedMetricRef<TDatasetName, TMetricName, any, TDataset>;
export interface DatasetClient {
    execute<TDataset extends TypedDataset, const TQuery extends DatasetQueryFor<TDataset> = DatasetQueryFor<TDataset>>(target: TDataset, query?: TQuery, context?: ExecutionContext): Promise<DatasetQueryResultFor<TDataset, TQuery>>;
    execute<TDatasetName extends string, TMetricName extends string, TDataset extends TypedDataset<TDatasetName>, const TQuery extends MetricQueryFor<TDataset, TMetricName> = MetricQueryFor<TDataset, TMetricName>>(target: TypedMetricRef<TDatasetName, TMetricName, TDataset>, query?: TQuery, context?: ExecutionContext): Promise<MetricResultFor<TDataset, TMetricName, TQuery>>;
    execute<TDatasetName extends string, TMetricName extends string, TDataset extends TypedDataset<TDatasetName>, const TQuery extends MetricQueryFor<TDataset, TMetricName> = MetricQueryFor<TDataset, TMetricName>>(target: TypedGrainedMetricRef<TDatasetName, TMetricName, TDataset>, query?: TQuery, context?: ExecutionContext): Promise<MetricResultFor<TDataset, TMetricName, TQuery>>;
    execute<TRow = Record<string, unknown>, TTarget extends SemanticTarget = SemanticTarget>(target: TTarget, query?: SemanticQuery<TTarget>, context?: ExecutionContext): Promise<SemanticResult<TTarget, TRow>>;
    toSQL<TTarget extends SemanticTarget>(target: TTarget, query?: SemanticQuery<TTarget>, context?: ExecutionContext): string;
    validate<TTarget extends SemanticTarget>(target: TTarget, query?: SemanticQuery<TTarget>, context?: ExecutionContext): ValidationResult;
    /** Lookup counters for this client's semantic result cache. */
    getCacheStats(): SemanticCacheStats;
    /**
     * Clears the semantic result cache. Returns false when the configured store
     * does not support clearing (see `SemanticCacheStats.clearSupported`).
     */
    clearCache(): Promise<boolean>;
}
export declare class MetricQueryEngine {
    private builderFactory;
    constructor(options: MetricQueryEngineOptions);
    protected getBuilderFactory(): QueryBuilderFactoryLike;
    /**
     * Execute a metric query. Generates SQL, applies tenant/filter context, executes.
     */
    run<T = Record<string, unknown>>(metric: MetricRef | GrainedMetricRef, query?: MetricQuery, context?: ExecutionContext): Promise<MetricResult<T>>;
    /**
     * Generate SQL without executing.
     */
    toSQL(metric: MetricRef | GrainedMetricRef, query?: MetricQuery, context?: ExecutionContext): string;
    /**
     * Validate a metric query against the metric's contract.
     */
    validate(metric: MetricRef | GrainedMetricRef, query: MetricQuery, context?: ExecutionContext): ValidationResult;
    private runViaBuilder;
    private buildBaseQuery;
    private buildDerivedSQLViaBuilder;
}
export declare class DatasetClientImpl extends MetricQueryEngine implements DatasetClient {
    private backend?;
    private readonly queryCache;
    private readonly cacheEnabledByDefault;
    private readonly defaultCacheScope?;
    constructor(options: CreateDatasetClientOptions);
    getCacheStats(): SemanticCacheStats;
    clearCache(): Promise<boolean>;
    /**
     * True when this call can hit the cache — either the client has a default
     * TTL or the call opts in via `context.cache`. Skips signature building for
     * the common uncached path.
     */
    private isCacheable;
    /**
     * Context used for cache-key building: fills in the client-level default
     * `cache.scope` unless the call sets its own, so clients sharing a custom
     * store can be namespaced apart.
     */
    private signatureContext;
    planMetric(metric: MetricRef | GrainedMetricRef, query?: MetricQuery, context?: ExecutionContext): PlanNode;
    planDataset(ds: AnyDatasetInstance, query?: DatasetQuery, context?: ExecutionContext): PlanNode;
    /**
     * Execute a semantic target.
     */
    execute<TDataset extends DatasetInstance<any, any, any, any>, const TQuery extends DatasetQueryFor<TDataset> = DatasetQueryFor<TDataset>>(target: TDataset, query?: TQuery, context?: ExecutionContext): Promise<DatasetQueryResultFor<TDataset, TQuery>>;
    execute<TDatasetName extends string, TMetricName extends string, TDataset extends DatasetInstance<any, any, any, TDatasetName>, const TQuery extends MetricQueryFor<TDataset, TMetricName> = MetricQueryFor<TDataset, TMetricName>>(target: MetricRef<TDatasetName, TMetricName, any, TDataset>, query?: TQuery, context?: ExecutionContext): Promise<MetricResultFor<TDataset, TMetricName, TQuery>>;
    execute<TDatasetName extends string, TMetricName extends string, TDataset extends DatasetInstance<any, any, any, TDatasetName>, const TQuery extends MetricQueryFor<TDataset, TMetricName> = MetricQueryFor<TDataset, TMetricName>>(target: GrainedMetricRef<TDatasetName, TMetricName, any, TDataset>, query?: TQuery, context?: ExecutionContext): Promise<MetricResultFor<TDataset, TMetricName, TQuery>>;
    toSQL<TTarget extends SemanticTarget>(target: TTarget, query?: SemanticQuery<TTarget>, context?: ExecutionContext): string;
    validate<TTarget extends SemanticTarget>(target: TTarget, query?: SemanticQuery<TTarget>, context?: ExecutionContext): ValidationResult;
    private executeMetric;
    private executeDataset;
    private toDatasetSQL;
}
export declare function createDatasetClient(options: CreateDatasetClientOptions): DatasetClient;
export type { DatasetQueryExecutionOptions };
//# sourceMappingURL=executor.d.ts.map