@hypequery/datasets 0.1.0 → 0.2.1

package/dist/catalog.js

@@ -0,0 +1,105 @@
+import { SEMANTIC_FILTER_OPERATORS, SUPPORTED_TIME_GRAINS } from './constants.js';
+function dimensionToCatalog(dimension) {
+    return {
+        type: dimension.fieldType,
+        column: dimension.column,
+        sql: dimension.sql,
+        label: dimension.label,
+        description: dimension.description,
+        filterable: dimension.filterable !== false,
+        groupable: dimension.groupable !== false,
+    };
+}
+function measureToCatalog(measure) {
+    return {
+        aggregation: measure.aggregation,
+        field: measure.field,
+        sql: measure.sql,
+        label: measure.label,
+        description: measure.description,
+        filterCount: measure.filters?.length ?? 0,
+    };
+}
+function filterToCatalog(filter, dimensions) {
+    return {
+        field: filter.field,
+        label: filter.label,
+        description: filter.description,
+        operators: filter.operators ? [...filter.operators] : [...SEMANTIC_FILTER_OPERATORS],
+        valueType: dimensions[filter.field]?.fieldType,
+    };
+}
+function metricToCatalog(metric) {
+    const contract = metric.contract();
+    return {
+        kind: contract.kind,
+        dataset: contract.dataset,
+        valueType: contract.valueType,
+        label: contract.label,
+        description: contract.description,
+        dimensions: contract.dimensions,
+        measures: contract.measures,
+        filters: contract.filters,
+        grains: contract.grains,
+        grain: contract.grain,
+        requires: contract.requires,
+    };
+}
+function relationshipToCatalog(relationship) {
+    return {
+        kind: relationship.kind,
+        target: relationship.target().name,
+        from: relationship.from,
+        to: relationship.to,
+        execution: 'metadata_only',
+    };
+}
+export function getDatasetCatalog(dataset) {
+    const dimensionNames = Object.keys(dataset.dimensions);
+    const measureNames = Object.keys(dataset.measures);
+    const metricNames = Object.keys(dataset.metrics ?? {});
+    const supportedGrains = dataset.timeKey ? [...SUPPORTED_TIME_GRAINS] : [];
+    const maxLimit = dataset.limits?.maxResultSize;
+    return {
+        name: dataset.name,
+        source: dataset.source,
+        tenantKey: dataset.tenantKey,
+        timeKey: dataset.timeKey,
+        dimensions: Object.fromEntries(Object.entries(dataset.dimensions).map(([name, dimension]) => [
+            name,
+            dimensionToCatalog(dimension),
+        ])),
+        measures: Object.fromEntries(Object.entries(dataset.measures).map(([name, measure]) => [
+            name,
+            measureToCatalog(measure),
+        ])),
+        metrics: Object.fromEntries(Object.entries(dataset.metrics ?? {}).map(([name, metric]) => [
+            name,
+            metricToCatalog(metric),
+        ])),
+        filters: Object.fromEntries(Object.entries(dataset.filters).map(([name, filter]) => [
+            name,
+            filterToCatalog(filter, dataset.dimensions),
+        ])),
+        relationships: Object.fromEntries(Object.entries(dataset.relationships).map(([name, relationship]) => [
+            name,
+            relationshipToCatalog(relationship),
+        ])),
+        limits: dataset.limits,
+        requiresTenant: !!dataset.tenantKey,
+        supportedGrains,
+        orderableFields: [
+            ...dimensionNames,
+            ...measureNames,
+            ...metricNames,
+            ...(dataset.timeKey ? ['period'] : []),
+        ],
+        maxLimit,
+    };
+}
+export function getDatasetCatalogs(datasets) {
+    return Object.fromEntries(Object.entries(datasets).map(([name, dataset]) => [
+        name,
+        getDatasetCatalog(dataset),
+    ]));
+}

package/dist/constants.d.ts

@@ -6,4 +6,17 @@ import type { TimeGrain } from './types.js';
  * Maps time grain to ClickHouse date truncation functions.
  */
 export declare const GRAIN_FUNCTIONS: Record<TimeGrain, string>;
