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

package/dist/physical/provider.d.ts

@@ -1,10 +1,55 @@
 export type DataRow = Record<string, unknown>;
 export type SqlParameters = readonly unknown[];
+export type DatePart = 'second' | 'minute' | 'hour' | 'weekday' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+/** Module-augmentation seam for application-owned Provider kinds. */
+export interface ProviderKindExtensions {
+}
+export type ProviderKind = 'clickhouse' | 'databricks' | 'dameng' | 'doris' | 'duckdb' | 'gbase' | 'maxcompute' | 'mysql' | 'oracle' | 'postgresql' | 'snowflake' | 'sqlserver' | 'starrocks' | Extract<keyof ProviderKindExtensions, string>;
 export interface ProviderExecutionRequest {
     readonly sql: string;
     readonly parameters: SqlParameters;
     readonly signal?: AbortSignal;
 }
+/** Native SQL results, without semantic hydration or generated row identities. */
+export interface SQLResult {
+    readonly rows: DataRow[];
+    /** Omitted when the driver does not report an affected-row count. */
+    readonly affectedRows?: number;
+}
+export interface DatabaseTable {
+    readonly name: string;
+    readonly database?: string;
+    readonly schema?: string;
+    readonly type: 'table' | 'view';
+}
+export interface TableListRequest {
+    /** Database/catalog override; unsupported scopes are rejected, not ignored. */
+    readonly database?: string;
+    readonly schema?: string;
+    readonly signal?: AbortSignal;
+}
+export interface DescribeTableRequest extends TableListRequest {
+    /** Literal, unqualified physical table name; use database/schema for its namespace. */
+    readonly table: string;
+    /** Read one example row by default. Disable to inspect metadata only. */
+    readonly includeSample?: boolean;
+}
+export interface DatabaseColumn {
+    readonly name: string;
+    /** Native database type, including size/precision where available. */
+    readonly type: string;
+    readonly comment: string;
+    /** Omitted if the database/adapter cannot report primary-key membership. */
+    readonly primaryKey?: boolean;
+    /** Omitted for empty tables, disabled sampling, or a failed sample query. */
+    readonly exampleValue?: unknown;
+}
+export interface TableDescription {
+    readonly columns: DatabaseColumn[];
+    readonly tableInfo: DatabaseTable & {
+        readonly comment: string;
+    };
+}
 export interface SqlRenderCapabilities {
     /** Whether HAVING may reference an alias declared in the same SELECT list. */
     readonly supportsHavingAlias?: boolean;
@@ -12,15 +57,29 @@ export interface SqlRenderCapabilities {
     tableAlias(expression: string, alias: string): string;
     paginate(sql: string, pageSize: number, offset: number): string;
     dateBucket(expression: string, level: string): string;
+    /** Extract a numeric date component. weekday uses Monday=1 through Sunday=7. */
+    datePart(expression: string, part: DatePart): string;
     dateShift(expression: string, granularity: string, offset: number): string;
+    datePeriodBoundary?(expression: string, granularity: string, boundary: 'start' | 'end'): string;
+    /** Cast a bound literal to the semantic type required by the SQL expression. */
+    castValue?(expression: string, type: string): string;
+    /** Render a NULL-ignoring scalar extremum without a correlated subquery. */
+    scalarExtremum?(operator: 'least' | 'greatest', expressions: readonly string[]): string;
     aggregateFunction(name: string, expression?: string): string;
+    stringify(expression: string): string;
     concat(expressions: readonly string[]): string;
     substring(expression: string, start: number, length: number): string;
+    /** Return the number of characters in a string expression. */
+    stringLength(expression: string): string;
     regex(expression: string, pattern: string, options?: string): string;
     /** Whether the dialect supports a WITH RECURSIVE subquery. */
     readonly supportsRecursiveCte?: boolean;
+    /** Recursive-term set operator. Defaults to UNION when omitted. */
+    readonly recursiveCteUnion?: 'UNION' | 'UNION ALL';
     arrayContains?(arrayExpression: string, valueExpression: string): string;
-    expandArray?(arrayExpression: string, alias: string, column: string): {
+    /** Coerce a native text array, JSON array, or scalar text value to a text array. */
+    normalizeStringArray?(expression: string): string;
+    expandArray?(arrayExpression: string, alias: string, column: string, elementType?: 'string'): {
         readonly joinSql: string;
         readonly valueExpression: string;
     };
@@ -29,12 +88,17 @@ export interface SqlRenderCapabilities {
  * Internal physical database contract used by the compiler and executor.
  */
 export interface CoreComputeProvider extends SqlRenderCapabilities {
-    readonly kind: 'clickhouse' | 'doris' | 'mysql' | 'oracle' | 'postgresql' | 'snowflake' | 'starrocks';
+    readonly kind: ProviderKind;
     /** Maximum items accepted by one SQL IN expression, when the dialect has a limit. */
     readonly maxInListItems?: number;
     parameter(index: number, value: unknown): string;
     /** Render bound parameters for diagnostics only; this SQL is never executed by SemanticDB. */
     displayQuery(sql: string, parameters: SqlParameters): string;
     execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    /** Optional native-SQL capability; execute retains its row-query contract. */
+    runSQL?(request: ProviderExecutionRequest): Promise<SQLResult>;
+    /** Optional physical metadata capability, independent of semantic Schemas. */
+    getTableList?(request: TableListRequest): Promise<DatabaseTable[]>;
+    describeTable?(request: DescribeTableRequest): Promise<TableDescription>;
     close(): Promise<void>;
 }

package/dist/physical/snowflake-provider.d.ts

@@ -1,8 +1,8 @@
-import type { ConnectionOptions } from 'snowflake-sdk';
-import type { CoreComputeProvider, DataRow, ProviderExecutionRequest } from './provider';
+import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest, SQLResult, DatabaseTable, TableListRequest, DescribeTableRequest, TableDescription } from './provider';
 type SnowflakeBind = string | number | boolean | null;
 export interface SnowflakeStatementLike {
     cancel(callback?: (error?: Error) => void): void;
+    getNumUpdatedRows?(): number | undefined;
 }
 export interface SnowflakeConnectionLike {
     connect(callback: (error?: Error) => void): unknown;
@@ -13,9 +13,20 @@ export interface SnowflakeConnectionLike {
     }): SnowflakeStatementLike;
     destroy(callback: (error?: Error) => void): unknown;
 }
+export interface SnowflakeConnectionOptions {
+    readonly account?: string;
+    readonly username?: string;
+    readonly password?: string;
+    readonly warehouse?: string;
+    readonly database?: string;
+    readonly schema?: string;
+    readonly role?: string;
+    readonly authenticator?: string;
+    readonly [option: string]: unknown;
+}
 export interface SnowflakeProviderOptions {
     /** Options passed to snowflake-sdk's createConnection(). */
-    readonly connection?: ConnectionOptions;
+    readonly connection?: object;
     /** Injectable SDK connection used by tests or caller-managed connection factories. */
     readonly client?: SnowflakeConnectionLike;
 }
@@ -29,10 +40,13 @@ export declare class SnowflakeProvider implements CoreComputeProvider {
     parameter(index: number, value: unknown): string;
     displayQuery(sql: string, parameters: readonly unknown[]): string;
     dateBucket(expression: string, level: string): string;
+    datePart(expression: string, part: DatePart): string;
     dateShift(expression: string, granularity: string, offset: number): string;
     aggregateFunction(name: string, expression?: string): string;
+    stringify(expression: string): string;
     concat(expressions: readonly string[]): string;
     substring(expression: string, start: number, length: number): string;
+    stringLength(expression: string): string;
     regex(expression: string, pattern: string, options?: string): string;
     arrayContains(arrayExpression: string, valueExpression: string): string;
     expandArray(arrayExpression: string, alias: string, column: string): {
@@ -40,6 +54,9 @@ export declare class SnowflakeProvider implements CoreComputeProvider {
         valueExpression: string;
     };
     execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    runSQL(request: ProviderExecutionRequest): Promise<SQLResult>;
+    getTableList(request: TableListRequest): Promise<DatabaseTable[]>;
+    describeTable(request: DescribeTableRequest): Promise<TableDescription>;
     close(): Promise<void>;
 }
 export {};

package/dist/physical/sqlserver-provider.d.ts

@@ -0,0 +1,69 @@
+import type { CoreComputeProvider, DataRow, DatePart, ProviderExecutionRequest, SQLResult, DatabaseTable, TableListRequest, DescribeTableRequest, TableDescription } from './provider';
+type SQLServerBind = string | number | boolean | Date | Buffer | null;
+export interface SQLServerRequestLike {
+    input(name: string, value: SQLServerBind): this;
+    query(sql: string): Promise<{
+        readonly recordset?: unknown;
+        readonly rowsAffected?: readonly number[];
+    }>;
+    cancel(): void;
+}
+export interface SQLServerPoolLike {
+    connect(): Promise<unknown>;
+    request(): SQLServerRequestLike;
+    close(): Promise<void>;
+}
+export interface SQLServerDriverLike {
+    readonly ConnectionPool: new (options: object) => SQLServerPoolLike;
+}
+export interface SQLServerConnectionOptions {
+    readonly host?: string;
+    readonly server?: string;
+    readonly port?: number;
+    readonly user?: string;
+    readonly password?: string;
+    readonly database?: string;
+    readonly options?: Readonly<Record<string, unknown>>;
+    readonly pool?: Readonly<Record<string, unknown>>;
+    readonly requestTimeout?: number;
+    readonly connectionTimeout?: number;
+    readonly [option: string]: unknown;
+}
+export interface SQLServerProviderOptions {
+    readonly connection?: SQLServerConnectionOptions;
+    readonly pool?: SQLServerPoolLike;
+    readonly driver?: SQLServerDriverLike;
+}
+export declare const sqlServerPoolOptions: (connection: SQLServerConnectionOptions) => object;
+export declare class SQLServerProvider implements CoreComputeProvider {
+    #private;
+    readonly kind: "sqlserver";
+    readonly supportsHavingAlias = false;
+    constructor(options?: SQLServerProviderOptions);
+    quoteIdentifier(identifier: string): string;
+    tableAlias(expression: string, alias: string): string;
+    paginate(sql: string, pageSize: number, offset: number): string;
+    parameter(index: number, value: unknown): string;
+    displayQuery(sql: string, parameters: readonly unknown[]): string;
+    dateBucket(expression: string, level: string): string;
+    datePart(expression: string, part: DatePart): string;
+    dateShift(expression: string, granularity: string, offset: number): string;
+    castValue(expression: string, type: string): string;
+    aggregateFunction(name: string, expression?: string): string;
+    stringify(expression: string): string;
+    concat(expressions: readonly string[]): string;
+    substring(expression: string, start: number, length: number): string;
+    stringLength(expression: string): string;
+    regex(expression: string, pattern: string, options?: string): string;
+    arrayContains(arrayExpression: string, valueExpression: string): string;
+    expandArray(arrayExpression: string, alias: string, column: string): {
+        readonly joinSql: string;
+        readonly valueExpression: string;
+    };
+    execute(execution: ProviderExecutionRequest): Promise<DataRow[]>;
+    runSQL(execution: ProviderExecutionRequest): Promise<SQLResult>;
+    getTableList(request: TableListRequest): Promise<DatabaseTable[]>;
+    describeTable(request: DescribeTableRequest): Promise<TableDescription>;
+    close(): Promise<void>;
+}
+export {};

package/dist/physical/starrocks-provider.d.ts

@@ -1,9 +1,15 @@
 import { MySQLProtocolProvider } from './mysql-protocol-provider';
-import type { MySQLProtocolPoolLike, MySQLProtocolProviderOptions } from './mysql-protocol-provider';
+import type { MySQLProtocolPoolLike, MySQLProtocolConnectionOptions, MySQLProtocolProviderOptions } from './mysql-protocol-provider';
 export type StarRocksPoolLike = MySQLProtocolPoolLike;
+export type StarRocksConnectionOptions = MySQLProtocolConnectionOptions;
 export type StarRocksProviderOptions = MySQLProtocolProviderOptions;
 /** StarRocks adapter using its MySQL-compatible protocol and SQL surface. */
 export declare class StarRocksProvider extends MySQLProtocolProvider {
     readonly kind: "starrocks";
     constructor(options?: StarRocksProviderOptions);
+    arrayContains(arrayExpression: string, valueExpression: string): string;
+    expandArray(arrayExpression: string, alias: string, column: string): {
+        readonly joinSql: string;
+        readonly valueExpression: string;
+    };
 }

package/dist/physical/table-description.d.ts

@@ -0,0 +1,5 @@
+import type { CoreComputeProvider, DataRow, DescribeTableRequest, TableDescription } from './provider';
+export declare const validateDescribeTable: (request: DescribeTableRequest) => void;
+/** INFORMATION_SCHEMA/Oracle expose size separately; PostgreSQL/MySQL already format native types. */
+export declare const columnType: (row: DataRow) => string;
+export declare const describePhysicalTable: (provider: CoreComputeProvider, request: DescribeTableRequest) => Promise<TableDescription>;

package/dist/physical/table-discovery.d.ts

@@ -0,0 +1,10 @@
+import type { CoreComputeProvider, DatabaseTable, DataRow, TableListRequest } from './provider';
+export declare const validateTableScope: (request: TableListRequest) => void;
+export declare const rejectTableScope: (provider: CoreComputeProvider, field: "database" | "schema") => never;
+/** Drivers differ in alias casing; never silently discard malformed metadata rows. */
+export declare const metadataValue: (row: DataRow, field: string) => unknown;
+export declare const metadataString: (row: DataRow, field: string) => string;
+export declare const normalizeTableRow: (row: DataRow) => DatabaseTable;
+export declare const normalizeTableMetadata: (rows: DataRow[]) => DatabaseTable[];
+/** Physical metadata SQL only; no semantic Schema resolution belongs here. */
+export declare const discoverTables: (provider: CoreComputeProvider, request: TableListRequest) => Promise<DatabaseTable[]>;

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) => QueryLineage;
+export declare const buildLineage: (plan: LogicalPlan, schema: ResolvedSemanticSchema, provider: CoreComputeProvider, operators?: OperatorRegistry, providerForConnection?: (connectionId: string) => CoreComputeProvider) => QueryLineage;

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

@@ -1,6 +1,8 @@
 import type { LogicformType } 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 { ResolvedSemanticProperty } from '../semantic-types/index';
 import { type PlannerSemanticRegistry } from './semantics/index';
@@ -8,8 +10,13 @@ import type { LogicalPlan } from './types';
 export declare const createResultSchema: (plan: LogicalPlan, sourceSchema: ResolvedSemanticSchema) => ResolvedSemanticSchema;
 export declare const createDerivedSourceSchema: (sourcePlan: LogicalPlan, outerSchema: ResolvedSemanticSchema) => ResolvedSemanticSchema;
 export interface CreateLogicalPlanOptions {
+    readonly plugins?: readonly SemanticDBPlugin[];
     readonly resolveSchema?: (schemaId: string) => ResolvedSemanticSchema;
+    /** Prefer physical mappings colocated with the execution's main connection. */
+    readonly preferredConnectionId?: string;
     readonly canUsePropertyRowIdentity?: (schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty) => boolean;
     readonly semanticRegistry?: PlannerSemanticRegistry;
+    /** Observe each physical Schema mapping decision made during planning. */
+    readonly onSchemaMappingSelection?: (selection: SchemaMappingSelection) => void;
 }
 export declare const createLogicalPlan: (logicform: LogicformType, schema: ResolvedSemanticSchema, operators?: OperatorRegistry, schemaMappings?: SchemaMappingRegistry, options?: CreateLogicalPlanOptions) => LogicalPlan;

package/dist/planner/index.d.ts

@@ -1,7 +1,9 @@
 export { buildLineage } from './build-lineage';
 export { createDerivedSourceSchema, createLogicalPlan, createResultSchema } from './create-logical-plan';
 export type { CreateLogicalPlanOptions } from './create-logical-plan';
-export type { Expression, ArrayExpansionPlan, FieldReferencePlan, GroupLimitPlan, JoinPlan, LogicalQuerySubquery, LogicalRecursiveQuery, LogicalOrdinalQuery, LineageColumnSource, LineageOutput, LogicalPlan, OrderPlan, PaginationPlan, ProjectionPlan, QueryLineage, RowIdentityPlan, } from './types';
-export { isLogicalQuerySubquery, isLogicalRecursiveQuery } from './types';
+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 { isLogicalQuerySubquery, isLogicalQueryOperator } from './types';
 export { isLogicalOrdinalQuery } from './types';
+export { isLogicalExpressionQuery } from './types';
 export * from './semantics/index';
+export { createPlannerSemanticRegistry } from './semantics/registry-defaults';

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

@@ -0,0 +1,7 @@
+import type { LogicformType } from '../logicform-types';
+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. */
+export declare const mappingGranularityReason: (logicform: LogicformType, schema: ResolvedSemanticSchema, mapping: SchemaMappingDefinition, resolveSchema?: (schemaId: string) => ResolvedSemanticSchema, plugins?: readonly SemanticDBPlugin[], operators?: OperatorRegistry) => string | undefined;

package/dist/planner/rewrite-nested-components.d.ts

@@ -0,0 +1,8 @@
+import type { LogicformType } from '../logicform-types';
+import type { OperatorRegistry } from '../operators/index';
+/**
+ * Lift component inputs into a derived LogicForm so ordinary expression operators can consume
+ * their result columns. The inner LogicForm owns source-grain work; the outer LogicForm owns
+ * result operations and the expression path above every component.
+ */
+export declare const rewriteNestedComponents: (logicform: LogicformType, operators: OperatorRegistry) => LogicformType | undefined;

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

@@ -1,6 +1,8 @@
 import type { LogicformType } from '../logicform-types';
-import type { SchemaMappingDefinition, SchemaMappingRegistry } from '../schema-mappings/index';
+import type { SemanticDBPlugin } from '../plugins/index';
+import type { SchemaMappingDefinition, SchemaMappingRegistry, SchemaMappingSelection } from '../schema-mappings/index';
 import type { ResolvedSemanticSchema } from '../semantic-types/index';
+import { type OperatorRegistry } from '../operators/index';
 export interface PredMappingRewrite {
     readonly predIndex: number;
     readonly column: string;
@@ -9,6 +11,18 @@ export interface SelectedSchemaMapping {
     readonly mapping: SchemaMappingDefinition;
     readonly logicform: LogicformType;
     readonly predRewrites: readonly PredMappingRewrite[];
+    readonly selection: SchemaMappingSelection;
+}
+export interface MappedPropertySource {
+    readonly column: string;
+    readonly sourceRef?: string;
 }
 export declare const mappedPropertyColumn: (mapping: SchemaMappingDefinition, schema: ResolvedSemanticSchema, reference: string) => string | undefined;
-export declare const selectSchemaMapping: (logicform: LogicformType, schema: ResolvedSemanticSchema, mappings: SchemaMappingRegistry) => SelectedSchemaMapping;
+export declare const mappedPropertySource: (mapping: SchemaMappingDefinition, schema: ResolvedSemanticSchema, reference: string) => MappedPropertySource | undefined;
+export declare const selectSchemaMapping: (logicform: LogicformType, schema: ResolvedSemanticSchema, mappings: SchemaMappingRegistry, options?: {
+    readonly preferredConnectionId?: string;
+    readonly resolveSchema?: (schemaId: string) => ResolvedSemanticSchema;
+    /** Extra plugins used by this execution; must also be supplied when registering plugin grains. */
+    readonly plugins?: readonly SemanticDBPlugin[];
+    readonly operators?: OperatorRegistry;
+}) => SelectedSchemaMapping;

package/dist/planner/semantics/index.d.ts

@@ -1,5 +1,2 @@
-export * from './observation/index';
-export * from './lifecycle/index';
 export { PlannerSemanticRegistry } from './registry';
 export type { PlannerSemanticResolution, PlannerSemanticQueryContext, PlannerSemanticRule, PlannerSemanticRuleContext, } from './registry';
-export { createPlannerSemanticRegistry } from './registry-defaults';

package/dist/planner/semantics/periods.d.ts

@@ -0,0 +1,13 @@
+import type { TimeGranularity } from '../../semantic-types/index';
+export interface Period {
+    readonly label: string;
+    readonly start: string;
+    readonly end: string;
+}
+export interface PeriodErrorContext {
+    readonly codePrefix: string;
+    readonly label: string;
+}
+export declare const isTimeGranularity: (value: unknown) => value is TimeGranularity;
+/** Expand one bounded time condition into natural boundaries at the requested granularity. */
+export declare const resolvePeriods: (condition: unknown, granularity: TimeGranularity, context: PeriodErrorContext) => readonly Period[];

package/dist/planner/semantics/registry-defaults.d.ts

@@ -1,2 +1,3 @@
 import { PlannerSemanticRegistry } from './registry';
-export declare const createPlannerSemanticRegistry: () => PlannerSemanticRegistry;
+import type { SemanticDBPlugin } from '../../plugins/index';
+export declare const createPlannerSemanticRegistry: (plugins?: readonly SemanticDBPlugin[]) => PlannerSemanticRegistry;

package/dist/planner/semantics/registry.d.ts

@@ -1,13 +1,14 @@
 import type { PredItemType } from '../../logicform-types';
 import type { LogicformType, QueryType } from '../../logicform-types';
 import type { ResolvedSemanticProperty, ResolvedSemanticSchema } from '../../semantic-types/index';
-import type { OperatorDefinition, ResultProperty } from '../../operators/index';
+import type { OperatorDefinition, OperatorExecutionContext, ResultProperty } from '../../operators/index';
 export interface PlannerSemanticRuleContext {
     readonly pred: PredItemType;
     readonly schema: ResolvedSemanticSchema;
     readonly sourceProperty?: ResolvedSemanticProperty;
     readonly outputProperty: ResultProperty;
     readonly operator?: OperatorDefinition;
+    readonly executionContext?: OperatorExecutionContext;
 }
 export interface PlannerSemanticQueryContext {
     readonly logicform: LogicformType;

package/dist/planner/types.d.ts

@@ -1,6 +1,8 @@
 import type { CoreComputeProvider } from '../physical/index';
+import type { LogicformType } from '../logicform-types';
 import type { ResultProperty } from '../operators/index';
 import type { ComparableCategoryDefinition, TimeGranularity } from '../semantic-types/index';
+import type { QueryOperatorDefinition } from '../plugins/index';
 export interface FieldReferencePlan {
     readonly schemaId: string;
     readonly property: string;
@@ -10,31 +12,44 @@ export interface FieldReferencePlan {
     readonly qualifier: string;
     readonly sql?: string;
     readonly timestampColumn?: string;
+    /** Source alias that supplies $TS when it differs from the Property's Schema. */
+    readonly timestampQualifier?: string;
     readonly isArray?: boolean;
+    /** Accept native text arrays and JSON/scalar representations of string arrays. */
+    readonly normalizeStringArray?: boolean;
     readonly comparable?: ComparableCategoryDefinition;
 }
 export interface LogicalQuerySubquery {
     readonly kind: 'logicform-subquery';
     readonly plan: LogicalPlan;
 }
-export interface LogicalRecursiveQuery {
-    readonly kind: 'recursive-query';
-    readonly schemaId: string;
-    readonly source: string;
-    readonly sourceSql?: string;
-    readonly idColumn: string;
-    readonly parentColumn: string;
-    readonly roots: readonly unknown[];
-    readonly includeSelf: boolean;
+export interface LogicalQueryOperator {
+    readonly kind: 'query-operator';
+    readonly operator: string;
+    readonly value: unknown;
+    readonly sources?: readonly {
+        readonly schemaId: string;
+        readonly source: string;
+        readonly connectionId?: string;
+    }[];
+    /** Capability selected during planning; omitted only by manually constructed plans. */
+    readonly definition?: QueryOperatorDefinition;
 }
 export interface LogicalOrdinalQuery {
     readonly kind: 'ordinal-query';
     readonly comparable: ComparableCategoryDefinition;
     readonly condition: unknown;
 }
+export interface LogicalExpressionQuery {
+    readonly kind: 'expression-query';
+    readonly expression: Expression;
+    readonly condition: unknown;
+    readonly properties: readonly string[];
+}
 export declare const isLogicalQuerySubquery: (value: unknown) => value is LogicalQuerySubquery;
-export declare const isLogicalRecursiveQuery: (value: unknown) => value is LogicalRecursiveQuery;
+export declare const isLogicalQueryOperator: (value: unknown) => value is LogicalQueryOperator;
 export declare const isLogicalOrdinalQuery: (value: unknown) => value is LogicalOrdinalQuery;
+export declare const isLogicalExpressionQuery: (value: unknown) => value is LogicalExpressionQuery;
 export type Expression = {
     readonly kind: 'array-element';
     readonly schemaId: string;
@@ -55,6 +70,7 @@ export type Expression = {
     readonly sql: string;
     readonly qualifier?: string;
     readonly timestampColumn?: string;
+    readonly timestampQualifier?: string;
 } | {
     readonly kind: 'operator';
     readonly operator: string;
@@ -63,7 +79,7 @@ export type Expression = {
     readonly qualifier?: string;
     readonly schemaId?: string;
     readonly input?: Expression;
-    readonly components?: readonly Expression[];
+    readonly inputs?: readonly Expression[];
     readonly args: Readonly<Record<string, unknown>>;
     readonly query?: Readonly<Record<string, unknown>>;
 } | {
@@ -107,17 +123,45 @@ export interface JoinPlan {
     readonly sourceColumn: string;
     readonly sourceSql?: string;
     readonly sourceTimestampColumn?: string;
-    readonly sourceTimestampGranularity?: TimeGranularity;
     readonly targetSchemaId: string;
+    /** Physical connection selected for the target Schema mapping. */
+    readonly targetConnectionId?: string;
     readonly targetSource: string;
     readonly targetSourceSql?: string;
     readonly targetAlias: string;
     readonly targetColumn: string;
     readonly targetSql?: string;
     readonly targetTimestampColumn?: string;
-    readonly targetTimestampGranularity?: TimeGranularity;
+    readonly temporalCondition?: TemporalJoinConditionPlan;
     readonly sourceArrayExpansionPath?: string;
 }
+export type TemporalJoinConditionPlan = {
+    readonly kind: 'date-bucket-equal';
+    readonly sourceColumn: string;
+    readonly targetColumn: string;
+    readonly sourceGranularity: TimeGranularity;
+    readonly targetGranularity: TimeGranularity;
+} | {
+    readonly kind: 'point-in-interval';
+    readonly pointSide: 'source' | 'target';
+    readonly pointColumn: string;
+    readonly intervalSide: 'source' | 'target';
+    readonly startColumn: string;
+    readonly endColumn: string;
+};
+export interface EnrichmentJoinPlan {
+    readonly kind: 'enrichment-left';
+    readonly id: string;
+    readonly source: string;
+    readonly sourceSql?: string;
+    readonly alias: string;
+    readonly baseAlias: string;
+    readonly keys: readonly {
+        readonly baseColumn: string;
+        readonly targetColumn: string;
+    }[];
+    readonly temporalCondition?: TemporalJoinConditionPlan;
+}
 export interface ArrayExpansionPlan {
     readonly path: string;
     readonly sourceAlias: string;
@@ -125,6 +169,8 @@ export interface ArrayExpansionPlan {
     readonly sourceSql?: string;
     readonly sourceTimestampColumn?: string;
     readonly alias: string;
+    readonly normalizeStringArray?: boolean;
+    readonly elementType?: 'string';
 }
 export type PaginationPlan = {
     readonly kind: 'rows';
@@ -140,9 +186,30 @@ export interface GroupLimitPlan {
     readonly partitionBy: readonly string[];
     readonly orderBy: readonly OrderPlan[];
 }
+export interface PeriodSourcePlan {
+    readonly alias: string;
+    readonly labelColumn: string;
+    readonly asOfColumn: string;
+    readonly sourceAlias: string;
+    readonly periods: readonly {
+        readonly label: string;
+        readonly asOf: string;
+    }[];
+    readonly match: {
+        readonly kind: 'interval';
+        readonly startColumn: string;
+        readonly endColumn: string;
+    } | {
+        readonly kind: 'latest';
+        readonly lookupAlias: string;
+        readonly timestampColumn: string;
+    };
+}
 export type RowIdentityPlan = {
     readonly kind: 'group';
     readonly names: readonly string[];
+    readonly separator: string;
+    readonly nullLabel: string;
 } | {
     readonly kind: 'property';
     readonly column: string;
@@ -155,19 +222,27 @@ export type RowIdentityPlan = {
 export interface LogicalPlan {
     readonly schemaId: string;
     readonly source: string;
+    /** 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;
     /** Physical mapping selected by the Planner for this logical Schema. */
     readonly mappingId?: string;
     /** Child relations combined by their compatible group identity. */
-    readonly composition?: readonly LogicalPlan[];
+    readonly subplans?: readonly LogicalPlan[];
     /** 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. */
+    readonly sourceLogicform?: LogicformType;
     readonly sourceAlias?: string;
     readonly fields: Readonly<Record<string, string>>;
     readonly fieldReferences?: Readonly<Record<string, FieldReferencePlan>>;
     readonly joins?: readonly JoinPlan[];
+    /** Physical extensions of this mapping, added only when a mapped property uses them. */
+    readonly enrichmentJoins?: readonly EnrichmentJoinPlan[];
     readonly arrayExpansions?: readonly ArrayExpansionPlan[];
+    /** Generated period rows matched to a source by a plugin-selected generic strategy. */
+    readonly periodSource?: PeriodSourcePlan;
     readonly projections: readonly ProjectionPlan[];
     readonly columnProperties?: readonly ResultProperty[];
     readonly groupBy: readonly ProjectionPlan[];
@@ -196,6 +271,11 @@ export interface QueryLineage {
         readonly schemaName: string;
         readonly physicalTable: string;
         readonly provider: CoreComputeProvider['kind'];
+        readonly connectionId?: string;
+        readonly connections?: readonly {
+            readonly connectionId: string;
+            readonly provider: CoreComputeProvider['kind'];
+        }[];
     };
     readonly outputs: readonly LineageOutput[];
     readonly filters: readonly LineageColumnSource[];

package/dist/plugins/hierarchy/index.d.ts

@@ -1,3 +1,3 @@
 import type { SemanticDBPlugin } from '../types';
-export type { HierarchyDefinition, HierarchyLevelDefinition, ResolvedHierarchyDefinition, } from './types';
+export type { HierarchyDefinition, HierarchyLevelDefinition, ResolvedHierarchyDefinition, SchemaMappingHierarchyGranularity, } from './types';
 export declare const hierarchyPlugin: SemanticDBPlugin;

package/dist/plugins/hierarchy/mapping-granularity.d.ts

@@ -0,0 +1,4 @@
+import type { MappingGranularityPlugin } from '../types';
+import type { SchemaMappingHierarchyGranularity } from './types';
+export declare const isMappingHierarchyGranularity: (value: unknown) => value is SchemaMappingHierarchyGranularity;
+export declare const hierarchyMappingGranularity: MappingGranularityPlugin;