react-semaphor 0.1.337 → 0.1.339

package/dist/types/data-app-builder.d.ts

@@ -480,19 +480,32 @@ export declare type GeneratedRevision = {
 
 export declare type ReasoningEffort = 'low' | 'medium' | 'high';
 
-declare type SemaphorAnalyticsFilter = {
+declare type SemaphorAnalyticsFilter = SemaphorAnalyticsValueFilter | SemaphorAnalyticsNullFilter;
+
+declare type SemaphorAnalyticsFilterBase = {
     id?: string;
     field: SemaphorFieldRef;
-    operator?: SemaphorAnalyticsFilterOperator;
-    value?: unknown;
-    values?: unknown[];
 };
 
 declare type SemaphorAnalyticsFilterOperator = SemaphorInputOperator | 'not_contains' | 'is_null' | 'is_not_null';
 
 declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent;
 
-declare type SemaphorDialect = 'semantic' | 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
+declare type SemaphorAnalyticsNullFilter = SemaphorAnalyticsFilterBase & {
+    operator: SemaphorAnalyticsNullFilterOperator;
+    values?: never;
+};
+
+declare type SemaphorAnalyticsNullFilterOperator = 'is_null' | 'is_not_null';
+
+declare type SemaphorAnalyticsValueFilter = SemaphorAnalyticsFilterBase & {
+    operator?: SemaphorAnalyticsValueFilterOperator;
+    values: unknown[];
+};
+
+declare type SemaphorAnalyticsValueFilterOperator = Exclude<SemaphorAnalyticsFilterOperator, 'is_null' | 'is_not_null'>;
+
+declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
 declare type SemaphorFieldRef = {
     name: string;
@@ -532,9 +545,8 @@ declare type SemaphorMetricIntent = {
     version?: SemaphorProtocolVersion;
     id?: string;
     source: SemaphorSourceRef;
-    metrics: string[];
-    primaryMetric?: string;
-    metricRefs?: SemaphorFieldRef[];
+    metrics: SemaphorFieldRef[];
+    primaryMetric?: SemaphorFieldRef;
     label?: string;
     dateField?: SemaphorFieldRef;
     timeGrain?: SemaphorTimeGrain;
@@ -559,12 +571,11 @@ declare type SemaphorRecordsIntent = {
     id?: string;
     label?: string;
     fields: SemaphorFieldRef[];
-    measures?: string[];
     dateField?: SemaphorFieldRef;
     timeGrain?: SemaphorTimeGrain;
     limit?: number;
     orderBy?: {
-        field: string;
+        field: SemaphorFieldRef;
         direction: 'asc' | 'desc';
     };
     inputs?: SemaphorInputBinding[];
@@ -589,7 +600,6 @@ declare type SemaphorSourceRef = {
 } | {
     kind: 'sql';
     connectionId: string;
-    sql: string;
     dialect?: SemaphorDialect;
     label?: string;
 };
@@ -600,9 +610,9 @@ declare type SemaphorSqlIntent = {
     id?: string;
     label?: string;
     source: Extract<SemaphorSourceRef, {
-        kind: 'sql' | 'physical';
+        kind: 'sql';
     }>;
-    sql?: string;
+    sql: string;
     parameters?: Record<string, unknown>;
     pythonCode?: string;
     limit?: number;

package/dist/types/data-app-sdk.d.ts

@@ -16,18 +16,31 @@ export declare function normalizeSemaphorInputOptions(options?: Array<{
 
 export declare function readWindowRuntime(): SemaphorDataAppWindowRuntime | undefined;
 
-declare type SemaphorAnalyticsFilter = {
+declare type SemaphorAnalyticsFilter = SemaphorAnalyticsValueFilter | SemaphorAnalyticsNullFilter;
+
+declare type SemaphorAnalyticsFilterBase = {
     id?: string;
     field: SemaphorFieldRef;
-    operator?: SemaphorAnalyticsFilterOperator;
-    value?: unknown;
-    values?: unknown[];
 };
 
 declare type SemaphorAnalyticsFilterOperator = SemaphorInputOperator | 'not_contains' | 'is_null' | 'is_not_null';
 
 declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent;
 
+declare type SemaphorAnalyticsNullFilter = SemaphorAnalyticsFilterBase & {
+    operator: SemaphorAnalyticsNullFilterOperator;
+    values?: never;
+};
+
+declare type SemaphorAnalyticsNullFilterOperator = 'is_null' | 'is_not_null';
+
+declare type SemaphorAnalyticsValueFilter = SemaphorAnalyticsFilterBase & {
+    operator?: SemaphorAnalyticsValueFilterOperator;
+    values: unknown[];
+};
+
+declare type SemaphorAnalyticsValueFilterOperator = Exclude<SemaphorAnalyticsFilterOperator, 'is_null' | 'is_not_null'>;
+
 export declare const SemaphorDataAppContext: Context<SemaphorDataAppRuntime>;
 
 export declare type SemaphorDataAppControlInputSpec<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue> = SemaphorDataAppInputBase<TValue> & {
@@ -51,14 +64,13 @@ export declare type SemaphorDataAppExecutorContext = {
     activeInputs?: SemaphorDataAppInputSnapshot[];
 };
 
-export declare type SemaphorDataAppFieldSpec = string | SemaphorFieldRef;
+export declare type SemaphorDataAppFieldSpec = SemaphorFieldRef;
 
 export declare type SemaphorDataAppFilterInputSpec<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue> = SemaphorDataAppInputBase<TValue> & {
     kind: 'filter';
     field: SemaphorDataAppFieldSpec;
     operator?: SemaphorInputOperator;
     multi?: boolean;
-    source?: SemaphorSourceRef;
 };
 
 declare type SemaphorDataAppInputBase<TValue extends SemaphorDataAppInputValue> = {
@@ -76,7 +88,6 @@ export declare type SemaphorDataAppInputHandle<TValue extends SemaphorDataAppInp
     label?: string;
     field?: SemaphorFieldRef;
     operator?: SemaphorInputOperator;
-    source?: SemaphorSourceRef;
     controlRole?: SemaphorDataAppControlRole;
     value: TValue | undefined;
     options: SemaphorDataAppInputOption[];
@@ -119,7 +130,6 @@ export declare type SemaphorDataAppInputSnapshot<TValue extends SemaphorDataAppI
     value?: TValue;
     isActive: boolean;
     operator?: SemaphorInputOperator;
-    source?: SemaphorSourceRef;
     controlRole?: SemaphorDataAppControlRole;
 };
 
@@ -127,7 +137,7 @@ export declare type SemaphorDataAppInputSpec<TValue extends SemaphorDataAppInput
 
 export declare type SemaphorDataAppInputValue = SemaphorDataAppScalar | SemaphorDataAppScalar[];
 
-export declare type SemaphorDataAppMetricComparison = 'none' | 'previous_period' | 'same_period_last_year' | 'previous_year' | {
+export declare type SemaphorDataAppMetricComparison = {
     kind: 'previous_period' | 'previous_year' | 'target';
     targetValue?: number;
 };
@@ -149,8 +159,8 @@ export declare type SemaphorDataAppMetricResult = SemaphorDataAppQueryState & Se
 export declare type SemaphorDataAppMetricSpec = SemaphorDataAppSourceSpec & {
     id?: string;
     label?: string;
-    metrics: SemaphorDataAppNonEmptyArray<string>;
-    primaryMetric?: string;
+    metrics: SemaphorDataAppNonEmptyArray<SemaphorDataAppFieldSpec>;
+    primaryMetric?: SemaphorDataAppFieldSpec;
     dateField?: SemaphorDataAppFieldSpec;
     timeGrain?: SemaphorTimeGrain;
     dimensions?: SemaphorDataAppFieldSpec[];
@@ -199,8 +209,12 @@ export declare type SemaphorDataAppRecordsData<TRecord extends Record<string, un
     rowCount?: number;
 };
 
+export declare type SemaphorDataAppRecordsFieldSpec = SemaphorFieldRef & {
+    role: NonNullable<SemaphorFieldRef['role']>;
+};
+
 export declare type SemaphorDataAppRecordsOrderBy = {
-    field: string;
+    field: SemaphorDataAppFieldSpec;
     direction: 'asc' | 'desc';
 };
 
@@ -210,17 +224,7 @@ export declare type SemaphorDataAppRecordsResult<TRecord extends Record<string,
 };
 
 declare type SemaphorDataAppRecordsSelectorSpec = {
-    fields: SemaphorDataAppNonEmptyArray<SemaphorDataAppFieldSpec>;
-    dimensions?: SemaphorDataAppFieldSpec[];
-    measures?: string[];
-} | {
-    fields?: SemaphorDataAppFieldSpec[];
-    dimensions: SemaphorDataAppNonEmptyArray<SemaphorDataAppFieldSpec>;
-    measures?: string[];
-} | {
-    fields?: SemaphorDataAppFieldSpec[];
-    dimensions?: SemaphorDataAppFieldSpec[];
-    measures: SemaphorDataAppNonEmptyArray<string>;
+    fields: SemaphorDataAppNonEmptyArray<SemaphorDataAppRecordsFieldSpec>;
 };
 
 export declare type SemaphorDataAppRecordsSpec = SemaphorDataAppRecordsBaseSpec & SemaphorDataAppRecordsSelectorSpec;
@@ -233,19 +237,6 @@ export declare type SemaphorDataAppScalar = string | number | boolean | null;
 
 export declare type SemaphorDataAppSourceSpec = {
     source: SemaphorSourceRef;
-    domainId?: never;
-    dataset?: never;
-    datasetName?: never;
-    datasetId?: never;
-    connectionId?: never;
-} | {
-    source?: never;
-    domainId: string;
-    dataset?: string;
-    datasetName?: string;
-    datasetId?: string;
-    connectionId?: string;
-    sourceLabel?: string;
 };
 
 declare type SemaphorDataAppWindowRuntime = {
@@ -256,7 +247,7 @@ declare type SemaphorDataAppWindowRuntime = {
     };
 };
 
-declare type SemaphorDialect = 'semantic' | 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
+declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
 declare type SemaphorFieldRef = {
     name: string;
@@ -296,9 +287,8 @@ declare type SemaphorMetricIntent = {
     version?: SemaphorProtocolVersion;
     id?: string;
     source: SemaphorSourceRef;
-    metrics: string[];
-    primaryMetric?: string;
-    metricRefs?: SemaphorFieldRef[];
+    metrics: SemaphorFieldRef[];
+    primaryMetric?: SemaphorFieldRef;
     label?: string;
     dateField?: SemaphorFieldRef;
     timeGrain?: SemaphorTimeGrain;
@@ -323,12 +313,11 @@ declare type SemaphorRecordsIntent = {
     id?: string;
     label?: string;
     fields: SemaphorFieldRef[];
-    measures?: string[];
     dateField?: SemaphorFieldRef;
     timeGrain?: SemaphorTimeGrain;
     limit?: number;
     orderBy?: {
-        field: string;
+        field: SemaphorFieldRef;
         direction: 'asc' | 'desc';
     };
     inputs?: SemaphorInputBinding[];
@@ -353,7 +342,6 @@ declare type SemaphorSourceRef = {
 } | {
     kind: 'sql';
     connectionId: string;
-    sql: string;
     dialect?: SemaphorDialect;
     label?: string;
 };
@@ -364,9 +352,9 @@ declare type SemaphorSqlIntent = {
     id?: string;
     label?: string;
     source: Extract<SemaphorSourceRef, {
-        kind: 'sql' | 'physical';
+        kind: 'sql';
     }>;
-    sql?: string;
+    sql: string;
     parameters?: Record<string, unknown>;
     pythonCode?: string;
     limit?: number;
@@ -400,7 +388,6 @@ export declare function toSemaphorInputSpec<TValue extends SemaphorDataAppInputV
     label?: string;
     field?: SemaphorFieldRef;
     operator?: SemaphorInputOperator;
-    source?: SemaphorSourceRef;
 };
 
 export declare function toSemaphorMetricIntent(spec: SemaphorDataAppMetricSpec): SemaphorMetricIntent;

package/dist/types/main.d.ts

@@ -1179,6 +1179,13 @@ export declare interface CardConfig {
     pivotByColumns?: PivotByField[];
     sortByColumns?: SortByField[];
     detailColumns?: DetailField[];
+    /**
+     * Typed source that anchors the query before auto-join materializes an
+     * executable joinPlan.baseEntity. This is distinct from
+     * DataSource.selectedEntities, which lists available datasets but does not
+     * define join-root semantics.
+     */
+    queryBaseSource?: SemaphorSourceRef;
     /** Preserves non-detail config when switching to detail tables. */
     detailTableBackup?: DetailTableBackupConfig;
     filters?: FilterGroup;
@@ -1723,21 +1730,9 @@ declare type DashboardAIContext = AIContext & {
 
 declare type DashboardAIContextMode = 'auto' | 'fixed';
 
-declare type DashboardAuthoringDatasetRef = {
-    kind: 'semantic';
-    domainId: string;
-    datasetName: string;
-    datasetId?: string;
-    label?: string;
-    connectionId?: string;
-} | {
-    kind: 'physical';
-    connectionId: string;
-    databaseName?: string;
-    schemaName?: string;
-    tableName: string;
-    label?: string;
-};
+declare type DashboardAuthoringDatasetRef = Extract<SemaphorSourceRef, {
+    kind: 'semantic' | 'physical';
+}>;
 
 export declare type DashboardAuthoringSource = DashboardAuthoringDatasetRef & {
     domainName?: string;
@@ -1772,24 +1767,6 @@ export declare type DashboardBriefingLauncherProps = {
     client?: Partial<DashboardBriefingLauncherClient>;
 };
 
-declare type DashboardCardQueryFieldRef = {
-    name: string;
-    source?: DashboardAuthoringDatasetRef;
-};
-
-declare type DashboardCardQueryIntent = {
-    metrics?: string[];
-    primaryMetric?: string;
-    metricRefs?: DashboardCardQueryFieldRef[];
-    dateField?: string;
-    dateFieldRef?: DashboardCardQueryFieldRef;
-    timeGrain?: 'day' | 'week' | 'month' | 'quarter' | 'year';
-    dimensions?: string[];
-    dimensionRefs?: DashboardCardQueryFieldRef[];
-    filters?: SemaphorAnalyticsFilter[];
-    limit?: number;
-};
-
 declare type DashboardCardSizeIntent = 'kpi' | 'chart' | 'table' | 'text';
 
 declare type DashboardControlsModelOptions = {
@@ -2032,7 +2009,7 @@ declare type DashboardPlan = {
     id: string;
     title: string;
     description?: string;
-    datasets: DashboardAuthoringDatasetRef[];
+    datasets: SemaphorSourceRef[];
     sheets: DashboardPlanSheet[];
     filterInputs?: DashboardPlanFilterInput[];
     calculatedFields?: DashboardPlanCalculatedField[];
@@ -2060,7 +2037,6 @@ declare type DashboardPlanCard = {
     role: DashboardCardSizeIntent;
     priority: number;
     section?: string;
-    query?: DashboardCardQueryIntent;
     analyticsIntent?: SemaphorAnalyticsIntent;
     text?: string;
 };
@@ -2076,7 +2052,7 @@ declare type DashboardPlanFilterInput = {
 
 declare type DashboardPlanRequest = {
     prompt: string;
-    dataset: DashboardAuthoringDatasetRef;
+    dataset: SemaphorSourceRef;
 } | {
     prompt: string;
     domainId: string;
@@ -2298,7 +2274,7 @@ declare type DashboardSuggestion = {
 declare type DashboardSuggestionPreviewKind = 'kpi' | 'line' | 'bar' | 'donut' | 'table';
 
 declare type DashboardSuggestionRequest = {
-    dataset: DashboardAuthoringDatasetRef;
+    dataset: SemaphorSourceRef;
     instruction?: string;
 } | {
     domainId: string;
@@ -4417,24 +4393,37 @@ declare type SemanticExecutionPayload = {
     }>;
 };
 
-declare type SemaphorAnalyticsFilter = {
+declare type SemaphorAnalyticsFilter = SemaphorAnalyticsValueFilter | SemaphorAnalyticsNullFilter;
+
+declare type SemaphorAnalyticsFilterBase = {
     id?: string;
     field: SemaphorFieldRef;
-    operator?: SemaphorAnalyticsFilterOperator;
-    value?: unknown;
-    values?: unknown[];
 };
 
 declare type SemaphorAnalyticsFilterOperator = SemaphorInputOperator | 'not_contains' | 'is_null' | 'is_not_null';
 
 declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent;
 
+declare type SemaphorAnalyticsNullFilter = SemaphorAnalyticsFilterBase & {
+    operator: SemaphorAnalyticsNullFilterOperator;
+    values?: never;
+};
+
+declare type SemaphorAnalyticsNullFilterOperator = 'is_null' | 'is_not_null';
+
+declare type SemaphorAnalyticsValueFilter = SemaphorAnalyticsFilterBase & {
+    operator?: SemaphorAnalyticsValueFilterOperator;
+    values: unknown[];
+};
+
+declare type SemaphorAnalyticsValueFilterOperator = Exclude<SemaphorAnalyticsFilterOperator, 'is_null' | 'is_not_null'>;
+
 export declare const SemaphorContextProvider: ({ children, dashboardProps, }: {
     children: React.ReactNode;
     dashboardProps: DashboardProps;
 }) => JSX.Element;
 
-declare type SemaphorDialect = 'semantic' | 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
+declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
 declare type SemaphorFieldRef = {
     name: string;
@@ -4474,9 +4463,8 @@ declare type SemaphorMetricIntent = {
     version?: SemaphorProtocolVersion;
     id?: string;
     source: SemaphorSourceRef;
-    metrics: string[];
-    primaryMetric?: string;
-    metricRefs?: SemaphorFieldRef[];
+    metrics: SemaphorFieldRef[];
+    primaryMetric?: SemaphorFieldRef;
     label?: string;
     dateField?: SemaphorFieldRef;
     timeGrain?: SemaphorTimeGrain;
@@ -4507,12 +4495,11 @@ declare type SemaphorRecordsIntent = {
     id?: string;
     label?: string;
     fields: SemaphorFieldRef[];
-    measures?: string[];
     dateField?: SemaphorFieldRef;
     timeGrain?: SemaphorTimeGrain;
     limit?: number;
     orderBy?: {
-        field: string;
+        field: SemaphorFieldRef;
         direction: 'asc' | 'desc';
     };
     inputs?: SemaphorInputBinding[];
@@ -4537,7 +4524,6 @@ declare type SemaphorSourceRef = {
 } | {
     kind: 'sql';
     connectionId: string;
-    sql: string;
     dialect?: SemaphorDialect;
     label?: string;
 };
@@ -4548,9 +4534,9 @@ declare type SemaphorSqlIntent = {
     id?: string;
     label?: string;
     source: Extract<SemaphorSourceRef, {
-        kind: 'sql' | 'physical';
+        kind: 'sql';
     }>;
-    sql?: string;
+    sql: string;
     parameters?: Record<string, unknown>;
     pythonCode?: string;
     limit?: number;
@@ -6418,7 +6404,7 @@ export declare function useTextFilterHook(filterId: string): {
     activeFilterValue: TFilterValue | undefined;
     isSearching: boolean;
     searchError: boolean;
-    resultSource: "server" | "both" | "local";
+    resultSource: "both" | "server" | "local";
 };
 
 export declare function validateBriefingFormDraft(draft: BriefingFormDraft): BriefingFormValidationResult;

package/dist/types/shared.d.ts

@@ -119,6 +119,13 @@ declare interface CardConfig {
     pivotByColumns?: PivotByField[];
     sortByColumns?: SortByField[];
     detailColumns?: DetailField[];
+    /**
+     * Typed source that anchors the query before auto-join materializes an
+     * executable joinPlan.baseEntity. This is distinct from
+     * DataSource.selectedEntities, which lists available datasets but does not
+     * define join-root semantics.
+     */
+    queryBaseSource?: SemaphorSourceRef;
     /** Preserves non-detail config when switching to detail tables. */
     detailTableBackup?: DetailTableBackupConfig;
     filters?: FilterGroup;
@@ -1548,6 +1555,31 @@ declare type SelectedEntities = SelectedEntity[];
 
 declare type SelectedEntity = DatabaseEntityReference | DataModelEntityReference | DatasetEntityReference | FileEntityReference;
 
+declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
+
+declare type SemaphorSourceRef = {
+    kind: 'semantic';
+    domainId: string;
+    datasetName: string;
+    datasetId?: string;
+    label?: string;
+    connectionId?: string;
+} | {
+    kind: 'physical';
+    connectionId: string;
+    connectionType?: string;
+    tableName: string;
+    databaseName?: string;
+    schemaName?: string;
+    label?: string;
+    dialect?: SemaphorDialect;
+} | {
+    kind: 'sql';
+    connectionId: string;
+    dialect?: SemaphorDialect;
+    label?: string;
+};
+
 /**
  * Stable serializer for dashboard dirty checks.
  * This consolidates normalization + serialization into one call site, so

package/dist/types/surfboard.d.ts

@@ -211,6 +211,13 @@ declare interface CardConfig {
     pivotByColumns?: PivotByField[];
     sortByColumns?: SortByField[];
     detailColumns?: DetailField[];
+    /**
+     * Typed source that anchors the query before auto-join materializes an
+     * executable joinPlan.baseEntity. This is distinct from
+     * DataSource.selectedEntities, which lists available datasets but does not
+     * define join-root semantics.
+     */
+    queryBaseSource?: SemaphorSourceRef;
     /** Preserves non-detail config when switching to detail tables. */
     detailTableBackup?: DetailTableBackupConfig;
     filters?: FilterGroup;
@@ -1908,6 +1915,31 @@ declare type SemanticExecutionPayload = {
     }>;
 };
 
+declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
+
+declare type SemaphorSourceRef = {
+    kind: 'semantic';
+    domainId: string;
+    datasetName: string;
+    datasetId?: string;
+    label?: string;
+    connectionId?: string;
+} | {
+    kind: 'physical';
+    connectionId: string;
+    connectionType?: string;
+    tableName: string;
+    databaseName?: string;
+    schemaName?: string;
+    label?: string;
+    dialect?: SemaphorDialect;
+} | {
+    kind: 'sql';
+    connectionId: string;
+    dialect?: SemaphorDialect;
+    label?: string;
+};
+
 declare interface SortByField extends Field {
     role: 'sortby';
     direction: 'asc' | 'desc';

package/dist/types/types.d.ts

@@ -653,6 +653,13 @@ export declare interface CardConfig {
     pivotByColumns?: PivotByField[];
     sortByColumns?: SortByField[];
     detailColumns?: DetailField[];
+    /**
+     * Typed source that anchors the query before auto-join materializes an
+     * executable joinPlan.baseEntity. This is distinct from
+     * DataSource.selectedEntities, which lists available datasets but does not
+     * define join-root semantics.
+     */
+    queryBaseSource?: SemaphorSourceRef;
     /** Preserves non-detail config when switching to detail tables. */
     detailTableBackup?: DetailTableBackupConfig;
     filters?: FilterGroup;
@@ -2668,6 +2675,31 @@ declare type SemanticExecutionPayload = {
     }>;
 };
 
+declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
+
+declare type SemaphorSourceRef = {
+    kind: 'semantic';
+    domainId: string;
+    datasetName: string;
+    datasetId?: string;
+    label?: string;
+    connectionId?: string;
+} | {
+    kind: 'physical';
+    connectionId: string;
+    connectionType?: string;
+    tableName: string;
+    databaseName?: string;
+    schemaName?: string;
+    label?: string;
+    dialect?: SemaphorDialect;
+} | {
+    kind: 'sql';
+    connectionId: string;
+    dialect?: SemaphorDialect;
+    label?: string;
+};
+
 export declare interface SortByField extends Field {
     role: 'sortby';
     direction: 'asc' | 'desc';

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.337",
+  "version": "0.1.339",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",