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

package/dist/physical/provider.d.ts

@@ -1,3 +1,4 @@
+import type { ImportRowsRequest, ImportRowsResult } from './import-types';
 export type DataRow = Record<string, unknown>;
 export type SqlParameters = readonly unknown[];
 export type DatePart = 'second' | 'minute' | 'hour' | 'weekday' | 'day' | 'week' | 'month' | 'quarter' | 'year';
@@ -100,5 +101,8 @@ export interface CoreComputeProvider extends SqlRenderCapabilities {
     /** Optional physical metadata capability, independent of semantic Schemas. */
     getTableList?(request: TableListRequest): Promise<DatabaseTable[]>;
     describeTable?(request: DescribeTableRequest): Promise<TableDescription>;
+    importRows?(request: ImportRowsRequest): Promise<ImportRowsResult>;
+    /** Published dataset revision, used to isolate cached queries across imports. */
+    getDataVersion?(): Promise<string | undefined>;
     close(): Promise<void>;
 }

package/dist/planner/build-lineage.d.ts

@@ -2,4 +2,4 @@ import type { OperatorRegistry } from '../operators/index';
 import type { CoreComputeProvider } from '../physical/index';
 import type { ResolvedSemanticSchema } from '../semantic-types/index';
 import type { LogicalPlan, QueryLineage } from './types';
-export declare const buildLineage: (plan: LogicalPlan, schema: ResolvedSemanticSchema, provider: CoreComputeProvider, operators?: OperatorRegistry, providerForConnection?: (connectionId: string) => CoreComputeProvider) => QueryLineage;
+export declare const buildLineage: (plan: LogicalPlan, schema: ResolvedSemanticSchema, provider: CoreComputeProvider, operators?: OperatorRegistry, providerForConnection?: (connectionId: string) => CoreComputeProvider, resolveSchema?: (schemaId: string) => ResolvedSemanticSchema) => QueryLineage;

package/dist/planner/create-logical-plan.d.ts

@@ -1,15 +1,28 @@
-import type { LogicformType } from '../logicform-types';
+import type { LogicformType, PredItemType } from '../logicform-types';
 import type { OperatorRegistry } from '../operators/index';
 import { SchemaMappingRegistry } from '../schema-mappings/index';
 import type { SchemaMappingSelection } from '../schema-mappings/index';
 import type { SemanticDBPlugin } from '../plugins/index';
-import type { ResolvedSemanticSchema } from '../semantic-types/index';
+import type { ResolvedSemanticSchema, SemanticTypeRegistry } from '../semantic-types/index';
 import type { ResolvedSemanticProperty } from '../semantic-types/index';
+import type { ResultProperty } from '../operators/index';
 import { type PlannerSemanticRegistry } from './semantics/index';
 import type { LogicalPlan } from './types';
