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

package/dist/normalizer/core.d.ts

@@ -2,18 +2,32 @@ import type { LogicformType } from '../logicform-types';
 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';
 export interface NormalizeLogicformOptions {
     readonly semanticTypes: SemanticTypeRegistry;
     readonly operators?: OperatorRegistry;
     readonly plugins?: readonly SemanticDBPlugin[];
     /** Locale used for generated human-readable PredItem names. Defaults to zh-CN. */
     readonly locale?: string;
+    /** Additional or overriding locale files used for generated names. */
+    readonly locales?: LocaleInput;
+    /** Internal registry shared by recursive normalization calls. */
+    readonly localeRegistry?: LocaleRegistry;
     readonly now?: Date;
     readonly resolveSchema?: (schemaId: string) => ResolvedSemanticSchema;
-    readonly requestLatestDataDate?: (schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty) => Promise<Date | undefined>;
+    readonly requestTimeWatermark?: (schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty, requestedUpperBound: Date) => Promise<Date | undefined>;
+    readonly requestAutoCaseBounds?: (schema: ResolvedSemanticSchema, reference: string, query: LogicformType['query']) => Promise<{
+        readonly min: number;
+        readonly max: number;
+        readonly count: number;
+    } | {
+        readonly empty: true;
+    }>;
+    /** Internal root query used to resolve automatic `$case` boundaries. */
+    readonly autoCaseQuery?: LogicformType['query'];
     readonly resolveFromSchema?: (normalizedFrom: LogicformType, outerSchema: ResolvedSemanticSchema) => ResolvedSemanticSchema;
     readonly canProjectProperty?: (schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty) => boolean;
     /** Internal recursion hook installed by normalizeLogicform. */
     readonly normalizeNestedLogicform?: (logicform: LogicformType) => Promise<LogicformType>;
 }
-export declare const resolveLogicformSchema: (logicform: LogicformType, currentSchema: ResolvedSemanticSchema, options: NormalizeLogicformOptions) => ResolvedSemanticSchema;
+export declare const resolveFormSchema: (logicform: LogicformType, currentSchema: ResolvedSemanticSchema, options: NormalizeLogicformOptions) => ResolvedSemanticSchema;

package/dist/normalizer/default-pred-name.d.ts

@@ -1,6 +1,8 @@
 import type { PredItemType } from '../logicform-types';
 import type { OperatorRegistry } from '../operators/index';
+import { type LocaleRegistry } from '../i18n/index';
 export interface DefaultPredNameOptions {
     readonly locale?: string;
+    readonly localeRegistry?: LocaleRegistry;
 }
 export declare const defaultPredName: (pred: PredItemType, operators: OperatorRegistry, options?: DefaultPredNameOptions) => string;

package/dist/normalizer/index.d.ts

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

package/dist/normalizer/pred-expression.d.ts

@@ -0,0 +1,6 @@
+import type { LogicformType, PredItemType } from '../logicform-types';
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+import type { NormalizeLogicformOptions } from './core';
+type NormalizePredQuery = (query: LogicformType['query'], schema: ResolvedSemanticSchema, options: NormalizeLogicformOptions) => Promise<LogicformType['query']>;
+export declare const normalizePredExpression: (pred: PredItemType, schema: ResolvedSemanticSchema, options: NormalizeLogicformOptions, normalizePredQuery: NormalizePredQuery) => Promise<PredItemType>;
+export {};

package/dist/normalizer/property-resolve.d.ts

@@ -0,0 +1,6 @@
+import type { LogicformType } from '../logicform-types';
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+import type { NormalizeLogicformOptions } from './core';
+export declare const inferPropertyResolvePath: (rootSchema: ResolvedSemanticSchema, reference: string, targetSchema: ResolvedSemanticSchema, resolveSchema?: (schemaId: string) => ResolvedSemanticSchema) => string | undefined;
+/** Adds cross-Schema aliases after both legacy and v2 forms share normalization. */
+export declare const normalizePropertyResolve: (logicform: LogicformType, rootSchema: ResolvedSemanticSchema, options: NormalizeLogicformOptions) => LogicformType;

