semanticdb-v2 2.0.0-alpha.10 → 2.0.0-alpha.12

package/README.md

@@ -22,12 +22,13 @@ providers across executions; call `await Logicform.close()` during application s
 
 ```ts
 import { Logicform } from 'semanticdb-v2';
+import type { SchemaMappingDefinition } from 'semanticdb-v2';
 
-const schemaMappings = [
+const schemaMappings: SchemaMappingDefinition[] = [
   {
     schemaId: 'sales',
     connectionId: 'analytics',
-    source: 'analytics.sales_detail',
+    source: { kind: 'table', table: 'analytics.sales_detail' },
     mappings: [],
     freshness: { mode: 'ttl', ttlSeconds: 300 },
   },
@@ -68,6 +69,10 @@ A successful response always includes `total`, the number of result rows before
 `limit`/`page` pagination. For grouped LogicForms this is the number of groups after `having` and
 `limitBy`. Paginated physical queries include a separate `sqls` entry with `type: 'total'` for the
 count query; unpaginated and executor-merged results derive the value without another SQL query.
+For entity sampling, `total` counts distinct eligible entities before sampling. See
+[Entity sampling](docs/entity-sampling.md) for boolean `sample`, top-level `limit`, and sorting rules.
+See [Demo data perturbation](docs/random-data.md) for `randomData`, which applies random multipliers
+to final numeric output values while preserving group keys and identities.
 
 The v2 LogicForm contract requires `version` on executable LogicForms, including LogicForm objects
 used as subqueries, and accepts semantic versions greater than or equal to `2.0`. At the public
@@ -280,7 +285,7 @@ commands that have already reached the database.
 
 ### Permissions
 
-Pass table, row, and column permissions together through `ExecuteOptions.permissions`:
+Pass table, row, column, and custom metric permissions through `ExecuteOptions.permissions`:
 
 ```ts
 import type { Permissions } from 'semanticdb-v2';
@@ -326,6 +331,15 @@ filters, grouping, operator inputs, and relation paths. A row policy may still u
 column as an internal filter. If an ID is not whitelisted, SemanticDB generates the executor-owned
 result-row `_id` instead of exposing the physical ID as that identity.
 
+Custom metrics have a separate Schema catalog (`metrics: ['均价']`) and user policy
+(`metricPermissions: { whitelist: ['均价'] }`). Omission preserves unrestricted metric access;
+`[]` denies all custom metrics and `'*'` permits the current Schema's catalog. Metric names never
+belong in `columnPermissions`. Compound metrics require permission for their internal custom
+metrics and underlying properties; generated child queries retain table and row checks.
+Permissions are validated only for Schemas reached by the execution.
+See [the interface and YiAsk migration example](docs/metric-permissions.md) for dependency
+contracts, compatibility behavior, and complete configuration examples.
+
 ### Component operators
 
 Composite metrics are regular `OperatorDefinition` values with `kind: 'component'`. Their
@@ -341,7 +355,14 @@ names shared by both sides unless an exceptional custom operator explicitly supp
 
 See [Register an operator](docs/register-operator.md) for the component contract.
 
-The root entry point accepts a `connections` array of `DatabaseConnection` items. Every item has a unique `id`; set `kind` to `mysql`,
+DuckDB accepts customer `.duckdb` files (`path`, read-only by default) and managed
+shared upload datasets (`directory`). `DBConnector.importFile()` supports `.xlsx`
+and CSV, fixed column definitions, idempotent batches and batch replacement.
+CSV automatically accepts UTF-8/BOM-marked Unicode; specify `gbk` or `gb18030` for
+legacy Chinese files. See [DuckDB and file imports](docs/file-import.md) for PM2
+sharing, configuration, encoding rules and operational limits.
+
+The root entry point accepts a `connections` array of `DatabaseConnection` items. Every item has a unique `id`; set `kind` to `duckdb`, `mysql`,
 `doris`, `starrocks`, `gbase`, `maxcompute`, `clickhouse`, `databricks`, `dameng`, `snowflake`,
 `sqlserver`, `oracle`, or `postgresql`, then add that driver's
 native connection fields directly on the item. Each Schema Mapping selects an item through
@@ -496,6 +517,13 @@ driver's ordinal parameter binding and are not interpolated into executable SQL.
 required: PAT and OAuth fields are mutually exclusive, and authentication is never inferred from
 the presence of credentials.
 
+To check a real connection, fill in the Databricks fields in `.env` (see `.env.example`) and run
+`npm run test:databricks`. Set `DATABRICKS_AUTH_TYPE=databricks-oauth` with
+`DATABRICKS_CLIENT_ID` and `DATABRICKS_CLIENT_SECRET`, or use `access-token` with
+`DATABRICKS_TOKEN`. The command opens a session through `DatabricksProvider`, applies `TZ` with
+`SET TIME ZONE` when present, and prints the current session time zone, catalog, and schema.
+The `.env` file is ignored by Git.
+
 ### Dameng connection
 
 Dameng uses the official `dmdb` pool and the `dameng` connection kind:
@@ -584,6 +612,13 @@ trusted model metadata, must match the active provider dialect, and cannot conta
 comments, or parameter placeholders. Property UDFs do not support the legacy `function` or
 `dependencies` fields; application-side computed values belong outside this query SDK.
 
+### Schema Mapping and data weaving
+
+One logical Schema can use multiple physical sources, conditional measure columns,
+time partitions, and same-connection feature tables. See
+[Schema Mapping and data weaving](docs/data-weaving.md) for the current design and
+links to detailed configuration guides.
+
 ### Query cache
 
 All compiled provider queries, including the internal time-watermark query, can share one