+export declare const createResultProperty: (property: ResultProperty) => ResolvedSemanticProperty;
 export declare const createResultSchema: (plan: LogicalPlan, sourceSchema: ResolvedSemanticSchema) => ResolvedSemanticSchema;
 export declare const createDerivedSourceSchema: (sourcePlan: LogicalPlan, outerSchema: ResolvedSemanticSchema) => ResolvedSemanticSchema;
 export interface CreateLogicalPlanOptions {
+    /** Executor authorization for each form, including forms introduced by operator rewrites. */
+    readonly authorizeLogicform?: (logicform: LogicformType) => void;
+    readonly semanticTypes?: SemanticTypeRegistry;
+    /** Authorize logical inputs introduced by Mapping computations. */
+    readonly authorizeComputationInput?: (schema: ResolvedSemanticSchema, reference: string) => void;
+    /** Original semantic projections for this generated query only, aligned with its preds. */
+    readonly semanticPreds?: readonly PredItemType[];
+    /** Normalized nested LogicForms whose asynchronous partition plans were prepared by the executor. */
+    readonly preplannedPartitions?: ReadonlyMap<string, LogicalPlan>;
+    /** Restrict the root physical Schema to one candidate during partition planning. */
+    readonly mappingCandidates?: readonly string[];
     readonly plugins?: readonly SemanticDBPlugin[];
     readonly resolveSchema?: (schemaId: string) => ResolvedSemanticSchema;
     /** Prefer physical mappings colocated with the execution's main connection. */

package/dist/planner/index.d.ts

@@ -1,9 +1,10 @@
 export { buildLineage } from './build-lineage';
-export { createDerivedSourceSchema, createLogicalPlan, createResultSchema } from './create-logical-plan';
+export { createDerivedSourceSchema, createLogicalPlan, createResultProperty, createResultSchema } from './create-logical-plan';
 export type { CreateLogicalPlanOptions } from './create-logical-plan';
-export type { Expression, ArrayExpansionPlan, EnrichmentJoinPlan, FieldReferencePlan, GroupLimitPlan, JoinPlan, LogicalQuerySubquery, LogicalQueryOperator, LogicalOrdinalQuery, LogicalExpressionQuery, LineageColumnSource, LineageOutput, LogicalPlan, OrderPlan, PaginationPlan, ProjectionPlan, QueryLineage, RowIdentityPlan, PeriodSourcePlan, TemporalJoinConditionPlan, } from './types';
+export type { Expression, ArrayExpansionPlan, EnrichmentJoinPlan, FieldReferencePlan, GroupLimitPlan, JoinPlan, LogicalQuerySubquery, LogicalOutputReference, LogicalQueryOperator, LogicalOrdinalQuery, LogicalExpressionQuery, LineageColumnSource, LineageOutput, LogicalPlan, OrderPlan, PaginationPlan, PhysicalQueryFilterPlan, ProjectionPlan, QueryLineage, RowIdentityPlan, PeriodSourcePlan, TemporalJoinConditionPlan, } from './types';
 export { isLogicalQuerySubquery, isLogicalQueryOperator } from './types';
 export { isLogicalOrdinalQuery } from './types';
 export { isLogicalExpressionQuery } from './types';
+export { isLogicalOutputReference } from './types';
 export * from './semantics/index';
 export { createPlannerSemanticRegistry } from './semantics/registry-defaults';

package/dist/planner/mapping-granularity.d.ts

@@ -3,5 +3,5 @@ import type { SemanticDBPlugin } from '../plugins/index';
 import { type OperatorRegistry } from '../operators/index';
 import { type SchemaMappingDefinition } from '../schema-mappings/index';
 import type { ResolvedSemanticSchema } from '../semantic-types/index';
-/** Checks grouped-source Property coverage and delegates plugin-owned physical grains. */
+/** Checks physical-grain Property coverage and delegates plugin-owned grains. */
 export declare const mappingGranularityReason: (logicform: LogicformType, schema: ResolvedSemanticSchema, mapping: SchemaMappingDefinition, resolveSchema?: (schemaId: string) => ResolvedSemanticSchema, plugins?: readonly SemanticDBPlugin[], operators?: OperatorRegistry) => string | undefined;

package/dist/planner/materialize-computations.d.ts

@@ -0,0 +1,3 @@
+import type { LogicalPlan } from './types';
+/** Isolate row computations from aggregate/query scopes, without SQL-text pruning. */
+export declare const materializeComputations: (plan: LogicalPlan) => LogicalPlan;

package/dist/planner/select-schema-mapping.d.ts

@@ -1,25 +1,40 @@
 import type { LogicformType } from '../logicform-types';
 import type { SemanticDBPlugin } from '../plugins/index';
-import type { SchemaMappingDefinition, SchemaMappingRegistry, SchemaMappingSelection } from '../schema-mappings/index';
+import type { SchemaMappingDefinition, PropertyMappingCalculation, SchemaMappingRegistry, SchemaMappingSelection } from '../schema-mappings/index';
 import type { ResolvedSemanticSchema } from '../semantic-types/index';
 import { type OperatorRegistry } from '../operators/index';
+import type { PhysicalQueryFilterPlan } from './types';
 export interface PredMappingRewrite {
     readonly predIndex: number;
     readonly column: string;
 }
+export interface GroupPathBinding {
+    readonly canonicalId: string;
+    readonly sourceColumn: string;
+    readonly targetSchemaId: string;
+}
 export interface SelectedSchemaMapping {
     readonly mapping: SchemaMappingDefinition;
     readonly logicform: LogicformType;
     readonly predRewrites: readonly PredMappingRewrite[];
+    readonly physicalQueryFilters: readonly PhysicalQueryFilterPlan[];
+    readonly groupPathBindings: readonly GroupPathBinding[];
     readonly selection: SchemaMappingSelection;
 }
 export interface MappedPropertySource {
     readonly column: string;
     readonly sourceRef?: string;
+    readonly calculation?: PropertyMappingCalculation;
+    readonly propertyId?: string;
 }
 export declare const mappedPropertyColumn: (mapping: SchemaMappingDefinition, schema: ResolvedSemanticSchema, reference: string) => string | undefined;
 export declare const mappedPropertySource: (mapping: SchemaMappingDefinition, schema: ResolvedSemanticSchema, reference: string) => MappedPropertySource | undefined;
+/** A physical column for the complete logical path, without traversing its relations. */
+export declare const mappedPropertyPathSource: (mapping: SchemaMappingDefinition, schema: ResolvedSemanticSchema, reference: string, resolveSchema?: (schemaId: string) => ResolvedSemanticSchema) => MappedPropertySource | undefined;
+/** A related entity's mapped ID column is also the root relation's value. */
+export declare const mappedRelationIdSource: (mapping: SchemaMappingDefinition, schema: ResolvedSemanticSchema, reference: string, resolveSchema?: (schemaId: string) => ResolvedSemanticSchema) => MappedPropertySource | undefined;
 export declare const selectSchemaMapping: (logicform: LogicformType, schema: ResolvedSemanticSchema, mappings: SchemaMappingRegistry, options?: {
+    readonly mappingCandidates?: readonly string[];
     readonly preferredConnectionId?: string;
     readonly resolveSchema?: (schemaId: string) => ResolvedSemanticSchema;
     /** Extra plugins used by this execution; must also be supplied when registering plugin grains. */

package/dist/planner/types.d.ts

@@ -1,3 +1,4 @@
+import type { ResolvedMappingSource, PropertyMappingCalculation } from '../schema-mappings/index';
 import type { CoreComputeProvider } from '../physical/index';
 import type { LogicformType } from '../logicform-types';
 import type { ResultProperty } from '../operators/index';
@@ -11,6 +12,8 @@ export interface FieldReferencePlan {
     readonly column: string;
     readonly qualifier: string;
     readonly sql?: string;
+    /** Planned row-level value; inlined for single-use filters, otherwise materialized. */
+    readonly computation?: Expression;
     readonly timestampColumn?: string;
     /** Source alias that supplies $TS when it differs from the Property's Schema. */
     readonly timestampQualifier?: string;
@@ -19,10 +22,21 @@ export interface FieldReferencePlan {
     readonly normalizeStringArray?: boolean;
     readonly comparable?: ComparableCategoryDefinition;
 }
+/** Filter against a column of the selected physical source. */
+export interface PhysicalQueryFilterPlan {
+    readonly sourceColumn: string;
+    readonly value: string | number | boolean | LogicformType | LogicalQuerySubquery;
+}
 export interface LogicalQuerySubquery {
     readonly kind: 'logicform-subquery';
     readonly plan: LogicalPlan;
 }
+/** Reference to another projected output in a HAVING comparison. */
+export interface LogicalOutputReference {
+    readonly kind: 'output-reference';
+    readonly name: string;
+}
+export declare const isLogicalOutputReference: (value: unknown) => value is LogicalOutputReference;
 export interface LogicalQueryOperator {
     readonly kind: 'query-operator';
     readonly operator: string;
@@ -51,6 +65,13 @@ export declare const isLogicalQueryOperator: (value: unknown) => value is Logica
 export declare const isLogicalOrdinalQuery: (value: unknown) => value is LogicalOrdinalQuery;
 export declare const isLogicalExpressionQuery: (value: unknown) => value is LogicalExpressionQuery;
 export type Expression = {
+    readonly kind: 'mapping-computation';
+    readonly definition: PropertyMappingCalculation & {
+        readonly id: string;
+    };
+    readonly inputs: Readonly<Record<string, Expression>>;
+    readonly alias: string;
+} | {
     readonly kind: 'array-element';
     readonly schemaId: string;
     readonly property: string;
@@ -126,10 +147,13 @@ export interface JoinPlan {
     readonly targetSchemaId: string;
     /** Physical connection selected for the target Schema mapping. */
     readonly targetConnectionId?: string;
-    readonly targetSource: string;
-    readonly targetSourceSql?: string;
+    readonly targetSource: ResolvedMappingSource;
+    /** Two projection layers for the target Schema Mapping and its UDFs. */
+    readonly targetMappingSourcePlan?: LogicalPlan;
     readonly targetAlias: string;
     readonly targetColumn: string;
+    readonly sourceExpression?: Expression;
+    readonly targetExpression?: Expression;
     readonly targetSql?: string;
     readonly targetTimestampColumn?: string;
     readonly temporalCondition?: TemporalJoinConditionPlan;
@@ -152,8 +176,7 @@ export type TemporalJoinConditionPlan = {
 export interface EnrichmentJoinPlan {
     readonly kind: 'enrichment-left';
     readonly id: string;
-    readonly source: string;
-    readonly sourceSql?: string;
+    readonly source: ResolvedMappingSource;
     readonly alias: string;
     readonly baseAlias: string;
     readonly keys: readonly {
@@ -221,15 +244,34 @@ export type RowIdentityPlan = {
 };
 export interface LogicalPlan {
     readonly schemaId: string;
-    readonly source: string;
+    readonly source: ResolvedMappingSource | undefined;
     /** Physical connection selected for this plan's source mapping. */
     readonly connectionId?: string;
-    /** Trusted derived-table SQL supplied by the selected physical mapping. */
-    readonly sourceSql?: string;
+    /** Two projection layers for the physical Mapping and Schema UDFs. */
+    readonly mappingSourcePlan?: LogicalPlan;
     /** Physical mapping selected by the Planner for this logical Schema. */
     readonly mappingId?: string;
+    /** Only computation sources actually required by this plan. */
+    readonly computationSources?: readonly {
+        readonly id: string;
+        readonly alias: string;
+        readonly source: string;
+        readonly schemaId: string;
+        readonly mappingSource: string;
+        readonly connectionId: string;
+    }[];
     /** Child relations combined by their compatible group identity. */
     readonly subplans?: readonly LogicalPlan[];
+    /** Vertically combine disjoint aggregate shards by summing matching output groups. */
+    readonly sumPartition?: true;
+    /** Vertically combine disjoint physical detail rows. */
+    readonly rowPartition?: true;
+    /** Enumerated group values corresponding to subplans, combined vertically. */
+    readonly splitGroup?: {
+        readonly name: string;
+        readonly values: readonly string[];
+        readonly groupNames: readonly string[];
+    };
     /** Optional query plan compiled as the derived-table source of this plan. */
     readonly sourcePlan?: LogicalPlan;
     /** Normalized LogicForm corresponding to sourcePlan when generated rewrites need execution. */
@@ -247,6 +289,7 @@ export interface LogicalPlan {
     readonly columnProperties?: readonly ResultProperty[];
     readonly groupBy: readonly ProjectionPlan[];
     readonly query?: Readonly<Record<string, unknown>>;
+    readonly physicalQueryFilters?: readonly PhysicalQueryFilterPlan[];
     readonly having?: Readonly<Record<string, unknown>>;
     readonly orderBy: readonly OrderPlan[];
     readonly pagination?: PaginationPlan;
@@ -270,11 +313,11 @@ export interface QueryLineage {
         readonly schemaId: string;
         readonly schemaName: string;
         readonly physicalTable: string;
-        readonly provider: CoreComputeProvider['kind'];
+        readonly provider: CoreComputeProvider['kind'] | 'runtime';
         readonly connectionId?: string;
         readonly connections?: readonly {
             readonly connectionId: string;
-            readonly provider: CoreComputeProvider['kind'];
+            readonly provider: CoreComputeProvider['kind'] | 'runtime';
         }[];
     };
     readonly outputs: readonly LineageOutput[];

package/dist/planner/udf-inputs.d.ts

@@ -0,0 +1,6 @@
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+/** Give Schema UDFs explicit logical inputs while preserving quoted string contents. */
+export declare const bindUdfInputs: (sql: string, schema: ResolvedSemanticSchema) => {
+    sql: string;
+    references: Readonly<Record<string, string>>;
+};

package/dist/plugins/types.d.ts

@@ -3,7 +3,7 @@ import type { LocaleDefinition } from '../i18n/types';
 import type { PlannerSemanticRule } from '../planner/semantics/registry';
 import type { CoreComputeProvider, DataRow } from '../physical/provider';
 import type { LogicformType, PredItemType, QueryType } from '../logicform-types';
-import type { SchemaMappingDefinition, SchemaMappingItem } from '../schema-mappings/types';
+import type { SchemaMappingDefinition, SchemaMappingItem, SchemaMappingSource, ResolvedMappingSource } from '../schema-mappings/index';
 import type { ResolvedSemanticProperty, ResolvedSemanticSchema, SemanticSchemaDraft, SemanticTypeDefinition, TimeWatermarkPolicy } from '../semantic-types/types';
 export interface SchemaMetadataPlugin {
     readonly keys: readonly string[];
@@ -47,6 +47,8 @@ export interface QueryOperatorPlanContext {
     readonly schema: ResolvedSemanticSchema;
     readonly property: ResolvedSemanticProperty;
     readonly connectionId: string;
+    /** Resolve public source configuration for planning, rendering and dependency tracking. */
+    readonly resolveSource: (source: SchemaMappingSource) => ResolvedMappingSource;
     readonly resolveSchema?: (schemaId: string) => ResolvedSemanticSchema;
     readonly resolveMapping: (schemaId: string, preferredConnectionId?: string) => SchemaMappingDefinition;
 }
@@ -54,7 +56,7 @@ export interface QueryOperatorCompileContext {
     readonly field: string;
     readonly provider: CoreComputeProvider;
     readonly bind: (value: unknown) => string;
-    readonly renderSource: (source: string, sourceSql?: string) => string;
+    readonly renderSource: (source: unknown) => string;
 }
 export interface QueryOperatorAuthorizeContext {
     readonly schema: ResolvedSemanticSchema;

package/dist/schema/index.d.ts

@@ -1,4 +1,5 @@
 export { buildFieldMap, getProperty, getSchema, } from './schema-registry';
+export { isReverseRelation, resolvePropertyValuePath, resolveRelationKeys } from './relation-keys';
 export { resolvePropertyPath } from './resolve-property-path';
 export { isDependentProjection } from './dependent-projection';
 export { isConcreteEntityId, resolveEntityFilterProperty, resolveEntityIdProperty, } from './entity-identity';

package/dist/schema/relation-keys.d.ts

@@ -0,0 +1,11 @@
+import type { ResolvedSemanticProperty } from '../semantic-types/index';
+import type { ResolvedPropertyPath, ResolvedRelationSegment, ResolvedSchemaLookup } from './resolve-property-path';
+/** Virtual scalar one-to-one objects are supplied by the metadata owner. */
+export declare const isReverseRelation: (property: ResolvedSemanticProperty) => boolean;
+/** Join keys are semantic properties; physical mappings are applied by the planner. */
+export declare const resolveRelationKeys: (relation: ResolvedRelationSegment) => {
+    readonly source: ResolvedSemanticProperty;
+    readonly target: ResolvedSemanticProperty;
+};
+/** A reverse entity's value is the related row's ID, never the local entity ID. */
+export declare const resolvePropertyValuePath: (path: ResolvedPropertyPath, lookup?: ResolvedSchemaLookup) => ResolvedPropertyPath;

package/dist/schema-mappings/computations.d.ts

@@ -0,0 +1,3 @@
+import type { SchemaMappingDefinition, PropertyMappingCalculation } from './types';
+export declare const computationInputNames: (definition: PropertyMappingCalculation) => readonly string[];
+export declare const validateMappingValues: (mapping: SchemaMappingDefinition) => void;

package/dist/schema-mappings/index.d.ts

@@ -1,7 +1,11 @@
 export { SchemaMappingRegistry } from './registry';
+export { getSupportedDimensions } from './supported-dimensions';
 export { parseDailyExpireAt } from './freshness';
 export { isMappingTimeGranularity, isSchemaMappingGranularity, } from './granularity';
-export type { SchemaMappingDefinition, SchemaMappingEnrichmentDefinition, SchemaMappingEnrichmentKey, SchemaMappingItem, SchemaMappingGranularity, SchemaMappingGranularityExtensions, SchemaMappingPointTemporalDefinition, SchemaMappingSelection, RejectedSchemaMapping, SourceFreshnessPolicy, } from './types';
+export type { SchemaMappingDefinition, SchemaMappingSource, ResolvedMappingSource, PropertyMappingCalculation, PropertyMappingValue, PropertyMapping, PredItemMapping, IgnoredMapping, ComputationExpression, ComputationInput, SchemaMappingEnrichmentDefinition, SchemaMappingEnrichmentKey, SchemaMappingItem, QueryPathBinding, QueryPathMappingDefinition, SchemaMappingGranularity, SchemaMappingGranularityExtensions, SchemaMappingPointTemporalDefinition, SchemaMappingSelection, RejectedSchemaMapping, SourceFreshnessPolicy, } from './types';
 export type { SchemaMappingPredDefinition, SchemaMappingPredMatch, } from './types';
 export { fromYiAskSchemaMapping } from './yiask';
 export type { YiAskSchemaMappingItem, YiAskSchemaMappingRecord } from './yiask';
+export { computationInputNames } from './computations';
+export { sqlValueParts } from './sql-inputs';
+export { sourceIdentity, sqlIdentity, resolveMappingSource, schemaMappingIdentity, isResolvedMappingSource } from './source';

package/dist/schema-mappings/registry.d.ts

@@ -7,6 +7,7 @@ export declare class SchemaMappingRegistry {
     register(definition: SchemaMappingDefinition): this;
     get(schemaId: string, connectionId?: string): SchemaMappingDefinition;
     list(schemaId: string): readonly SchemaMappingDefinition[];
+    findById(schemaId: string, mappingId: string): SchemaMappingDefinition | undefined;
     definitions(): readonly SchemaMappingDefinition[];
     findSource(schemaId: string, source: string, connectionId?: string): SchemaMappingDefinition | undefined;
 }

package/dist/schema-mappings/source.d.ts

@@ -0,0 +1,11 @@
+import type { ResolvedMappingSource, SchemaMappingDefinition, SchemaMappingSource } from './types';
+/** Opaque SQL contents share an identity scheme without parsing their semantics. */
+export declare const sqlIdentity: (sql: string) => string;
+/** SQL source identity follows its contents rather than a fictitious table name. */
+export declare const resolveMappingSource: (source: SchemaMappingSource) => ResolvedMappingSource;
+export declare const sourceIdentity: (source: SchemaMappingSource) => string;
+export declare const schemaMappingIdentity: (mapping: SchemaMappingDefinition) => string;
+/** Check opaque plugin payloads without reinterpreting public source configuration. */
+export declare const isResolvedMappingSource: (value: unknown) => value is ResolvedMappingSource;
+export declare const validateMappingSource: (source: unknown) => void;
+export declare const rejectObsoleteSourceFields: (container: object) => void;

package/dist/schema-mappings/sql-inputs.d.ts

@@ -0,0 +1,7 @@
+export type SqlValuePart = string | {
+    readonly input: string;
+};
+/** Preserve trusted SQL verbatim, resolving only {{input}} outside literals, identifiers and comments.
+ * SQL syntax, scalar cardinality and allowed operations are the database's responsibility.
+ */
+export declare const sqlValueParts: (sql: string) => readonly SqlValuePart[];

package/dist/schema-mappings/supported-dimensions.d.ts

@@ -0,0 +1,10 @@
+import type { SchemaTypeDraft } from 'semanticdb-core';
+import type { SemanticSchemaDraft } from '../semantic-types/index';
+import type { SchemaMappingRegistry } from './registry';
+/**
+ * Dimensions declared by at least one physical Mapping for this Schema.
+ * Returns canonical property-name paths. This is a discoverability union:
+ * metric coverage, time grain, and combinations of dimensions still require
+ * planning a concrete LogicForm.
+ */
+export declare const getSupportedDimensions: (schemaId: string, schemas: Readonly<Record<string, SemanticSchemaDraft | SchemaTypeDraft>>, schemaMappings: SchemaMappingRegistry) => readonly string[];

package/dist/schema-mappings/types.d.ts

@@ -1,5 +1,23 @@
 import type { PredItemType, QueryType } from '../logicform-types';
 import type { TimeGranularity } from '../semantic-types/index';
+/** A table or a trusted SQL query supplying a complete row set. */
+export type SchemaMappingSource = {
+    readonly kind: 'table';
+    readonly table: string;
+} | {
+    readonly kind: 'sql';
+    readonly sql: string;
+};
+/** Validated row-set source passed unchanged through planning and compilation. */
+export type ResolvedMappingSource = {
+    readonly kind: 'table';
+    readonly identity: string;
+    readonly path: readonly string[];
+} | {
+    readonly kind: 'sql';
+    readonly identity: string;
+    readonly sql: string;
+};
 /** Plugin-owned physical grains extend this interface through module augmentation. */
 export interface SchemaMappingGranularityExtensions {
 }
@@ -15,10 +33,59 @@ export type SourceFreshnessPolicy = {
 } | {
     readonly mode: 'manual';
 };
+/** Structured, row-level expressions. Values are bound parameters, never SQL text. */
+export type ComputationExpression = {
+    readonly input: string;
+} | {
+    readonly value: string | number | boolean | null;
+} | {
+    readonly op: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'add' | 'subtract' | 'multiply' | 'divide';
+    readonly left: ComputationExpression;
+    readonly right: ComputationExpression;
+} | {
+    readonly op: 'and' | 'or' | 'coalesce';
+    readonly args: readonly ComputationExpression[];
+} | {
+    readonly op: 'not' | 'isNull' | 'isNotNull';
+    readonly arg: ComputationExpression;
+} | {
+    readonly op: 'case';
+    readonly cases: readonly {
+        readonly when: ComputationExpression;
+        readonly then: ComputationExpression;
+    }[];
+    readonly else: ComputationExpression;
+};
+export type ComputationInput = {
+    readonly property: string;
+    readonly sourceColumn?: never;
+} | {
+    readonly sourceColumn: string;
+    readonly sourceRef?: string;
+    readonly property?: never;
+};
+/** A scalar calculation owned by one Property mapping. */
+export type PropertyMappingCalculation = {
+    readonly inputs: Readonly<Record<string, ComputationInput>>;
+} & ({
+    readonly kind: 'expression';
+    readonly expression: ComputationExpression;
+} | {
+    readonly kind: 'sql';
+    readonly sql: string;
+    /** Cache policy for this opaque SQL expression, including any internal table reads. */
+    readonly freshness?: SourceFreshnessPolicy;
+});
+export type PropertyMappingValue = {
+    readonly kind: 'column';
+    readonly column: string;
+    readonly sourceRef?: string;
+} | PropertyMappingCalculation;
 export interface SchemaMappingPredMatch {
     /** Defaults to the owning mapping's Schema. */
     readonly schema?: string;
-    readonly operator: string;
+    /** Restricts the match to one operator. Missing matches any aggregate operator. */
+    readonly operator?: string;
     readonly pred: string;
     /** Required conjunctive conditions across the LogicForm and PredItem queries. */
     readonly query?: QueryType;
@@ -28,16 +95,40 @@ export interface SchemaMappingPredDefinition {
     /** Physical column used as the matched PredItem's operator input. */
     readonly column: string;
 }
-export interface SchemaMappingItem {
-    readonly sourceColumn?: string;
-    /** Enrichment id that owns sourceColumn. Missing means the mapping's base source. */
-    readonly sourceRef?: string;
-    readonly mappingType?: 'property' | 'predItem' | 'ignored';
-    readonly propertyTarget?: readonly string[];
-    readonly predItem?: PredItemType;
-    /** Finest physical grain of a mapped Property. */
+export interface PropertyMapping {
+    readonly mappingType: 'property';
+    /** One logical Property ID, or an ID path for a directly mapped related Property. */
+    readonly propertyId: string;
+    readonly value: PropertyMappingValue;
     readonly granularity?: SchemaMappingGranularity;
 }
+export interface PredItemMapping {
+    readonly mappingType: 'predItem';
+    readonly sourceColumn: string;
+    readonly predItem: PredItemType;
+    /** Optional exact dimension path encoded by the conditional column. */
+    readonly propertyTarget?: readonly string[];
+}
+export interface IgnoredMapping {
+    readonly mappingType: 'ignored';
+    readonly sourceColumn: string;
+}
+export type SchemaMappingItem = PropertyMapping | PredItemMapping | IgnoredMapping;
+export type QueryPathBinding = {
+    readonly sourceColumn: string;
+    readonly mappingType: 'literal';
+    readonly value: string | number | boolean;
+} | {
+    readonly sourceColumn: string;
+    readonly mappingType: 'value';
+    /** Path to the matched entity relation value. */
+    readonly valuePath: readonly string[];
+};
+/** Map an entity relation path in a root query or groupby to physical columns. */
+export interface QueryPathMappingDefinition {
+    readonly path: readonly string[];
+    readonly bindings: readonly QueryPathBinding[];
+}
 export interface SchemaMappingEnrichmentKey {
     /** Physical column on the mapping's base source. */
     readonly baseColumn: string;
@@ -52,8 +143,7 @@ export interface SchemaMappingPointTemporalDefinition {
 /** A same-connection physical extension of one logical Schema. */
 export interface SchemaMappingEnrichmentDefinition {
     readonly id: string;
-    readonly source: string;
-    readonly sourceSql?: string;
+    readonly source: SchemaMappingSource;
     readonly on: readonly SchemaMappingEnrichmentKey[];
     readonly temporal?: SchemaMappingPointTemporalDefinition;
     /** Missing means queries depending on this enrichment are not cached. */
@@ -65,14 +155,14 @@ export interface SchemaMappingDefinition {
     readonly schemaId: string;
     /** Database connection used by this physical mapping. */
     readonly connectionId: string;
-    /** Stable physical source identity used by connection routing, lineage, and cache invalidation. */
-    readonly source: string;
-    /** Optional trusted query compiled as a derived-table source instead of reading source directly. */
-    readonly sourceSql?: string;
+    /** Physical row set supplied by a table or a trusted SQL query. */
+    readonly source: SchemaMappingSource;
     /** Optional physical tables that extend base rows without becoming logical Schema relations. */
     readonly enrichments?: readonly SchemaMappingEnrichmentDefinition[];
     /** Unified logical-to-physical mappings for properties and conditional PredItems. */
     readonly mappings?: readonly SchemaMappingItem[];
+    /** Entity paths handled directly by physical source columns for query and groupby. */
+    readonly queryPathMappings?: readonly QueryPathMappingDefinition[];
     /** Higher values win when multiple candidates cover the same LogicForm. */
     readonly priority?: number;
     /** Missing means queries depending on this physical source are not cached. */
@@ -81,6 +171,8 @@ export interface SchemaMappingDefinition {
 export interface RejectedSchemaMapping {
     readonly mappingId: string;
     readonly reason: string;
+    /** Dimension Properties required by the query but unavailable on this Mapping. */
+    readonly missingDimensions?: readonly string[];
 }
 /** Planner diagnostics for one physical Schema mapping decision. */
 export interface SchemaMappingSelection {

package/dist/schema-mappings/yiask.d.ts

@@ -1,25 +1,13 @@
 import type { SemanticDBPlugin } from '../plugins/index';
-import type { PredItemType } from '../logicform-types';
-import type { SchemaMappingDefinition, SchemaMappingEnrichmentDefinition, SchemaMappingGranularity } from './types';
-export interface YiAskSchemaMappingItem {
-    readonly sourceColumn?: string;
-    readonly sourceRef?: string;
-    readonly mappingType?: 'property' | 'predItem' | 'ignored';
-    readonly propertyTarget?: readonly string[];
-    readonly predItem?: PredItemType;
-    readonly granularity?: SchemaMappingGranularity;
-}
+import type { SchemaMappingDefinition, SchemaMappingSource, SchemaMappingEnrichmentDefinition, SchemaMappingItem, QueryPathMappingDefinition } from './types';
+export type YiAskSchemaMappingItem = SchemaMappingItem;
 export interface YiAskSchemaMappingRecord {
     readonly id: string | number;
-    readonly schemaSid: string;
-    readonly datasourceSid: string;
-    readonly sourceMode?: 'table' | 'demo';
-    readonly tablePath?: string;
-    readonly sourceSql?: string;
-    readonly physicalDatabase?: string;
-    readonly physicalSchema?: string;
-    readonly physicalTable?: string;
+    readonly schemaId: string;
+    readonly connectionId: string;
+    readonly source: SchemaMappingSource;
     readonly enrichments?: readonly SchemaMappingEnrichmentDefinition[];
+    readonly queryPathMappings?: readonly QueryPathMappingDefinition[];
     readonly mappings: readonly YiAskSchemaMappingItem[];
     readonly enabled?: boolean;
 }

package/dist/semantic-types/index.d.ts

@@ -5,7 +5,7 @@ export { SemanticTypeRegistry } from './registry';
 export { resolveSchema } from './resolve-schema';
 export { validateResolvedSchema } from './validate-resolved-schema';
 export { normalizePrimalQuery } from './primal-types/index';
-export type { ComparableCategoryDefinition, PropertyHierarchyDefinition, PropertySqlDefinition, PrimalType, ResolvedSemanticProperty, ResolvedSemanticSchema, LegacySemanticSchemaMetadata, ResolvedSemanticSchemaMetadata, SemanticSchemaMetadata, SemanticTypeNormalizeContext, SemanticPeriodEvaluationContext, SemanticTypeResultContext, SemanticTypeResultProperty, SemanticPropertyDraft, SemanticSchemaDraft, SemanticTypeDefinition, TimeGranularity, TimeWatermarkPolicy, } from './types';
+export type { ComparableCategoryDefinition, PropertyHierarchyDefinition, PropertySqlDefinition, LogicformPartition, LogicformPartitionContext, LogicformPartitionShard, PrimalType, ResolvedSemanticProperty, ResolvedSemanticSchema, LegacySemanticSchemaMetadata, ResolvedSemanticSchemaMetadata, SemanticSchemaMetadata, SemanticTypeNormalizeContext, SemanticPeriodEvaluationContext, SemanticTypeResultContext, SemanticTypeResultProperty, SemanticPropertyDraft, SemanticSchemaDraft, SemanticTypeDefinition, TimeGranularity, TimeWatermarkPolicy, } from './types';
 export declare const createSemanticTypeRegistry: (plugins?: readonly SemanticDBPlugin[]) => SemanticTypeRegistry;
 /** Copies a caller-owned Registry and appends plugin types without mutating the input. */
 export declare const addPluginSemanticTypes: (registry: SemanticTypeRegistry, plugins: readonly SemanticDBPlugin[]) => SemanticTypeRegistry;