package/dist/operators/builtins/constant.d.ts

@@ -0,0 +1,2 @@
+import type { OperatorDefinition } from '../types';
+export declare const constantOperator: OperatorDefinition;

package/dist/operators/builtins/period-name.d.ts

@@ -1 +1,2 @@
-export declare const periodComparisonName: (args: Readonly<Record<string, unknown>>, locale: string) => string;
+import type { LocaleTranslate } from '../../i18n/index';
+export declare const periodComparisonName: (args: Readonly<Record<string, unknown>>, locale: string, t?: LocaleTranslate) => string;

package/dist/operators/builtins/period-value.d.ts

@@ -0,0 +1,2 @@
+import type { OperatorDefinition } from '../types';
+export declare const periodValueOperator: OperatorDefinition;

package/dist/operators/builtins/query-expression.d.ts

@@ -0,0 +1,3 @@
+import type { OperatorDefinition } from '../types';
+export declare const lengthOperator: OperatorDefinition;
+export declare const datePartOperators: readonly OperatorDefinition[];

package/dist/operators/builtins/scalar-extremum.d.ts

@@ -0,0 +1,3 @@
+import type { OperatorDefinition } from '../types';
+export declare const leastOperator: OperatorDefinition;
+export declare const greatestOperator: OperatorDefinition;

package/dist/operators/index.d.ts

@@ -1,7 +1,8 @@
 import type { SemanticDBPlugin } from '../plugins/index';
 import { OperatorRegistry } from './registry';
 export { OperatorRegistry } from './registry';
+export { resolveOperator } from './resolve';
 export { bindTrustedSqlExpression } from './sql-expression';
-export type { OperatorDefinition, OperatorDefaultNameContext, OperatorComponentContext, OperatorCteCalculation, OperatorCteComponent, OperatorCteSqlContext, OperatorExecutionComponent, OperatorGroupKeyShift, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorEvaluateContext, OperatorOutputPropertyContext, OperatorObservationPolicy, OperatorObservationPolicyContext, OperatorNormalizePredContext, OperatorPlanExpressionContext, OperatorPeriodEvaluationContext, OperatorPlanInputContext, OperatorPlannedInput, OperatorRewriteLogicformContext, OperatorValidatePlanContext, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, } from './types';
+export type { OperatorDefinition, OperatorDefaultNameContext, OperatorExecutionContext, OperatorComponentContext, OperatorComponentCalculation, OperatorComponentQuery, OperatorExecutionComponent, OperatorGroupKeyShift, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorEvaluateContext, OperatorOutputPropertyContext, OperatorPeriodBoundaryPolicy, OperatorPeriodBoundaryPolicyContext, OperatorNormalizePredContext, OperatorPlanExpressionContext, OperatorPeriodEvaluationContext, OperatorPlanInputContext, OperatorPlannedInput, OperatorRewriteLogicformContext, OperatorValidatePlanContext, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, ResultPropertyTemporalMetadataExtensions, } from './types';
 export declare const builtinOperators: readonly import("./types").OperatorDefinition[];
 export declare const createOperatorRegistry: (plugins?: readonly SemanticDBPlugin[]) => OperatorRegistry;

package/dist/operators/registry.d.ts