+/**
+ * The set of time grains supported by the planner. Derived from
+ * {@link GRAIN_FUNCTIONS} so the two never drift apart.
+ */
+export declare const SUPPORTED_TIME_GRAINS: TimeGrain[];
+/**
+ * The filter operators accepted by semantic dataset and metric inputs.
+ */
+export declare const SEMANTIC_FILTER_OPERATORS: readonly ["eq", "neq", "gt", "gte", "lt", "lte", "in", "notIn", "between", "like"];
+/**
+ * Narrowing guard for a runtime-provided grain value.
+ */
+export declare function isSupportedTimeGrain(grain: unknown): grain is TimeGrain;
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAMrD,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAgB,SAAS,EAAE,MAAM,YAAY,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAMrD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAmC,SAAS,EAAE,CAAC;AAEjF;;GAEG;AACH,eAAO,MAAM,yBAAyB,oFAWkB,CAAC;AAEzD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAEvE"}

package/dist/constants.js

@@ -11,3 +11,29 @@ export const GRAIN_FUNCTIONS = {
     quarter: 'toStartOfQuarter',
     year: 'toStartOfYear',
 };
+/**
+ * The set of time grains supported by the planner. Derived from
+ * {@link GRAIN_FUNCTIONS} so the two never drift apart.
+ */
+export const SUPPORTED_TIME_GRAINS = Object.keys(GRAIN_FUNCTIONS);
+/**
+ * The filter operators accepted by semantic dataset and metric inputs.
+ */
+export const SEMANTIC_FILTER_OPERATORS = [
+    'eq',
+    'neq',
+    'gt',
+    'gte',
+    'lt',
+    'lte',
+    'in',
+    'notIn',
+    'between',
+    'like',
+];
+/**
+ * Narrowing guard for a runtime-provided grain value.
+ */
+export function isSupportedTimeGrain(grain) {
+    return typeof grain === 'string' && Object.hasOwn(GRAIN_FUNCTIONS, grain);
+}

package/dist/dataset-query.d.ts

@@ -0,0 +1,16 @@
+import type { AnyDatasetInstance, DatasetQuery, DatasetQueryResult, ExecutionContext } from './types.js';
+import type { QueryBuilderFactoryLike, QueryBuilderLike } from './query-builder-protocol.js';
+import { type ValidationResult } from './validation.js';
+export interface DatasetQueryExecutionOptions {
+    builderFactory: QueryBuilderFactoryLike;
+    context?: ExecutionContext;
+    /**
+     * Overrides the SQL `LIMIT` without affecting validation (which still uses
+     * `query.limit`). Used to over-fetch one row for pagination's `hasMore`.
+     */
+    executionLimit?: number;
+}
+export declare function validateDatasetQuery(ds: AnyDatasetInstance, query: DatasetQuery, context?: ExecutionContext): ValidationResult;
+export declare function buildDatasetQueryBuilder(ds: AnyDatasetInstance, query: DatasetQuery, options: DatasetQueryExecutionOptions): QueryBuilderLike;
+export declare function runDatasetQuery(ds: AnyDatasetInstance, query: DatasetQuery, options: DatasetQueryExecutionOptions): Promise<DatasetQueryResult>;
+//# sourceMappingURL=dataset-query.d.ts.map

package/dist/dataset-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-query.d.ts","sourceRoot":"","sources":["../src/dataset-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAQ7F,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAoBxD,MAAM,WAAW,4BAA4B;IAC3C,cAAc,EAAE,uBAAuB,CAAC;IACxC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAElB;AAED,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,GACpC,gBAAgB,CAwClB;AAED,wBAAsB,eAAe,CACnC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,kBAAkB,CAAC,CAa7B"}

package/dist/dataset-query.js