@@ -592,17 +627,6 @@ cache identity includes namespace, connection id, provider, SQL, and parameters.
 expiration belongs to each Schema mapping's `freshness` policy. See
 [Query cache and Redis](docs/query-cache.md).
 
-Schema mappings can also expose same-connection entity feature tables as lazy physical
-enrichments. A mapped feature property adds a `LEFT JOIN` only when referenced, and a point-in-time
-feature can be assigned to the containing valid-time entity row. See
-[Schema Mapping feature enrichments](docs/schema-mapping-enrichments.md).
-
-For aggregate sources, set `granularity` on mapped date or hierarchy Properties.
-Other available dimensions are inferred from their Property mappings, so there is no
-separate Schema Mapping `dimensions` field. The planner selects a source that covers
-the requested properties and physical time or hierarchy grain. See
-[Schema Mapping physical granularity](docs/schema-mapping-granularity.md).
-
 When Redis is shared with other applications, pass an application-specific key prefix in the
 execution JSON. SemanticDB reuses the connection by `cache.id`:
 

package/dist/cache/types.d.ts

@@ -4,6 +4,7 @@ export interface QueryCacheIdentity {
     readonly provider: CoreComputeProvider['kind'];
     /** Distinguishes separate databases using the same provider dialect. */
     readonly connectionId?: string;
+    readonly dataVersion?: string;
     readonly sql: string;
     readonly parameters: SqlParameters;
 }
@@ -39,6 +40,6 @@ export interface QueryCacheConfiguration {
 }
 export interface InvalidateQueryCacheSourceOptions {
     readonly cache: QueryCacheConfiguration;
-    /** Physical Schema Mapping source to invalidate. */
+    /** Source identity returned by sourceIdentity(mapping.source). */
     readonly source: string;
 }

package/dist/compiler/compile-computation.d.ts

@@ -0,0 +1,6 @@
+import type { Expression } from '../planner/index';
+import type { CoreComputeProvider } from '../physical/index';
+/** Render a scoped row-level computation. Inputs have already been resolved by Planner. */
+export declare const compileComputation: (computation: Extract<Expression, {
+    kind: "mapping-computation";
+}>, provider: CoreComputeProvider, renderInput: (expression: Expression) => string, bind: (value: unknown) => string) => string;

package/dist/compiler/compile-source.d.ts

@@ -0,0 +1,5 @@
+import type { ResolvedMappingSource } from '../schema-mappings/index';
+import type { CoreComputeProvider } from '../physical/index';
+/** The only SQL renderer for a resolved table/query row-set source. */
+export declare const compileSource: (source: unknown, provider: CoreComputeProvider) => string;
+export declare const sourceRequiresAlias: (source: ResolvedMappingSource | undefined) => boolean;

package/dist/executor/component-properties.d.ts

@@ -0,0 +1,22 @@
+import type { LogicformType } from '../logicform-types';
+import type { OperatorQueryComponent } from '../operators/index';
+import type { LogicalPlan } from '../planner/index';
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+import { type ExecutionUnit } from './components';
+export interface PreparedComponentPlan {
+    readonly logicform: LogicformType;
+    readonly plan: LogicalPlan;
+    readonly schema: ResolvedSemanticSchema;
+}
+/** Prepare metadata from the same normalized queries and hook results used for computation. */
+export declare const createComponentPropertyResolver: (options: {
+    readonly createUnits: (form: LogicformType, plan: LogicalPlan, schema: ResolvedSemanticSchema, source?: LogicformType) => readonly ExecutionUnit[] | undefined;
+    readonly prepareQuery: (component: OperatorQueryComponent) => Promise<PreparedComponentPlan>;
+    readonly replanSource: (form: LogicformType, schema: ResolvedSemanticSchema, sourceForm: LogicformType, sourcePlan: LogicalPlan) => LogicalPlan;
+    readonly resolveSchema: (form: LogicformType) => ResolvedSemanticSchema;
+    readonly prepareUnits: (units: readonly ExecutionUnit[]) => Promise<void>;
+}) => {
+    getUnits: (form: LogicformType, plan: LogicalPlan, schema: ResolvedSemanticSchema, source?: LogicformType) => readonly ExecutionUnit[] | undefined;
+    prepareQuery: (component: OperatorQueryComponent) => Promise<PreparedComponentPlan>;
+    resolvePlan: (form: LogicformType, original: LogicalPlan, schema: ResolvedSemanticSchema, source?: LogicformType) => Promise<LogicalPlan>;
+};

package/dist/executor/components.d.ts

@@ -1,14 +1,18 @@
 import type { LogicformType } from '../logicform-types';
-import type { OperatorComponentCalculation, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorRegistry } from '../operators/index';
+import type { OperatorComponentCalculation, OperatorComponentInput, OperatorComponentQuery, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorRegistry } from '../operators/index';
 import type { DataRow } from '../physical/index';
 import type { LogicalPlan } from '../planner/index';
 import type { ResolvedSemanticSchema } from '../semantic-types/index';
 import { type LocaleTranslate } from '../i18n/index';