@@ -1,8 +1,10 @@
-import type { OperatorDefinition, OperatorPeriodEvaluationContext } from './types';
+import type { OperatorDefinition, OperatorExecutionContext, OperatorPeriodEvaluationContext } from './types';
 export declare class OperatorRegistry {
     #private;
-    constructor(definitions?: readonly OperatorDefinition[]);
-    register(definition: OperatorDefinition): this;
+    readonly executionContext: OperatorExecutionContext;
+    constructor(definitions?: readonly OperatorDefinition[], executionContext?: OperatorExecutionContext);
+    withExecutionContext(executionContext: OperatorExecutionContext): OperatorRegistry;
+    register(input: OperatorDefinition): this;
     get(name: string): OperatorDefinition;
     requiresPerPeriodEvaluation(name: string, context: OperatorPeriodEvaluationContext): boolean;
     has(name: string): boolean;

package/dist/operators/resolve.d.ts

@@ -0,0 +1,3 @@
+import type { OperatorDefinition } from './types';
+/** Resolve an operator definition loaded from JSON or another untyped source. */
+export declare const resolveOperator: (input: unknown) => OperatorDefinition;

package/dist/operators/types.d.ts

@@ -1,7 +1,17 @@
 import type { PrimalType, ResolvedSemanticProperty, ResolvedSemanticSchema, TimeGranularity, ComparableCategoryDefinition } from '../semantic-types/index';
 import type { LogicformType, PredItemType } from '../logicform-types';
 import type { DataRow } from '../physical/index';
-import type { Expression } from '../planner/index';
+import type { Expression, LogicalPlan } from '../planner/index';
+import type { LocaleTranslate } from '../i18n/index';
+/** Immutable data shared by all Operator hooks during one LogicForm execution. */
+export interface OperatorExecutionContext {
+    /** Complete rows from the unique Schema marked with `is_calendar`. */
+    readonly calendar?: readonly Readonly<DataRow>[];
+}
+interface OperatorHookContext {
+    /** Always supplied by the executor; optional for direct unit-level hook invocation. */
+    readonly executionContext?: OperatorExecutionContext;
+}
 export interface OperatorSqlCapabilities {
     /** Produce a dialect-specific aggregate function around an expression. */
     aggregateFunction(name: string, expression?: string): string;
@@ -9,18 +19,25 @@ export interface OperatorSqlCapabilities {
     quoteIdentifier(identifier: string): string;
     concat(expressions: readonly string[]): string;
     substring(expression: string, start: number, length: number): string;
+    stringLength(expression: string): string;
+    datePart(expression: string, part: 'second' | 'minute' | 'hour' | 'weekday' | 'day' | 'week' | 'month' | 'quarter' | 'year'): string;
     dateBucket(expression: string, granularity: TimeGranularity): string;
+    dateShift(expression: string, granularity: TimeGranularity, offset: number): string;
+    /** Render a period boundary directly when the dialect has a concise native form. */
+    datePeriodBoundary?(expression: string, granularity: TimeGranularity, boundary: 'start' | 'end'): string;
+    /** Render a NULL-ignoring scalar extremum using a dialect-native expression. */
+    scalarExtremum?(operator: 'least' | 'greatest', expressions: readonly string[]): string;
     /** Bind a literal as a SQL parameter. */
-    value(value: unknown): string;
+    value(value: unknown, type?: string): string;
     /** Compile a field-local LogicForm condition against an expression. */
     condition(expression: string, condition: unknown): string;
 }
 /** Context passed to an operator that pushes its computation into SQL. */
-export interface OperatorSqlContext {
+export interface OperatorSqlContext extends OperatorHookContext {
     readonly sql: OperatorSqlCapabilities;
     /** SQL for the nested input expression, when this operator has one. */
     readonly expression?: string;
-    /** SQL expressions produced by a multi-input operator's structural components. */
+    /** SQL expressions produced by a multi-input pred. */
     readonly expressions?: readonly string[];
     /** Quoted physical column for a leaf-property operator. */
     readonly column?: string;
@@ -28,7 +45,7 @@ export interface OperatorSqlContext {
     readonly args: Readonly<Record<string, unknown>>;
 }
 /** Context passed to an operator evaluated after the provider returns rows. */
-export interface OperatorEvaluateContext {
+export interface OperatorEvaluateContext extends OperatorHookContext {
     /** Value produced by the nested expression, or undefined for a propertyless operator. */
     readonly input: unknown;
     /** Operator-specific LogicForm arguments. */
@@ -40,6 +57,8 @@ export interface ResultProperty {
     readonly type: string;
     readonly primal_type: PrimalType;
     readonly isArray: boolean;
+    /** Description inherited from the source Property or supplied by the operator. */
+    readonly description?: string;
     /** Referenced Schema for object-valued result columns. */
     readonly ref?: string;
     readonly granularity?: TimeGranularity;
@@ -47,8 +66,11 @@ export interface ResultProperty {
     /** Runtime temporal semantics for this output column, when applicable. */
     readonly temporal?: ResultPropertyTemporalMetadata;
 }
-export interface ResultPropertyTemporalMetadata {
-    readonly kind: 'period-boundary' | 'period-shift' | 'date-bucket' | 'lifecycle';
+/** Plugin-owned result temporal metadata extends this interface by key. */
+export interface ResultPropertyTemporalMetadataExtensions {
+}
+export type ResultPropertyTemporalMetadata = {
+    readonly kind: 'period-boundary' | 'period-shift' | 'date-bucket';
     readonly boundary?: 'start' | 'end';
     readonly sourceProperty?: string;
     readonly requestedRange?: {
@@ -68,39 +90,41 @@ export interface ResultPropertyTemporalMetadata {
         readonly group: Readonly<Record<string, unknown>>;
         readonly date: string;
     }[];
-}
-export interface OperatorOutputPropertyContext {
+} | ResultPropertyTemporalMetadataExtensions[keyof ResultPropertyTemporalMetadataExtensions];
+export interface OperatorOutputPropertyContext extends OperatorHookContext {
     /** Final alias assigned to this operator's single output column. */
     readonly name: string;
     /** Original Schema property when the operator starts from a physical property. */
     readonly property?: ResolvedSemanticProperty;
     /** Semantic metadata produced by a nested expression. */
     readonly inputProperty?: ResultProperty;
-    /** Semantic metadata produced by structural components. */
-    readonly componentProperties?: readonly ResultProperty[];
+    /** Semantic metadata produced by a multi-input pred. */
+    readonly inputProperties?: readonly ResultProperty[];
     /** Operator-specific LogicForm arguments. */
     readonly args: Readonly<Record<string, unknown>>;
 }
 /** Context used by operators whose value must be evaluated per time bucket. */
-export interface OperatorPeriodEvaluationContext {
+export interface OperatorPeriodEvaluationContext extends OperatorHookContext {
     readonly logicform: LogicformType;
     readonly pred: PredItemType;
     readonly schema: ResolvedSemanticSchema;
     readonly inputProperty?: ResolvedSemanticProperty;
 }
-export interface OperatorDefaultNameContext {
-    /** Name produced by the direct pred, structural components, or localized row label. */
+export interface OperatorDefaultNameContext extends OperatorHookContext {
+    /** Name produced by the direct pred inputs or localized row label. */
     readonly operandName: string;
     /** Name of a direct or nested pred input. */
     readonly inputName?: string;
-    /** Names of structural component inputs. */
-    readonly componentNames: readonly string[];
+    /** Names of multi-input pred values. */
+    readonly inputNames: readonly string[];
     /** Operator-specific LogicForm arguments. */
     readonly args: Readonly<Record<string, unknown>>;
-    /** Requested locale. Each operator owns its own localized default names. */
+    /** Requested locale for generated names. */
     readonly locale: string;
+    /** Translate a stable message key using the requested locale. */
+    readonly t?: LocaleTranslate;
 }
-export interface OperatorPlanInputContext {
+export interface OperatorPlanInputContext extends OperatorHookContext {
     /** Canonical property or relation reference supplied as this operator's direct pred. */
     readonly reference: string;
     readonly args: Readonly<Record<string, unknown>>;
@@ -113,46 +137,55 @@ export interface OperatorPlannedInput {
     /** Provider-independent arguments resolved from semantic metadata. */
     readonly args: Readonly<Record<string, unknown>>;
 }
-export interface OperatorNormalizePredContext {
+export interface OperatorNormalizePredContext extends OperatorHookContext {
     readonly pred: PredItemType;
     readonly schema: ResolvedSemanticSchema;
 }
-export interface OperatorPlanExpressionContext {
+export interface OperatorPlanExpressionContext extends OperatorHookContext {
     readonly pred: PredItemType;
     readonly input?: Expression;
     readonly inputProperty?: ResultProperty;
-    readonly components: readonly Expression[];
+    readonly inputs: readonly Expression[];
     readonly args: Readonly<Record<string, unknown>>;
     readonly resolveKey: (reference: string) => Expression;
     readonly getOperator: (name: string) => OperatorDefinition;
     readonly planQuery: (query: Readonly<Record<string, unknown>>) => Readonly<Record<string, unknown>>;
 }
-export interface OperatorObservationPolicyContext {
+export interface OperatorPeriodBoundaryPolicyContext extends OperatorHookContext {
     readonly pred: PredItemType;
 }
-export interface OperatorObservationPolicy {
+export interface OperatorPeriodBoundaryPolicy {
     readonly boundary: 'start' | 'end';
     readonly implicit: boolean;
 }
-export interface OperatorValidatePlanContext {
+export interface OperatorValidatePlanContext extends OperatorHookContext {
     readonly pred: PredItemType;
     readonly groupByNames: readonly string[];
     readonly resolveGroupName: (reference: string) => string | undefined;
     readonly getOperator: (name: string) => OperatorDefinition;
 }
-export interface OperatorRewriteLogicformContext {
+export interface OperatorValidateGroupbyContext extends OperatorHookContext {
+    readonly pred: PredItemType;
+}
+export interface OperatorRewriteLogicformContext extends OperatorHookContext {
     readonly logicform: LogicformType;
     readonly schema: ResolvedSemanticSchema;
+    /** Resolve operator metadata while rewriting nested expressions. */
+    readonly getOperator?: (name: string) => OperatorDefinition;
 }
-export interface OperatorComponentContext {
-    /** Fully normalized LogicForm containing this top-level operator projection. */
+export interface OperatorComponentContext extends OperatorHookContext {
+    /** Normalized input LogicForm; having, sort, limit, limitBy, and page stay on the merged result. */
     readonly logicform: LogicformType;
-    /** Caller-authored normalized LogicForm before executor row policies were added. */
+    /** Caller-authored normalized input before executor row policies, with result operations removed. */
     readonly sourceLogicform?: LogicformType;
     /** The operator projection for which the component is being built. */
     readonly pred: PredItemType;
     /** Final output alias assigned by the planner. */
     readonly outputName: string;
+    /** Requested locale for child component names. */
+    readonly locale: string;
+    /** Translate a stable message key using the requested locale. */
+    readonly t: LocaleTranslate;
     readonly schema: ResolvedSemanticSchema;
     /** Resolve Schemas referenced by object relation paths used by this component. */
     readonly resolveSchema: (schemaId: string) => ResolvedSemanticSchema;
@@ -173,31 +206,30 @@ export interface OperatorQueryComponent {
     /** SQL-side transformations that align this component's group keys with the base component. */
     readonly groupKeyShifts?: readonly OperatorGroupKeyShift[];
 }
-export interface OperatorCteSqlContext {
-    readonly values: Readonly<Record<string, string>>;
-    readonly quoteIdentifier: (identifier: string) => string;
-}
-export interface OperatorCteComponent {
+export interface OperatorComponentQuery {
+    /** Final result-column name for this child component. */
     readonly name: string;
-    readonly component: OperatorQueryComponent;
-    /** Group output names used to join this component back to the first component. */
+    readonly logicform: LogicformType;
+    readonly prepare?: boolean;
+    readonly mapResult?: (rows: readonly DataRow[]) => DataRow[];
+    readonly groupKeyShifts?: readonly OperatorGroupKeyShift[];
+    /**
+     * Group output names used to join this component back to the first component.
+     * When omitted, the compiler joins on the groupby outputs shared by both components.
+     */
     readonly joinKeys?: readonly string[];
 }
-export interface OperatorCteCalculation {
-    readonly kind: 'cte';
-    readonly components: readonly OperatorCteComponent[];
-    readonly outputName?: string;
-    readonly toSQL: (context: OperatorCteSqlContext) => string;
-    readonly exposeComponents?: boolean;
+export interface OperatorComponentCalculation {
+    readonly components: readonly OperatorComponentQuery[];
+    /** Provider-independent formula referring to component names. */
+    readonly expression: string;
 }
 export interface OperatorJavaScriptCalculation {
     readonly kind: 'js';
-    readonly components: readonly OperatorCteComponent[];
-    readonly outputName: string;
+    readonly components: readonly OperatorComponentQuery[];
     readonly mergeRow: (values: DataRow) => unknown;
-    readonly exposeComponents?: boolean;
 }
-export type OperatorExecutionComponent = OperatorQueryComponent | OperatorCteCalculation | OperatorJavaScriptCalculation;
+export type OperatorExecutionComponent = OperatorQueryComponent | OperatorComponentCalculation | OperatorJavaScriptCalculation;
 /**
  * Extension contract for one LogicForm operator.
  *
@@ -207,10 +239,25 @@ export type OperatorExecutionComponent = OperatorQueryComponent | OperatorCteCal
  * `getOutputProperty` to describe the resulting one-column logical schema.
  */
 interface OperatorDefinitionBase {
-    /** Public registry key, normally using the `$name` convention. */
+    /** Public registry key. Built-in operators commonly use a `$` prefix, but it is not required. */
     readonly name: string;
+    /** Description of the computed metric, exposed on its result Property. */
+    readonly description?: string;
     /** Produce the normalized output name when the PredItem does not declare one. */
     readonly defaultName: (context: OperatorDefaultNameContext) => string;
+    /** Translation key for the generated name. Defaults to `operator.${name}`. */
+    readonly defaultNameKey?: string | ((context: OperatorDefaultNameContext) => string);
+    /** defaultName already used the translator and must not be translated a second time. */
+    readonly defaultNameIsLocalized?: boolean;
+    /** A grouped physical source may safely apply this operator again to stored partial results. */
+    readonly supportsGroupedSourceRollup?: boolean;
+    /** This computed operator preserves a grouped physical source's dimension semantics. */
+    readonly supportsGroupedSourceGroupby?: boolean;
+    /** Requested time grain of a grouped dimension, when this is a time grouping operator. */
+    readonly groupedSourceTimeGranularity?: (context: {
+        readonly pred: PredItemType;
+        readonly property: ResolvedSemanticProperty;
+    }) => TimeGranularity | undefined;
     /** Logical property names read in addition to the direct input property. */
     readonly dependencies?: readonly string[];
     /** Set to false for operators such as `$count` that do not require a property. */
@@ -223,11 +270,17 @@ interface OperatorDefinitionBase {
     readonly normalizePred?: (context: OperatorNormalizePredContext) => PredItemType;
     /** Build a provider-independent expression for operators with custom planning semantics. */
     readonly planExpression?: (context: OperatorPlanExpressionContext) => Expression | undefined;
-    /** Resolve observation temporal semantics for this operator, when applicable. */
-    readonly observationPolicy?: (context: OperatorObservationPolicyContext) => OperatorObservationPolicy | undefined;
+    /** Describe how this operator selects a value at a generated period boundary. */
+    readonly periodBoundaryPolicy?: (context: OperatorPeriodBoundaryPolicyContext) => OperatorPeriodBoundaryPolicy | undefined;
     /** Validate this operator against the completed group key set. */
     readonly validatePlan?: (context: OperatorValidatePlanContext) => void;
-    /** Expand high-level operator semantics into ordinary nested LogicForms before planning. */
+    /** Validate semantics that apply only when this Operator is used as a group key. */
+    readonly validateGroupby?: (context: OperatorValidateGroupbyContext) => void;
+    /** The logical planner may fully lower a component, so no executor child query is needed. */
+    readonly skipComponentExecution?: (context: OperatorHookContext & {
+        readonly plan: LogicalPlan;
+    }) => boolean;
+    /** Expand high-level operator semantics into ordinary nested LogicForm objects before planning. */
     readonly rewriteLogicform?: (context: OperatorRewriteLogicformContext) => LogicformType | undefined;
     /** Whether this operator requires one evaluation per time bucket. */
     readonly requiresPerPeriodEvaluation?: (context: OperatorPeriodEvaluationContext) => boolean;

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

@@ -1,4 +1,4 @@
-import type { CoreComputeProvider, DataRow, ProviderExecutionRequest } from './provider';
+import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest, SQLResult, DatabaseTable, TableListRequest, DescribeTableRequest, TableDescription } from './provider';
 interface ClickHouseResultLike {
     json<T>(): Promise<T>;
 }
@@ -9,18 +9,37 @@ export interface ClickHouseClientLike {
         query_params: Readonly<Record<string, unknown>>;
         abort_signal?: AbortSignal;
     }): Promise<ClickHouseResultLike>;
+    /** Native SDK exec does not append a FORMAT clause to commands. */
+    exec?(options: {
+        query: string;
+        query_params: Readonly<Record<string, unknown>>;
+        clickhouse_settings: {
+            readonly default_format: 'JSONEachRow';
+        };
+        abort_signal?: AbortSignal;
+    }): Promise<{
+        readonly stream: AsyncIterable<string | Buffer>;
+    }>;
     close(): Promise<void>;
 }
 export interface ClickHouseProviderOptions {
+    /** Full HTTP endpoint. Takes precedence over host and port. */
     readonly url?: string;
+    /** Host-style connection fields accepted by the shared datasource contract. */
+    readonly host?: string;
+    readonly port?: number;
     readonly username?: string;
+    /** Alias used by the shared datasource contract. username takes precedence. */
+    readonly user?: string;
     readonly password?: string;
     readonly database?: string;
     readonly client?: ClickHouseClientLike;
 }
 export declare class ClickHouseProvider implements CoreComputeProvider {
+    #private;
     readonly kind: "clickhouse";
-    private readonly client;
+    readonly supportsRecursiveCte = true;
+    readonly recursiveCteUnion: "UNION ALL";
     constructor(options?: ClickHouseProviderOptions);
     quoteIdentifier(identifier: string): string;
     tableAlias(expression: string, alias: string): string;
@@ -28,10 +47,15 @@ export declare class ClickHouseProvider 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;
+    castValue(expression: string, type: string): string;
+    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;
+    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): {
@@ -39,6 +63,9 @@ export declare class ClickHouseProvider implements CoreComputeProvider {
         valueExpression: string;
     };
     execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    getTableList(request: TableListRequest): Promise<DatabaseTable[]>;
+    describeTable(request: DescribeTableRequest): Promise<TableDescription>;
+    runSQL(request: ProviderExecutionRequest): Promise<SQLResult>;
     close(): Promise<void>;
 }
 export {};

package/dist/physical/connection-registry.d.ts

@@ -0,0 +1,13 @@
+import type { DatabaseConnection, ProviderRegistry } from './connection';
+import type { CoreComputeProvider } from './provider';
+type ProviderFactory = (connection: DatabaseConnection) => CoreComputeProvider;
+export declare class ConnectionRegistry {
+    #private;
+    private readonly create;
+    constructor(create?: ProviderFactory);
+    get(connection: DatabaseConnection): CoreComputeProvider;
+    close(): Promise<void>;
+}
+export declare const getConnectionProvider: (connection: DatabaseConnection, providers?: ProviderRegistry) => CoreComputeProvider;
+export declare const closeConnections: () => Promise<void>;
+export {};

package/dist/physical/connection.d.ts

@@ -1,32 +1,74 @@
 import type { CoreComputeProvider } from './provider';
 import type { ClickHouseProviderOptions } from './clickhouse-provider';
-import type { DorisProviderOptions } from './doris-provider';
-import type { MySQLProviderOptions } from './mysql-provider';
-import type { OracleProviderOptions } from './oracle-provider';
-import type { PostgreSQLProviderOptions } from './postgresql-provider';
-import type { SnowflakeProviderOptions } from './snowflake-provider';
-import type { StarRocksProviderOptions } from './starrocks-provider';
-/** Connection information supplied by an application. Provider instances stay internal. */
-export type DatabaseConnection = ({
+import type { DatabricksConnectionOptions } from './databricks-provider';
+import type { DamengConnectionOptions } from './dameng-provider';
+import type { DorisConnectionOptions } from './doris-provider';
+import type { GBaseConnectionOptions } from './gbase-provider';
+import type { MaxComputeConnectionOptions } from './maxcompute-provider';
+import type { MySQLConnectionOptions } from './mysql-provider';
+import type { OracleConnectionOptions } from './oracle-provider';
+import type { PostgreSQLConnectionOptions } from './postgresql-provider';
+import type { SnowflakeConnectionOptions } from './snowflake-provider';
+import type { SQLServerConnectionOptions } from './sqlserver-provider';
+import type { StarRocksConnectionOptions } from './starrocks-provider';
+export interface DatabaseConnectionBase {
+    readonly id: string;
+    readonly kind: string;
+}
+/** Module-augmentation seam for application-owned connection kinds. */
+export interface DatabaseConnectionExtensions {
+}
+export type BuiltinDatabaseConnection = ({
     readonly id: string;
     readonly kind: 'mysql';
-} & NonNullable<MySQLProviderOptions['connection']>) | ({
+} & MySQLConnectionOptions) | ({
     readonly id: string;
     readonly kind: 'doris';
-} & NonNullable<DorisProviderOptions['connection']>) | ({
+} & DorisConnectionOptions) | ({
+    readonly id: string;
+    readonly kind: 'gbase';
+} & GBaseConnectionOptions) | ({
     readonly id: string;
     readonly kind: 'starrocks';
-} & NonNullable<StarRocksProviderOptions['connection']>) | ({
+} & StarRocksConnectionOptions) | ({
+    readonly id: string;
+    readonly kind: 'maxcompute';
+} & MaxComputeConnectionOptions) | ({
     readonly id: string;
     readonly kind: 'postgresql';
-} & NonNullable<PostgreSQLProviderOptions['connection']>) | ({
+} & PostgreSQLConnectionOptions) | ({
     readonly id: string;
     readonly kind: 'clickhouse';
 } & Omit<ClickHouseProviderOptions, 'client'>) | ({
+    readonly id: string;
+    readonly kind: 'databricks';
+} & DatabricksConnectionOptions) | ({
+    readonly id: string;
+    readonly kind: 'dameng';
+} & DamengConnectionOptions) | ({
     readonly id: string;
     readonly kind: 'snowflake';
-} & NonNullable<SnowflakeProviderOptions['connection']>) | ({
+} & SnowflakeConnectionOptions) | ({
+    readonly id: string;
+    readonly kind: 'sqlserver';
+} & SQLServerConnectionOptions) | ({
     readonly id: string;
     readonly kind: 'oracle';
-} & NonNullable<OracleProviderOptions['connection']>);
-export declare const createProvider: (connection: DatabaseConnection) => CoreComputeProvider;
+} & OracleConnectionOptions);
+type ExtendedDatabaseConnection = DatabaseConnectionExtensions[keyof DatabaseConnectionExtensions];
+export type DatabaseConnection = BuiltinDatabaseConnection | ExtendedDatabaseConnection;
+export interface ProviderDefinition<Connection extends DatabaseConnectionBase = DatabaseConnectionBase> {
+    readonly kind: Connection['kind'];
+    readonly create: (connection: Connection) => CoreComputeProvider;
+}
+export declare const builtinProviderDefinitions: readonly ProviderDefinition[];
+export declare class ProviderRegistry {
+    #private;
+    constructor(definitions?: readonly ProviderDefinition[]);
+    register<Connection extends DatabaseConnectionBase>(definition: ProviderDefinition<Connection>): this;
+    create(connection: DatabaseConnectionBase): CoreComputeProvider;
+    has(kind: string): boolean;
+}
+export declare const defaultProviderRegistry: ProviderRegistry;
+export declare const createProvider: (connection: DatabaseConnection, providers?: ProviderRegistry) => CoreComputeProvider;
+export {};