@@ -0,0 +1,56 @@
+import { appendOrderLimitOffset, applyMeasureDefinition, buildDimensionSelectionPlan, resolveFilterField, resolveTenantFilterColumn, } from './query-planner.js';
+import { validateDatasetQueryInput } from './utils/dataset-query-validation.js';
+import { getRuntimeTenantId, getRuntimeTenantPredicate, } from './utils/tenant-runtime.js';
+import { applyPagination, overfetchLimit } from './utils/pagination.js';
+function toResultMeta(qb, timingMs, context) {
+    return {
+        sql: qb.toSQLWithParams().sql,
+        timingMs,
+        tenant: getRuntimeTenantId(context),
+    };
+}
+export function validateDatasetQuery(ds, query, context) {
+    return validateDatasetQueryInput(ds, query, context);
+}
+export function buildDatasetQueryBuilder(ds, query, options) {
+    const validation = validateDatasetQuery(ds, query, options.context);
+    if (!validation.valid) {
+        throw new Error(`Invalid dataset query: ${validation.errors.join('; ')}`);
+    }
+    let qb = options.builderFactory.table(ds.source);
+    const { selectParts, groupByParts } = buildDimensionSelectionPlan(ds, query.dimensions ?? [], query.by);
+    const measureNames = query.measures ?? Object.keys(ds.measures);
+    if (selectParts.length > 0) {
+        qb = qb.select(selectParts);
+    }
+    for (const measureName of measureNames) {
+        qb = applyMeasureDefinition(qb, ds, measureName, ds.measures[measureName]);
+    }
+    if (groupByParts.length > 0) {
+        qb = qb.groupBy(groupByParts);
+    }
+    const tenantColumn = resolveTenantFilterColumn(ds, options.context);
+    const tenantPredicate = getRuntimeTenantPredicate(options.context);
+    if (tenantPredicate && tenantColumn) {
+        qb = qb.where(tenantColumn, tenantPredicate.operator, tenantPredicate.value);
+    }
+    for (const filter of query.filters ?? []) {
+        const resolvedField = resolveFilterField(ds, filter.field);
+        qb = qb.where(resolvedField, filter.operator, filter.value);
+    }
+    return appendOrderLimitOffset(qb, query.orderBy, query.by, options.executionLimit ?? query.limit, query.offset);
+}
+export async function runDatasetQuery(ds, query, options) {
+    const start = Date.now();
+    // Over-fetch one row so we can report `hasMore` without a count query.
+    const qb = buildDatasetQueryBuilder(ds, query, {
+        ...options,
+        executionLimit: overfetchLimit(query.limit),
+    });
+    const rows = await qb.execute();
+    const { data, pagination } = applyPagination(rows, query.limit, query.offset);
+    return {
+        data,
+        meta: { ...toResultMeta(qb, Date.now() - start, options.context), rowCount: data.length, pagination },
+    };
+}

package/dist/dataset.d.ts

@@ -29,5 +29,5 @@
  * ```
  */
 import type { DatasetConfig, DatasetInstance, DimensionDefinition, MeasureDefinition, RelationshipDefinition } from './types.js';
-export declare function dataset<TDimensions extends Record<string, DimensionDefinition>, TMeasures extends Record<string, MeasureDefinition> = Record<string, never>, TRelationships extends Record<string, RelationshipDefinition> = Record<string, never>>(name: string, config: DatasetConfig<TDimensions, TMeasures, TRelationships>): DatasetInstance<TDimensions, TMeasures, TRelationships>;
+export declare function dataset<TDatasetName extends string, TDimensions extends Record<string, DimensionDefinition>, TMeasures extends Record<string, MeasureDefinition> = Record<string, never>, TRelationships extends Record<string, RelationshipDefinition> = Record<string, never>>(name: TDatasetName, config: DatasetConfig<TDimensions, TMeasures, TRelationships>): DatasetInstance<TDimensions, TMeasures, TRelationships, TDatasetName>;
 //# sourceMappingURL=dataset.d.ts.map

package/dist/dataset.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset.d.ts","sourceRoot":"","sources":["../src/dataset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EAYvB,MAAM,YAAY,CAAC;AAqMpB,wBAAgB,OAAO,CACrB,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACvD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAC3E,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAErF,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC,GAC5D,eAAe,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC,CAgEzD"}
+{"version":3,"file":"dataset.d.ts","sourceRoot":"","sources":["../src/dataset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EAKvB,MAAM,YAAY,CAAC;AAkBpB,wBAAgB,OAAO,CACrB,YAAY,SAAS,MAAM,EAC3B,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACvD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAC3E,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAErF,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC,GAC5D,eAAe,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,YAAY,CAAC,CA2DvE"}

package/dist/dataset.js

@@ -28,135 +28,29 @@
  * });
  * ```
  */