-export type ExecutionUnit = OperatorQueryComponent | (OperatorComponentCalculation & {
+export type ExecutionUnit = (OperatorQueryComponent & {
+    readonly outputName?: string;
+}) | (OperatorComponentCalculation & {
     readonly outputName: string;
 }) | (OperatorJavaScriptCalculation & {
     readonly outputName: string;
 });
+export declare const isQueryComponent: (input: OperatorComponentInput) => input is OperatorComponentQuery;
 export declare const createExecutionUnits: (logicform: LogicformType, plan: LogicalPlan, schema: ResolvedSemanticSchema, operators: OperatorRegistry, resolveSchema: (schemaId: string) => ResolvedSemanticSchema, sourceLogicform?: LogicformType, locale?: string, t?: LocaleTranslate) => readonly ExecutionUnit[] | undefined;
 export declare const mergeComponentRows: (results: readonly (readonly DataRow[])[], groupNames: readonly string[]) => DataRow[];
-export declare const mergeExecutionResults: (results: readonly (readonly DataRow[])[], plan: LogicalPlan) => DataRow[];
+export declare const mergeCalculationRows: (results: readonly (readonly DataRow[])[], groupNames: readonly string[], calculation: OperatorJavaScriptCalculation) => DataRow[];
+export declare const mergeExecutionResults: (results: readonly (readonly DataRow[])[], plan: Pick<LogicalPlan, "groupBy" | "having" | "groupLimit" | "orderBy" | "pagination">) => DataRow[];

package/dist/executor/execute-query.d.ts

@@ -10,6 +10,7 @@ export interface PhysicalQuerySource {
     readonly connectionId?: string;
     /** Base mapping source that owns an enrichment source. */
     readonly mappingSource?: string;
+    readonly computationId?: string;
 }
 export declare const resolvePhysicalSourceMapping: (source: PhysicalQuerySource, mappings: SchemaMappingRegistry) => SchemaMappingDefinition | undefined;
 export declare const collectPlanSources: (plan: LogicalPlan) => readonly PhysicalQuerySource[];

package/dist/executor/execute.d.ts

@@ -1,4 +1,4 @@
-import type { LogicformType } from '../logicform-types';
+import { type LogicformType } from '../logicform-types';
 import type { ExecuteOptions, ExecuteResult, ExecuteSuccessResult, InternalExecuteOptions } from './types';
 export declare const executeWithProvider: (inputLogicform: LogicformType, inputOptions: InternalExecuteOptions) => Promise<ExecuteSuccessResult>;
 export declare const execute: (inputLogicform: LogicformType, inputOptions: ExecuteOptions) => Promise<ExecuteResult>;

package/dist/executor/federated-execution.d.ts

@@ -4,11 +4,12 @@ import type { OperatorRegistry } from '../operators/index';
 import type { CoreComputeProvider, DataRow } from '../physical/index';
 import type { LogicalPlan } from '../planner/index';
 import type { SchemaMappingRegistry } from '../schema-mappings/index';
-import type { SqlExecutionSourceReporter } from './execute-query';
+import type { PhysicalQuerySource, SqlExecutionSourceReporter } from './execute-query';
 import type { InternalExecuteOptions } from './types';
 export declare const coordinatorConnectionId = "__semanticdb_coordinator__";
 export interface FederatedCompiledQuery {
     readonly compiled: CompiledQuery;
+    readonly sources: readonly PhysicalQuerySource[];
     readonly connectionId: string;
     readonly provider: CoreComputeProvider;
     readonly type: 'computation' | 'total';

package/dist/executor/fetch-entities.d.ts

@@ -9,7 +9,7 @@ import type { Permissions } from '../permissions/index';
 import type { ResolvedSemanticSchema, SemanticTypeRegistry } from '../semantic-types/index';
 import type { EntityFetchRequest } from './result-hydrator/index';
 import type { SemanticDBPlugin } from '../plugins/index';
-import type { SqlExecutionSourceReporter } from './execute-query';
+import type { PhysicalQuerySource, SqlExecutionSourceReporter } from './execute-query';
 import type { LocaleRegistry } from '../i18n/index';
 interface FetchEntityOptions {
     readonly version: string;
@@ -26,7 +26,7 @@ interface FetchEntityOptions {
     readonly preferredConnectionId?: string;
     readonly cache?: QueryCacheExecutionOptions;
     readonly signal?: AbortSignal;
-    readonly onCompiled?: (compiled: CompiledQuery, logicform: LogicformType, provider: CoreComputeProvider, connectionId?: string) => SqlExecutionSourceReporter | undefined;
+    readonly onCompiled?: (compiled: CompiledQuery, logicform: LogicformType, provider: CoreComputeProvider, connectionId: string | undefined, sources: readonly PhysicalQuerySource[]) => SqlExecutionSourceReporter | undefined;
 }
 export declare const fetchEntities: (request: EntityFetchRequest, options: FetchEntityOptions) => Promise<DataRow[]>;
 export {};

package/dist/executor/index.d.ts

@@ -1,3 +1,3 @@
 export { execute } from './execute';
 export { closeConnections } from './connection-registry';
-export type { ExecuteOptions, ExecuteFailureResult, ExecuteProgressEvent, ExecuteResult, ExecuteSuccessResult, ExecutedSql, ExecutedSqlType, SqlExecutionSource, PartialExecuteResult, ProgressCallback, } from './types';
+export type { ExecuteOptions, ExecuteFailureResult, ExecuteProgressEvent, ExecuteResult, ExecuteSuccessResult, ExecutedSql, ExecutedSqlSchemaMapping, ExecutedSqlType, SqlExecutionSource, PartialExecuteResult, ProgressCallback, } from './types';

package/dist/executor/merge-by-id.d.ts

@@ -0,0 +1,3 @@
+import type { DataRow } from '../physical/index';
+/** Merge result arrays by their executor-owned `_id`; later columns override earlier ones. */
+export declare const mergeByID: (results: readonly (readonly Readonly<DataRow>[])[]) => DataRow[];

package/dist/executor/partition.d.ts

@@ -0,0 +1,18 @@
+import type { LogicformType, QueryType } from '../logicform-types';
+import type { OperatorRegistry } from '../operators/index';
+import type { CreateLogicalPlanOptions, LogicalPlan } from '../planner/index';
+import type { SchemaMappingRegistry } from '../schema-mappings/index';
+import type { LogicformPartitionShard, ResolvedSemanticSchema } from '../semantic-types/index';
+/** Intersect range filters so the grain checker sees the effective shard boundary. */
+export declare const partitionQuery: (original: QueryType | undefined, additional: QueryType) => QueryType;
+export declare const validatePartitionShards: (schema: ResolvedSemanticSchema, shards: readonly LogicformPartitionShard[], mappings: SchemaMappingRegistry) => void;
+export declare const isDetailPartition: (logicform: LogicformType) => boolean;
+export interface PartitionedPlans {
+    readonly current: LogicalPlan;
+    readonly comparison?: LogicalPlan;
+    readonly mappingIds: readonly string[];
+}
+export declare const createPartitionedPlans: (logicform: LogicformType, schema: ResolvedSemanticSchema, shards: readonly LogicformPartitionShard[], operators: OperatorRegistry, mappings: SchemaMappingRegistry, options: CreateLogicalPlanOptions, comparison?: {
+    readonly logicform: LogicformType;
+    readonly queryForCurrentShard: (query: QueryType) => QueryType;
+}) => PartitionedPlans;

package/dist/executor/random-data.d.ts

@@ -0,0 +1,5 @@
+import type { LogicformRandomDataType } from '../logicform-types';
+import type { DataRow } from '../physical/index';
+import type { LogicalPlan } from '../planner/index';
+/** Runs after all calculations/pagination and before semantic result hooks. Never mutates cached rows. */
+export declare const randomizeResultData: (rows: readonly DataRow[], plan: LogicalPlan, randomData: LogicformRandomDataType | undefined) => readonly DataRow[];

package/dist/executor/result-hydrator/entity-fetch-conditions.d.ts

@@ -0,0 +1,4 @@
+import type { LogicformType, QueryType } from '../../logicform-types';
+import type { EntityFetchRequest } from './types';
+/** ID-only display expansion uses the latest version that has already started. */
+export declare const createEntityFetchConditions: (request: EntityFetchRequest, idQuery: QueryType) => Pick<LogicformType, "query" | "sort">;

package/dist/executor/result-hydrator/index.d.ts

@@ -1,2 +1,3 @@
 export { hydrateResult } from './hydrate-result';
+export { createEntityFetchConditions } from './entity-fetch-conditions';
 export type { EntityFetchRequest, ResultHydratorOptions } from './types';

package/dist/executor/result-hydrator/types.d.ts

@@ -7,8 +7,15 @@ export interface EntityFetchRequest {
     readonly schema: ResolvedSemanticSchema;
     readonly idProperty: ResolvedSemanticProperty;
     readonly ids: readonly unknown[];
+    /** Fetch candidates ordered by descending start time; retain the first row per ID. */
+    readonly latestVersion?: {
+        readonly startProperty: string;
+        readonly asOf: string;
+    };
 }
 export interface ResultHydratorOptions {
+    readonly expandEntities?: boolean;
+    readonly now?: Date;
     readonly semanticTypes: SemanticTypeRegistry;
     readonly resolveSchema: (schemaId: string) => ResolvedSemanticSchema;
     readonly fetchEntities: (request: EntityFetchRequest) => Promise<readonly DataRow[]>;

package/dist/executor/runtime-execution.d.ts

@@ -0,0 +1,6 @@
+import type { LogicformType } from '../logicform-types';
+import type { OperatorRegistry } from '../operators/index';
+import type { ExecuteOptions, ExecuteResult, ExecuteSuccessResult } from './types';
+/** Runtime operators are handled only as top-level projections. */
+export declare const hasRuntimeProjection: (form: LogicformType, operators: OperatorRegistry) => boolean;
+export declare const executeRuntime: (input: LogicformType, options: ExecuteOptions, operators: OperatorRegistry, executeNested: (form: LogicformType, options: ExecuteOptions) => Promise<ExecuteResult>) => Promise<ExecuteSuccessResult>;

package/dist/executor/sample.d.ts

@@ -0,0 +1,6 @@
+import type { DataRow } from '../physical/index';
+import type { OrderPlan } from '../planner/index';
+export declare const sampleEntityRows: (rows: readonly DataRow[], limit: number, orderBy: readonly OrderPlan[]) => {
+    readonly rows: DataRow[];
+    readonly total: number;
+};

package/dist/executor/types.d.ts

@@ -2,7 +2,7 @@ import type { OperatorDefinition, OperatorExecutionContext, OperatorRegistry } f
 import type { CoreComputeProvider, DataRow, ProviderRegistry, SqlParameters } from '../physical/index';
 import type { DatabaseConnection } from '../physical/index';
 import type { LogicalPlan, QueryLineage } from '../planner/index';
-import type { SchemaMappingDefinition, SchemaMappingRegistry, SchemaMappingSelection } from '../schema-mappings/index';
+import type { SchemaMappingDefinition, SchemaMappingRegistry } from '../schema-mappings/index';
 import type { ResolvedSemanticSchema, SemanticSchemaDraft, SemanticTypeRegistry, TimeWatermarkPolicy } from '../semantic-types/index';
 import type { LogicformType, PublicLogicformType } from '../logicform-types';
 import type { QueryCacheConfiguration, QueryCacheExecutionOptions } from '../cache/index';
@@ -67,10 +67,16 @@ interface ExecuteBaseOptions {
     readonly locale?: string;
     /** Additional or overriding locale files used by generated names and messages. */
     readonly locales?: LocaleInput;
-    /** Table, row, and column permissions for this execution. */
+    /** Table, row, column, and custom metric permissions for this execution. */
     readonly permissions?: Permissions;
     readonly onProgress?: ProgressCallback;
     readonly signal?: AbortSignal;
+    /** Application helpers (for example axios) passed to runtime Operators. SDK helper names are reserved. */
+    readonly runtimeHelpers?: Readonly<Record<string, unknown>>;
+    /** Application configuration passed as the third argument to a runtime Operator's run hook. */
+    readonly runtimeConfig?: Readonly<Record<string, unknown>>;
+    /** Skip entity expansion in this execution; the public result envelope remains unchanged. */
+    readonly result_only?: boolean;
     /** Default time watermark policy; Schema and Property policies override it. */
     readonly timeWatermark?: TimeWatermarkPolicy;
     /** Resource limits for in-process combination of separate physical connections. */
@@ -81,9 +87,9 @@ interface ExecuteBaseOptions {
 }
 export interface ExecuteOptions extends ExecuteBaseOptions {
     /** Physical mappings supplied as JSON definitions. */
-    readonly schemaMappings: readonly SchemaMappingDefinition[];
+    readonly schemaMappings?: readonly SchemaMappingDefinition[];
     /** Database connections addressable by SchemaMappingDefinition.connectionId. */
-    readonly connections: readonly DatabaseConnection[];
+    readonly connections?: readonly DatabaseConnection[];
     /** Provider factories used for built-in or application-defined connection kinds. */
     readonly providerRegistry?: ProviderRegistry;
     /** JSON configuration for an internally owned and reused query-cache connection. */
@@ -91,6 +97,10 @@ export interface ExecuteOptions extends ExecuteBaseOptions {
 }
 /** Internal execution seam used by executor tests after a provider has been resolved. */
 export interface InternalExecuteOptions extends Omit<ExecuteBaseOptions, 'operators'> {
+    /** Schema hooks already active in an internal execution, for recursion detection. */
+    readonly partitionStack?: readonly string[];
+    /** A pinned internal execution does not repartition this Schema. */
+    readonly partitionDisabledSchemaIds?: readonly string[];
     readonly operators?: OperatorRegistry;
     /** The public execution boundary has already merged built-in, plugin, and explicit Operators. */
     readonly operatorsResolved?: boolean;
@@ -117,14 +127,6 @@ export interface ExecuteSuccessResult {
     readonly normedLogicform: PublicLogicformType;
     readonly sqls: readonly ExecutedSql[];
     readonly lineage: QueryLineage;
-    readonly provider: CoreComputeProvider['kind'];
-    /** Physical connections that contributed rows to this result. */
-    readonly providers: readonly {
-        readonly connectionId: string;
-        readonly provider: CoreComputeProvider['kind'];
-    }[];
-    /** Physical mapping decisions, including why every non-selected candidate lost. */
-    readonly schemaMappingSelections: readonly SchemaMappingSelection[];
     /** Plugin-owned materialization for a custom LogicForm output type. */
     readonly output?: unknown;
 }
@@ -135,12 +137,18 @@ export interface ExecuteFailureResult {
     readonly schema?: ResolvedSemanticSchema;
     readonly normedLogicform: PublicLogicformType;
     readonly sqls: readonly ExecutedSql[];
-    readonly provider?: CoreComputeProvider['kind'];
     readonly lineage?: QueryLineage;
 }
 export type ExecuteResult = ExecuteSuccessResult | ExecuteFailureResult;
 export type ExecutedSqlType = 'computation' | 'semantic-resolution' | 'total';
 export type SqlExecutionSource = 'cache' | 'database';
+export interface ExecutedSqlSchemaMapping {
+    readonly schemaId: string;
+    /** Schema Mapping id, or its source when no explicit id was configured. */
+    readonly mappingId: string;
+    readonly connectionId: string;
+    readonly source: string;
+}
 export interface ExecutedSql {
     /** Why this SQL participates in the LogicForm execution. */
     readonly type: ExecutedSqlType;
@@ -151,6 +159,8 @@ export interface ExecutedSql {
     readonly explain: string;
     /** Normalized LogicForm represented by this SQL statement. */
     readonly logicform: PublicLogicformType;
+    /** Physical Schema Mappings read directly by this SQL; empty for coordinator or materialized-row SQL. */
+    readonly schemaMappings: readonly ExecutedSqlSchemaMapping[];
     /** Parameterized SQL used for provider execution and cache identity. */
     readonly sql: string;
     readonly parameters: SqlParameters;

package/dist/file-import/index.d.ts

@@ -0,0 +1,2 @@
+export { readImportFile } from './read-file';
+export type { CsvEncoding, ImportFile, ReadImportFileOptions, ReadImportFileResult } from './types';

package/dist/file-import/read-file.d.ts

@@ -0,0 +1,2 @@
+import type { ReadImportFileOptions, ReadImportFileResult } from './types';
+export declare const readImportFile: (options: ReadImportFileOptions) => Promise<ReadImportFileResult>;

package/dist/file-import/types.d.ts

@@ -0,0 +1,31 @@
+import type { DataRow } from '../physical/index';
+export type CsvEncoding = 'auto' | 'utf-8' | 'gbk' | 'gb18030' | 'utf-16le' | 'utf-16be';
+export type ImportFile = {
+    readonly path: string;
+    readonly format?: 'csv' | 'xlsx';
+} | {
+    readonly data: Uint8Array;
+    readonly format: 'csv' | 'xlsx';
+};
+export interface ReadImportFileOptions {
+    readonly file: ImportFile;
+    readonly csv?: {
+        readonly encoding?: CsvEncoding;
+        readonly delimiter?: ',' | ';' | '\t' | '|';
+    };
+    readonly excel?: {
+        readonly sheet?: string;
+        readonly headerRow?: number;
+    };
+    /** Defaults to 50 MiB and 100,000 data rows. */
+    readonly maxBytes?: number;
+    readonly maxRows?: number;
+    readonly signal?: AbortSignal;
+}
+export interface ReadImportFileResult {
+    readonly format: 'csv' | 'xlsx';
+    readonly encoding?: Exclude<CsvEncoding, 'auto'>;
+    readonly sheet?: string;
+    readonly columns: readonly string[];
+    readonly rows: readonly DataRow[];
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { getLogicformPropertyReferences, isDimensionInLogicform } from './logicform/index';
+export type { LogicformPropertyReference } from './logicform/index';
 export { createLocaleRegistry, defaultLocaleRegistry, LocaleRegistry, enUS, zhCN, } from './i18n/index';
 export type { LocaleDefinition, LocaleInput, LocaleTranslate } from './i18n/index';
 export declare const Logicform: Readonly<{
@@ -8,19 +10,22 @@ export { SemanticDBError } from './errors';
 export { builtinSemanticTypes, createSemanticTypeRegistry, resolveSchema, SemanticTypeRegistry, validateResolvedSchema, } from './semantic-types/index';
 export { builtinOperators, createOperatorRegistry, OperatorRegistry, resolveOperator, } from './operators/index';
 export type { LegacySchemaPluginContext, MappingGranularityContext, MappingGranularityPlugin, OutputHandlerContext, OutputHandlerDefinition, IntervalSemanticProperties, IntervalSemanticsDefinition, PlannerPeriodDefinition, PlannerPeriodEvaluation, RelationSemanticsDefinition, RelationTemporalPlan, TimeWatermarkLogicformContext, PropertyMetadataPlugin, QueryOperatorCompileContext, QueryOperatorAuthorizeContext, QueryOperatorDefinition, QueryOperatorNormalizeContext, QueryOperatorPhysicalSource, QueryOperatorPlanContext, QueryOperatorPlanResult, SchemaMetadataPlugin, SchemaMappingPlugin, SemanticDBPlugin, } from './plugins/index';
-export { SchemaMappingRegistry, fromYiAskSchemaMapping, } from './schema-mappings/index';
-export type { AbsoluteDateValue, CompareOperator, DatePartQueryComparison, DatePartQueryOperand, DateTimeValue, DateValue, EntityIdType, ExpressionItemType, LogicformType, NumericQueryComparison, NumericQueryOperand, PublicLogicformType, PeriodShiftTime, PredItemType, QueryLogicalOperand, QueryExpressionType, RelationQueryType, QueryType, QueryValueType, QueryValueTypeWithCompareOperator, RelativeDateValue, RepresentationType, } from './logicform-types';
+export { SchemaMappingRegistry, sourceIdentity, fromYiAskSchemaMapping, getSupportedDimensions, } from './schema-mappings/index';
+export type { AbsoluteDateValue, CalendarDateQueryValue, CompareOperator, DatePartQueryComparison, DatePartQueryOperand, DateTimeValue, DateValue, EntityIdType, ExpressionItemType, LogicformType, LogicformSampleType, LogicformRandomDataOptions, LogicformRandomDataType, NumericQueryComparison, NumericQueryOperand, PublicLogicformType, PeriodShiftTime, PredItemType, QueryLogicalOperand, QueryExpressionType, RelationQueryType, QueryType, QueryValueType, QueryValueTypeWithCompareOperator, RelativeDateValue, RepresentationType, } from './logicform-types';
 export type { RecursiveQueryType } from './plugins/index';
 export type { PrimalType, PropertyHierarchyDefinition, PropertySqlDefinition, ResolvedSemanticProperty, ResolvedSemanticSchema, SemanticTypeNormalizeContext, SemanticPropertyDraft, SemanticSchemaDraft, SemanticTypeDefinition, SemanticTypeResultContext, SemanticTypeResultProperty, TimeGranularity, TimeWatermarkPolicy, } from './semantic-types/index';
 export type { DataRow, SqlParameters, BuiltinDatabaseConnection, DatabaseConnection, DatabaseConnectionBase, DatabaseConnectionExtensions, ProviderDefinition, ProviderKind, ProviderKindExtensions, } from './physical/index';
 export { DBConnector, ProviderRegistry } from './physical/index';
+export { readImportFile } from './file-import/index';
+export type { CsvEncoding, ImportFile, ReadImportFileOptions, ReadImportFileResult } from './file-import/index';
+export type { DuckDBConnectionOptions, ImportColumn, ImportRowsRequest, ImportRowsResult, ImportFileOptions, ImportFileResult } from './physical/index';
 export type { DBConnectorOptions, RunSQLOptions, GetTableListOptions, DescribeTableOptions, DescribeTableRequest, DatabaseColumn, TableDescription, DatabaseTable, SQLResult, TableListRequest, } from './physical/index';
-export type { OperatorDefinition, OperatorDefaultNameContext, OperatorExecutionContext, OperatorComponentContext, OperatorComponentCalculation, OperatorComponentQuery, OperatorExecutionComponent, OperatorPlanInputContext, OperatorPlannedInput, OperatorGroupKeyShift, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorEvaluateContext, OperatorOutputPropertyContext, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, ResultPropertyTemporalMetadataExtensions, } from './operators/index';
-export type { SchemaMappingDefinition, SchemaMappingEnrichmentDefinition, SchemaMappingEnrichmentKey, SchemaMappingItem, SchemaMappingGranularity, SchemaMappingGranularityExtensions, SchemaMappingPointTemporalDefinition, SchemaMappingPredDefinition, SchemaMappingPredMatch, SchemaMappingSelection, RejectedSchemaMapping, SourceFreshnessPolicy, YiAskSchemaMappingItem, YiAskSchemaMappingRecord, } from './schema-mappings/index';
+export type { OperatorDefinition, OperatorDefaultNameContext, OperatorFormulaTextContext, OperatorExecutionContext, ResolvedTimeRange, OperatorComponentContext, OperatorComponentCalculation, OperatorComponentQuery, OperatorComponentLiteral, OperatorComponentInput, OperatorExecutionComponent, OperatorPlanInputContext, OperatorPlannedInput, OperatorGroupKeyShift, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorOutputPropertyContext, OperatorRuntimeHelpers, OperatorRuntimeConfig, OperatorRuntimeExecute, OperatorRuntimeRun, OperatorRuntimeValue, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, ResultPropertyTemporalMetadataExtensions, } from './operators/index';
+export type { SchemaMappingDefinition, SchemaMappingSource, ResolvedMappingSource, PropertyMappingCalculation, PropertyMappingValue, PropertyMapping, PredItemMapping, IgnoredMapping, ComputationExpression, ComputationInput, SchemaMappingEnrichmentDefinition, SchemaMappingEnrichmentKey, SchemaMappingItem, QueryPathBinding, QueryPathMappingDefinition, SchemaMappingGranularity, SchemaMappingGranularityExtensions, SchemaMappingPointTemporalDefinition, SchemaMappingPredDefinition, SchemaMappingPredMatch, SchemaMappingSelection, RejectedSchemaMapping, SourceFreshnessPolicy, YiAskSchemaMappingItem, YiAskSchemaMappingRecord, } from './schema-mappings/index';
 export { QueryCacheManager } from './cache/index';
 export type { InvalidateQueryCacheSourceOptions, QueryCacheConfiguration, } from './cache/index';
-export type { ExecuteOptions, ExecuteFailureResult, ExecuteProgressEvent, ExecuteResult, ExecuteSuccessResult, ExecutedSql, ExecutedSqlType, SqlExecutionSource, PartialExecuteResult, ProgressCallback, } from './executor/index';
-export type { ColumnPermissions, Permissions, SchemaPermissions, } from './permissions/index';
+export type { ExecuteOptions, ExecuteFailureResult, ExecuteProgressEvent, ExecuteResult, ExecuteSuccessResult, ExecutedSql, ExecutedSqlSchemaMapping, ExecutedSqlType, SqlExecutionSource, PartialExecuteResult, ProgressCallback, } from './executor/index';
+export type { ColumnPermissions, MetricPermissions, Permissions, SchemaPermissions, } from './permissions/index';
 export type { CreateLogicalPlanOptions, LogicalPlan, QueryLineage, } from './planner/index';
 export { PlannerSemanticRegistry, createPlannerSemanticRegistry, } from './planner/index';
 export type { PlannerSemanticResolution, PlannerSemanticQueryContext, PlannerSemanticRule, PlannerSemanticRuleContext, } from './planner/index';

package/dist/logicform/dimensions.d.ts

@@ -0,0 +1,16 @@
+import type { LogicformType } from '../logicform-types';
+export interface LogicformPropertyReference {
+    readonly reference: string;
+    readonly use: 'query' | 'pred' | 'groupby';
+}
+/** Property references in this v2 LogicForm node, retaining their use site. */
+export declare const getLogicformPropertyReferences: (logicform: LogicformType) => readonly LogicformPropertyReference[];
+/**
+ * Whether this v2 LogicForm node uses an exact property path in its query,
+ * PredItems, or groupby. A related-property filter such as
+ * `产品: { schema: 'product', query: { 品类: 'PA' } }` uses `产品_品类`,
+ * not the `产品` entity itself. A `from` or full query subquery has its own
+ * field scope and is not traversed. Normalize first when comparing property
+ * names with IDs or aliases.
+ */
+export declare const isDimensionInLogicform: (logicform: LogicformType, dimension: string) => boolean;

package/dist/logicform/index.d.ts

@@ -0,0 +1,2 @@
+export { getLogicformPropertyReferences, isDimensionInLogicform } from './dimensions';
+export type { LogicformPropertyReference } from './dimensions';

package/dist/logicform-types.d.ts

@@ -3,7 +3,7 @@ export type RepresentationType = 'value' | 'table' | 'pie' | 'bar' | 'column' |
 /** A concrete timestamp accepted by a LogicForm query. */
 export type DateTimeValue = `${number}-${number}-${number} ${number}:${number}:${number}`;
 /** A relative period resolved from the execution clock. */
-export interface RelativeDateValue {
+export interface RelativeDateValue extends AbsoluteDateValue {
     readonly granularity: TimeGranularity;
     readonly offset: number;
 }
@@ -22,7 +22,14 @@ export interface AbsoluteDateValue {
 /** Period reference used by operators such as `$periodShift`. */
 export type PeriodShiftTime = RelativeDateValue | AbsoluteDateValue;
 /** A date value before semantic-type normalization. */
-export type DateValue = string | RelativeDateValue | AbsoluteDateValue;
+export type DateValue = string | RelativeDateValue | AbsoluteDateValue | CalendarDateQueryValue;
+/** Calendar selections; comparison components and finer parts become date-part filters. */
+export type CalendarDateQueryValue = {
+    readonly [Part in Exclude<keyof AbsoluteDateValue, 'period'>]?: DatePartQueryOperand;
+} & {
+    readonly granularity?: TimeGranularity;
+    readonly offset?: number;
+};
 /** Stable entity identity. Numeric IDs must be safe integers. */
 export type EntityIdType = string | number;
 export type CompareOperator = '$eq' | '$gt' | '$gte' | '$lt' | '$lte' | '$ne' | '$in' | '$nin' | '$exists' | '$regex' | '$contains' | '$startsWith' | '$length' | '$and' | '$or' | '$second' | '$minute' | '$hour' | '$weekday' | '$day' | '$week' | '$month' | '$quarter' | '$year' | Extract<keyof QueryOperatorExtensions, string>;
@@ -118,6 +125,16 @@ export interface LogicformOutputType {
     type: LogicformOutputTypeValue;
     filename?: string;
 }
+/** Enable uniform sampling of distinct entity rows; top-level limit controls the count. */
+export type LogicformSampleType = boolean;
+/** Presentation-only numeric perturbation; each output cell gets an independent multiplier. */
+export interface LogicformRandomDataOptions {
+    /** Minimum multiplier (inclusive). Defaults to 0.1. */
+    readonly minFactor?: number;
+    /** Maximum multiplier (exclusive unless equal to minFactor). Defaults to 1.5. */
+    readonly maxFactor?: number;
+}
+export type LogicformRandomDataType = boolean | LogicformRandomDataOptions;
 export interface LogicformType {
     /** LogicForm protocol version. This SDK supports version 2.0 and later. */
     version: string;
@@ -129,6 +146,9 @@ export interface LogicformType {
     propertyResolve?: Readonly<Record<string, Readonly<Record<string, string>>>>;
     groupby?: PredItemType[];
     sort?: Record<string, 1 | -1>;
+    sample?: LogicformSampleType;
+    /** Perturb final scalar numeric values, excluding grouping keys and identities. Top-level only. */
+    randomData?: LogicformRandomDataType;
     having?: QueryType;
     output?: LogicformOutputType;
     limit?: number;

package/dist/normalizer/core.d.ts

@@ -3,7 +3,14 @@ import type { OperatorRegistry } from '../operators/index';
 import type { ResolvedSemanticProperty, ResolvedSemanticSchema, SemanticTypeRegistry } from '../semantic-types/index';
 import type { SemanticDBPlugin } from '../plugins/index';
 import type { LocaleInput, LocaleRegistry } from '../i18n/index';
+import type { ResolvedTimeRange } from '../operators/index';
 export interface NormalizeLogicformOptions {
+    /** Reports only this call's main query, never nested or metric queries. */
+    readonly onTimeRangeResolved?: (range: ResolvedTimeRange | undefined) => void;
+    /** Internal recursion guard: sampling is a top-level result operation. */
+    readonly allowSample?: boolean;
+    /** Internal recursion guard: numeric perturbation applies only to the final result. */
+    readonly allowRandomData?: boolean;
     readonly semanticTypes: SemanticTypeRegistry;
     readonly operators?: OperatorRegistry;
     readonly plugins?: readonly SemanticDBPlugin[];
@@ -25,7 +32,7 @@ export interface NormalizeLogicformOptions {
     }>;
     /** Internal root query used to resolve automatic `$case` boundaries. */
     readonly autoCaseQuery?: LogicformType['query'];
-    readonly resolveFromSchema?: (normalizedFrom: LogicformType, outerSchema: ResolvedSemanticSchema) => ResolvedSemanticSchema;
+    readonly resolveFromSchema?: (normalizedFrom: LogicformType, outerSchema: ResolvedSemanticSchema) => ResolvedSemanticSchema | Promise<ResolvedSemanticSchema>;
     readonly canProjectProperty?: (schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty) => boolean;
     /** Internal recursion hook installed by normalizeLogicform. */
     readonly normalizeNestedLogicform?: (logicform: LogicformType) => Promise<LogicformType>;

package/dist/normalizer/index.d.ts

@@ -2,3 +2,4 @@ export { normalizeLogicform } from './normalize-logicform';
 export { defaultPredName } from './default-pred-name';
 export { assertSupportedLogicformVersion } from './version';
 export { inferPropertyResolvePath } from './property-resolve';
+export { expandPublicLogicform } from './public-logicform';

package/dist/normalizer/main-time-range.d.ts

@@ -0,0 +1,9 @@
+import type { ResolvedTimeRange } from '../operators/index';
+import type { ResolvedSemanticProperty, ResolvedSemanticSchema, SemanticTypeNormalizeContext } from '../semantic-types/index';
+/** Collect only the root query; metric, relation and nested LF queries never enter here. */
+export declare class MainTimeRangeCollector {
+    #private;
+    invalidate(): void;
+    observe(schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty, queryPath: readonly (string | number)[], customNormalization: boolean): SemanticTypeNormalizeContext['onDateQueryNormalized'];
+    get result(): ResolvedTimeRange | undefined;
+}