-const ALL_GRAINS = ['day', 'week', 'month', 'quarter', 'year'];
-const NUMERIC_FIELD_TYPES = new Set(['number']);
-function isDerivedMetricConfig(config) {
-    return 'uses' in config && 'formula' in config;
-}
-function buildContract(metricName, ds, spec, label, description, grain) {
-    const dimensionNames = Object.keys(ds.dimensions);
-    const measureNames = Object.keys(ds.measures);
-    const filterNames = Object.keys(ds.filters).length > 0
-        ? Object.keys(ds.filters)
-        : dimensionNames.filter((name) => ds.dimensions[name]?.filterable !== false);
-    const kind = grain
-        ? 'grained_metric'
-        : spec.__type === 'derived_metric_spec'
-            ? 'derived_metric'
-            : 'metric';
-    return {
-        kind,
-        name: metricName,
-        dataset: ds.name,
-        valueType: 'number',
-        label,
-        description,
-        dimensions: dimensionNames,
-        measures: measureNames,
-        filters: filterNames,
-        grains: ds.timeKey ? ALL_GRAINS : [],
-        grain,
-        requires: spec.__type === 'derived_metric_spec'
-            ? Object.keys(spec.uses)
-            : undefined,
-        tenantScoped: !!ds.tenantKey,
-    };
-}
-function createMetricRef(ds, name, spec, label, description) {
-    const ref = {
-        __type: 'metric_ref',
-        datasetName: ds.name,
-        name,
-        spec,
-        label,
-        description,
-        dataset: ds,
-        by(grain) {
-            if (!ds.timeKey) {
-                throw new Error(`Cannot apply .by("${grain}") to metric "${name}" — ` +
-                    `dataset "${ds.name}" has no timeKey defined.`);
-            }
-            return {
-                __type: 'grained_metric_ref',
-                metric: ref,
-                grain,
-                contract() {
-                    return buildContract(name, ds, spec, label, description, grain);
-                },
-            };
-        },
-        contract() {
-            return buildContract(name, ds, spec, label, description);
-        },
-    };
-    return ref;
-}
-function validateBaseMetric(ds, metricName, spec, options) {
-    const dimension = ds.dimensions[spec.field];
-    if (!dimension && !options?.allowHiddenField) {
-        throw new Error(`Invalid metric "${metricName}": dimension "${spec.field}" does not exist on dataset "${ds.name}".`);
-    }
-    if (dimension &&
-        (spec.aggregation === 'sum' || spec.aggregation === 'avg') &&
-        !NUMERIC_FIELD_TYPES.has(dimension.fieldType)) {
-        throw new Error(`Invalid metric "${metricName}": ${spec.aggregation}() requires a numeric dimension, but "${spec.field}" is ${dimension.fieldType}.`);
-    }
-}
-function validateDerivedMetric(ds, metricName, config) {
-    const usedMetrics = Object.entries(config.uses);
-    if (usedMetrics.length === 0) {
-        throw new Error(`Invalid metric "${metricName}": derived metrics must reference at least one base metric.`);
-    }
-    for (const [alias, metric] of usedMetrics) {
-        if (metric.datasetName !== ds.name) {
-            throw new Error(`Invalid metric "${metricName}": referenced metric "${alias}" belongs to dataset "${metric.datasetName}", expected "${ds.name}".`);
-        }
-        if (metric.spec.__type !== 'aggregation_spec') {
-            throw new Error(`Invalid metric "${metricName}": referenced metric "${alias}" must be a base aggregation on dataset "${ds.name}".`);
-        }
-    }
-}
-function normalizeDimensions(config) {
-    return config.dimensions;
-}
-function normalizeFilters(dimensions, filters) {
-    if (filters) {
-        return filters;
-    }
-    return Object.fromEntries(Object.entries(dimensions)
-        .filter(([, definition]) => definition.filterable !== false)
-        .map(([name]) => [
-        name,
-        {
-            __type: 'filter_definition',
-            field: name,
-        },
-    ]));
-}
-function measureToAggregationSpec(measureName, definition) {
-    if (!definition.field) {
-        throw new Error(`Invalid measure "${measureName}": a backing field is required.`);
-    }
-    return {
-        __type: 'aggregation_spec',
-        aggregation: definition.aggregation,
-        field: definition.field,
-    };
-}
-function buildDatasetQueryContract(ds, config) {
-    return {
-        dataset: ds.name,
-        dimensions: config.dimensions ? [...config.dimensions] : Object.keys(ds.dimensions),
-        measures: config.measures ? [...config.measures] : Object.keys(ds.measures),
-        filters: Object.keys(ds.filters),
-        grains: ds.timeKey ? ALL_GRAINS : [],
-        tenantScoped: !!ds.tenantKey,
-    };
-}
+import { createDerivedMetricSpec, createMetricRef, isDerivedMetricConfig, } from './utils/dataset-metric-ref.js';
+import { measureToAggregationSpec, normalizeDimensions, normalizeFilters, normalizeMeasures, normalizeRelationships, } from './utils/dataset-normalization.js';
+import { validateBaseMetric, validateDerivedMetric, } from './utils/dataset-validation.js';
 export function dataset(name, config) {
     const dimensions = normalizeDimensions(config);
-    const measures = (config.measures ?? {});
+    const measures = normalizeMeasures(config.measures);
     const filters = normalizeFilters(dimensions, config.filters);
+    const relationships = normalizeRelationships(config.relationships);
+    function metric(metricName, metricConfig) {
+        if (isDerivedMetricConfig(metricConfig)) {
+            validateDerivedMetric(ds, metricName, metricConfig);
+            const derivedSpec = createDerivedMetricSpec(metricConfig);
+            return createMetricRef(ds, metricName, derivedSpec, metricConfig.label, metricConfig.description);
+        }
+        const measureName = metricConfig.measure;
+        const measure = ds.measures[measureName];
+        if (!measure) {
+            throw new Error(`Invalid metric "${metricName}": measure "${measureName}" does not exist on dataset "${ds.name}".`);
+        }
+        const spec = measureToAggregationSpec(measureName, measure);
+        validateBaseMetric(ds, metricName, spec, { allowHiddenField: true });
+        return createMetricRef(ds, metricName, spec, metricConfig.label ?? measure.label, metricConfig.description ?? measure.description);
+    }
     const ds = {
         __type: 'dataset',
         name,
@@ -166,38 +60,9 @@ export function dataset(name, config) {
         dimensions,
         measures,
         filters,
-        relationships: (config.relationships ?? {}),
+        relationships,
         limits: config.limits,
-        metric(metricName, metricConfig) {
-            if (isDerivedMetricConfig(metricConfig)) {
-                validateDerivedMetric(ds, metricName, metricConfig);
-                const derivedSpec = {
-                    __type: 'derived_metric_spec',
-                    uses: metricConfig.uses,
-                    formula: metricConfig.formula,
-                };
-                return createMetricRef(ds, metricName, derivedSpec, metricConfig.label, metricConfig.description);
-            }
-            // Base metric (measure-based)
-            const measureName = metricConfig.measure;
-            const measure = ds.measures[measureName];
-            if (!measure) {
-                throw new Error(`Invalid metric "${metricName}": measure "${measureName}" does not exist on dataset "${ds.name}".`);
-            }
-            const spec = measureToAggregationSpec(measureName, measure);
-            validateBaseMetric(ds, metricName, spec, { allowHiddenField: true });
-            return createMetricRef(ds, metricName, spec, metricConfig.label ?? measure.label, metricConfig.description ?? measure.description);
-        },
-        query(queryConfig) {
-            return {
-                __type: 'dataset_query_ref',
-                dataset: ds,
-                config: queryConfig,
-                contract() {
-                    return buildDatasetQueryContract(ds, queryConfig);
-                },
-            };
-        }
+        metric,
     };
     return ds;
 }

package/dist/executor.d.ts

@@ -1,25 +1,36 @@
 /**
- * MetricExecutor — resolves metrics to SQL and executes them.
+ * Semantic dataset client internals.
  *
- * Supports two modes:
- * 1. **Query builder** (recommended) — pass a `QueryBuilderFactoryLike` and the
- *    executor builds queries via the builder's fluent API, then calls `.execute()`.
- * 2. **Raw adapter** (deprecated) — pass a `MetricAdapter` with a `rawQuery` function
- *    and the executor generates SQL strings manually.
- *
- * The executor stays DB-agnostic via duck-typed protocol interfaces.
+ * Public callers use `createDatasetClient(...).execute(...)`. The implementation
+ * stays database-agnostic via query-builder and backend protocol interfaces.
  */
-import type { MetricRef, GrainedMetricRef, MetricQuery, MetricResult, ExecutionContext } from './types.js';
+import type { MetricRef, GrainedMetricRef, MetricQuery, MetricResult, DatasetQuery, DatasetQueryResult, ExecutionContext, AnyDatasetInstance } from './types.js';
 import type { QueryBuilderFactoryLike } from './query-builder-protocol.js';
+import type { PlanNode, SemanticBackend } from './semantic-plan.js';
 import { type ValidationResult } from './validation.js';
-export interface MetricExecutorOptions {
+import { type DatasetQueryExecutionOptions } from './dataset-query.js';
+export interface MetricQueryEngineOptions {
     /** Query builder factory for executing metrics. */
     builderFactory: QueryBuilderFactoryLike;
 }
-export declare class MetricExecutor {
+export interface CreateDatasetClientOptions {
+    /** Query builder factory for executing semantic metric and dataset queries. */
+    queryBuilder?: QueryBuilderFactoryLike;
+    /** Semantic backend for executing neutral semantic plans. */
+    backend?: SemanticBackend;
+}
+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>;
+export interface DatasetClient {
+    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;
+}
+export declare class MetricQueryEngine {
     private builderFactory;
-    constructor(options: MetricExecutorOptions);
-    getBuilderFactory(): QueryBuilderFactoryLike;
+    constructor(options: MetricQueryEngineOptions);
+    protected getBuilderFactory(): QueryBuilderFactoryLike;
     /**
      * Execute a metric query. Generates SQL, applies tenant/filter context, executes.
      */
@@ -31,9 +42,26 @@ export declare class MetricExecutor {
     /**
      * Validate a metric query against the metric's contract.
      */
-    validate(metric: MetricRef | GrainedMetricRef, query: MetricQuery): ValidationResult;
+    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?;
+    constructor(options: CreateDatasetClientOptions);
+    planMetric(metric: MetricRef | GrainedMetricRef, query?: MetricQuery, context?: ExecutionContext): PlanNode;
+    planDataset(ds: AnyDatasetInstance, query?: DatasetQuery, context?: ExecutionContext): PlanNode;
+    /**
+     * Execute a semantic target.
+     */
+    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;
+    private executeMetric;
+    private executeDataset;
+    private toDatasetSQL;
+}
+export declare function createDatasetClient(options: CreateDatasetClientOptions): DatasetClient;
+export type { DatasetQueryExecutionOptions };
 //# sourceMappingURL=executor.d.ts.map

package/dist/executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,YAAY,EAGZ,gBAAgB,EAOjB,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAEV,uBAAuB,EACxB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAyC,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAwG/F,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,cAAc,EAAE,uBAAuB,CAAC;CACzC;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,cAAc,CAA0B;gBAEpC,OAAO,EAAE,qBAAqB;IAI1C,iBAAiB,IAAI,uBAAuB;IAI5C;;OAEG;IACG,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,GAAE,WAAgB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAU3B;;OAEG;IACH,KAAK,CACH,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,GAAE,WAAgB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM;IAaT;;OAEG;IACH,QAAQ,CACN,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,EAAE,WAAW,GACjB,gBAAgB;YAQL,aAAa;IA2B3B,OAAO,CAAC,cAAc;IAgDtB,OAAO,CAAC,yBAAyB;CA0FlC"}
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"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"}