react-semaphor 0.1.370 → 0.1.371

package/dist/types/dashboard-assistant.d.ts

@@ -2,8 +2,14 @@ declare type AggregateFunction = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'MEDI
 
 /**
  * Formula metadata for calculated fields (UI-only metadata)
- * This is supplementary data to help the UI display and edit calculated fields.
- * The `expression` field remains the source of truth for the backend.
+ * This is supplementary runtime/compiler data to help dashboard UI display,
+ * edit, and execute calculated fields.
+ *
+ * Public source-level calculation metadata belongs in `Field.derivedField`
+ * (`SemaphorDerivedFieldDefinition`). `calculatedFormula` deliberately uses
+ * indexed `{field_N}` tokens and full runtime Field objects so current dashboard
+ * query execution can resolve aliases, joins, filters, and aggregates without
+ * doing catalog lookups.
  *
  * IMPORTANT: This metadata is ALWAYS updated atomically with the expression field.
  * Both are generated together from the same dialog inputs, preventing drift.
@@ -389,6 +395,15 @@ declare interface Field {
     role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
+    /**
+     * Public, source-level derived-field metadata for semantic/domain-authored
+     * calculations. This is the AI/MCP/Data App-facing contract: named-token
+     * expression, typed inputs, result role, and compute stage.
+     *
+     * Dashboard-local calculated fields may omit this because they are local
+     * runtime artifacts rather than semantic-domain definitions.
+     */
+    derivedField?: SemaphorDerivedFieldDefinition;
     format?: FormatSpec;
     aggregate?: AggregateFunction;
     fieldScope?: FieldScope;
@@ -1017,12 +1032,51 @@ declare type SemaphorCompiledQuery = {
     analyticsIntent?: SemaphorAnalyticsIntent;
 };
 
+declare type SemaphorDerivedFieldAggregationBehavior = 'additive' | 'non_additive' | 'ratio_of_sums' | 'weighted' | 'pre_aggregated' | 'snapshot';
+
+declare type SemaphorDerivedFieldAggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
+
+declare type SemaphorDerivedFieldComputeStage = 'row' | 'aggregate';
+
+declare type SemaphorDerivedFieldDefinition = {
+    kind: 'derived_field';
+    name: string;
+    label: string;
+    description?: string;
+    resultRole: SemaphorDerivedFieldResultRole;
+    dataType: NonNullable<SemaphorFieldRef['dataType']>;
+    computeStage: SemaphorDerivedFieldComputeStage;
+    expression: string;
+    expressionLanguage?: 'semaphor_sql_template';
+    inputs: Record<string, SemaphorDerivedFieldInput>;
+    defaultAggregate?: SemaphorAggregateFunction;
+    aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
+    aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
+    format?: unknown;
+    tags?: string[];
+};
+
+declare type SemaphorDerivedFieldInput = {
+    kind: 'field';
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+} | {
+    kind: 'metric';
+    metric: SemaphorFieldRef;
+} | {
+    kind: 'dimension';
+    dimension: SemaphorFieldRef;
+};
+
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'group' | 'date' | 'id' | 'filter';
+
 declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
 declare type SemaphorExecutionFieldRef = SemaphorFieldRef & {
     semanticAggregate?: SemaphorAggregateFunction;
     effectiveAggregate?: SemaphorAggregateFunction;
     aggregateSource?: SemaphorMetricAggregateSource;
+    derivedField?: SemaphorDerivedFieldDefinition;
 };
 
 /**
@@ -1061,6 +1115,7 @@ declare type SemaphorInputOptionsIntent = {
     field: SemaphorFieldRef;
     search?: string;
     limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 declare type SemaphorInputOptionsResult = SemaphorAnalyticsResultBase & {
@@ -1256,6 +1311,7 @@ declare type SemaphorMetricIntent = {
     };
     inputs?: SemaphorInputBinding[];
     limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 declare type SemaphorMetricResult = SemaphorAnalyticsResultBase & {
@@ -1311,6 +1367,7 @@ declare type SemaphorRecordsIntent = {
         direction: 'asc' | 'desc';
     };
     inputs?: SemaphorInputBinding[];
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 declare type SemaphorRecordsResult = SemaphorAnalyticsResultBase & {
@@ -1366,6 +1423,7 @@ declare type SemaphorResultColumn = {
     dataType?: SemaphorFieldRef['dataType'];
     aggregate?: SemaphorFieldRef['aggregate'];
     source?: SemaphorFieldRef['source'];
+    derivedField?: SemaphorDerivedFieldDefinition;
 };
 
 declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {

package/dist/types/dashboard-authoring.d.ts

@@ -81,8 +81,14 @@ declare type CacheConfig = {
 
 /**
  * Formula metadata for calculated fields (UI-only metadata)
- * This is supplementary data to help the UI display and edit calculated fields.
- * The `expression` field remains the source of truth for the backend.
+ * This is supplementary runtime/compiler data to help dashboard UI display,
+ * edit, and execute calculated fields.
+ *
+ * Public source-level calculation metadata belongs in `Field.derivedField`
+ * (`SemaphorDerivedFieldDefinition`). `calculatedFormula` deliberately uses
+ * indexed `{field_N}` tokens and full runtime Field objects so current dashboard
+ * query execution can resolve aliases, joins, filters, and aggregates without
+ * doing catalog lookups.
  *
  * IMPORTANT: This metadata is ALWAYS updated atomically with the expression field.
  * Both are generated together from the same dialog inputs, preventing drift.
@@ -1251,6 +1257,15 @@ declare interface Field {
     role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
+    /**
+     * Public, source-level derived-field metadata for semantic/domain-authored
+     * calculations. This is the AI/MCP/Data App-facing contract: named-token
+     * expression, typed inputs, result role, and compute stage.
+     *
+     * Dashboard-local calculated fields may omit this because they are local
+     * runtime artifacts rather than semantic-domain definitions.
+     */
+    derivedField?: SemaphorDerivedFieldDefinition;
     format?: FormatSpec;
     aggregate?: AggregateFunction;
     fieldScope?: FieldScope;
@@ -1869,6 +1884,44 @@ declare type SemaphorDashboardViewIntent = {
     text?: string;
 };
 
+declare type SemaphorDerivedFieldAggregationBehavior = 'additive' | 'non_additive' | 'ratio_of_sums' | 'weighted' | 'pre_aggregated' | 'snapshot';
+
+declare type SemaphorDerivedFieldAggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
+
+declare type SemaphorDerivedFieldComputeStage = 'row' | 'aggregate';
+
+declare type SemaphorDerivedFieldDefinition = {
+    kind: 'derived_field';
+    name: string;
+    label: string;
+    description?: string;
+    resultRole: SemaphorDerivedFieldResultRole;
+    dataType: NonNullable<SemaphorFieldRef['dataType']>;
+    computeStage: SemaphorDerivedFieldComputeStage;
+    expression: string;
+    expressionLanguage?: 'semaphor_sql_template';
+    inputs: Record<string, SemaphorDerivedFieldInput>;
+    defaultAggregate?: SemaphorAggregateFunction;
+    aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
+    aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
+    format?: unknown;
+    tags?: string[];
+};
+
+declare type SemaphorDerivedFieldInput = {
+    kind: 'field';
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+} | {
+    kind: 'metric';
+    metric: SemaphorFieldRef;
+} | {
+    kind: 'dimension';
+    dimension: SemaphorFieldRef;
+};
+
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'group' | 'date' | 'id' | 'filter';
+
 declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
 /**
@@ -1911,6 +1964,7 @@ declare type SemaphorInputOptionsIntent = {
     field: SemaphorFieldRef;
     search?: string;
     limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 declare type SemaphorInputScope = {
@@ -2110,6 +2164,7 @@ declare type SemaphorMetricIntent = {
     };
     inputs?: SemaphorInputBinding[];
     limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 declare type SemaphorPaginationRequest = {
@@ -2137,6 +2192,7 @@ declare type SemaphorRecordsIntent = {
         direction: 'asc' | 'desc';
     };
     inputs?: SemaphorInputBinding[];
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 declare type SemaphorRelativeTimeWindow = {

package/dist/types/dashboard.d.ts

@@ -158,8 +158,14 @@ export declare type CacheConfig = {
 
 /**
  * Formula metadata for calculated fields (UI-only metadata)
- * This is supplementary data to help the UI display and edit calculated fields.
- * The `expression` field remains the source of truth for the backend.
+ * This is supplementary runtime/compiler data to help dashboard UI display,
+ * edit, and execute calculated fields.
+ *
+ * Public source-level calculation metadata belongs in `Field.derivedField`
+ * (`SemaphorDerivedFieldDefinition`). `calculatedFormula` deliberately uses
+ * indexed `{field_N}` tokens and full runtime Field objects so current dashboard
+ * query execution can resolve aliases, joins, filters, and aggregates without
+ * doing catalog lookups.
  *
  * IMPORTANT: This metadata is ALWAYS updated atomically with the expression field.
  * Both are generated together from the same dialog inputs, preventing drift.
@@ -1288,6 +1294,15 @@ declare interface Field {
     role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
+    /**
+     * Public, source-level derived-field metadata for semantic/domain-authored
+     * calculations. This is the AI/MCP/Data App-facing contract: named-token
+     * expression, typed inputs, result role, and compute stage.
+     *
+     * Dashboard-local calculated fields may omit this because they are local
+     * runtime artifacts rather than semantic-domain definitions.
+     */
+    derivedField?: SemaphorDerivedFieldDefinition;
     format?: FormatSpec;
     aggregate?: AggregateFunction;
     fieldScope?: FieldScope;
@@ -1907,8 +1922,57 @@ declare type SemanticExecutionPayload = {
     }>;
 };
 
+declare type SemaphorAggregateFunction = 'SUM' | 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'MEDIAN' | 'DISTINCT';
+
+declare type SemaphorDerivedFieldAggregationBehavior = 'additive' | 'non_additive' | 'ratio_of_sums' | 'weighted' | 'pre_aggregated' | 'snapshot';
+
+declare type SemaphorDerivedFieldAggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
+
+declare type SemaphorDerivedFieldComputeStage = 'row' | 'aggregate';
+
+declare type SemaphorDerivedFieldDefinition = {
+    kind: 'derived_field';
+    name: string;
+    label: string;
+    description?: string;
+    resultRole: SemaphorDerivedFieldResultRole;
+    dataType: NonNullable<SemaphorFieldRef['dataType']>;
+    computeStage: SemaphorDerivedFieldComputeStage;
+    expression: string;
+    expressionLanguage?: 'semaphor_sql_template';
+    inputs: Record<string, SemaphorDerivedFieldInput>;
+    defaultAggregate?: SemaphorAggregateFunction;
+    aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
+    aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
+    format?: unknown;
+    tags?: string[];
+};
+
+declare type SemaphorDerivedFieldInput = {
+    kind: 'field';
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+} | {
+    kind: 'metric';
+    metric: SemaphorFieldRef;
+} | {
+    kind: 'dimension';
+    dimension: SemaphorFieldRef;
+};
+
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'group' | 'date' | 'id' | 'filter';
+
 declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
+declare type SemaphorFieldRef = {
+    name: string;
+    label?: string;
+    role?: 'dimension' | 'measure' | 'date' | 'id' | 'unknown';
+    dataType?: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'unknown';
+    source?: SemaphorSourceRef;
+    aggregate?: SemaphorAggregateFunction;
+};
+
 declare type SemaphorSourceRef = {
     kind: 'semantic';
     domainId: string;
@@ -2566,6 +2630,7 @@ export declare type TDataColumn = {
     role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
+    derivedField?: SemaphorDerivedFieldDefinition;
     format?: FormatSpec;
     sourceField?: string;
     aggregate?: AggregateFunction;

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

@@ -580,6 +580,44 @@ declare type SemaphorAnalyticsValueFilter = SemaphorAnalyticsFilterBase & {
 
 declare type SemaphorAnalyticsValueFilterOperator = Exclude<SemaphorAnalyticsFilterOperator, 'is_null' | 'is_not_null'>;
 
+declare type SemaphorDerivedFieldAggregationBehavior = 'additive' | 'non_additive' | 'ratio_of_sums' | 'weighted' | 'pre_aggregated' | 'snapshot';
+
+declare type SemaphorDerivedFieldAggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
+
+declare type SemaphorDerivedFieldComputeStage = 'row' | 'aggregate';
+
+declare type SemaphorDerivedFieldDefinition = {
+    kind: 'derived_field';
+    name: string;
+    label: string;
+    description?: string;
+    resultRole: SemaphorDerivedFieldResultRole;
+    dataType: NonNullable<SemaphorFieldRef['dataType']>;
+    computeStage: SemaphorDerivedFieldComputeStage;
+    expression: string;
+    expressionLanguage?: 'semaphor_sql_template';
+    inputs: Record<string, SemaphorDerivedFieldInput>;
+    defaultAggregate?: SemaphorAggregateFunction;
+    aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
+    aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
+    format?: unknown;
+    tags?: string[];
+};
+
+declare type SemaphorDerivedFieldInput = {
+    kind: 'field';
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+} | {
+    kind: 'metric';
+    metric: SemaphorFieldRef;
+} | {
+    kind: 'dimension';
+    dimension: SemaphorFieldRef;
+};
+
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'group' | 'date' | 'id' | 'filter';
+
 declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
 /**
@@ -618,6 +656,7 @@ declare type SemaphorInputOptionsIntent = {
     field: SemaphorFieldRef;
     search?: string;
     limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 declare type SemaphorMatrixAxisExpansionOptions = {
@@ -794,6 +833,7 @@ declare type SemaphorMetricIntent = {
     };
     inputs?: SemaphorInputBinding[];
     limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 declare type SemaphorPaginationRequest = {
@@ -821,6 +861,7 @@ declare type SemaphorRecordsIntent = {
         direction: 'asc' | 'desc';
     };
     inputs?: SemaphorInputBinding[];
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 declare type SemaphorRelativeTimeWindow = {

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

@@ -470,6 +470,10 @@ declare type SemaphorAnalyticsValueFilter = SemaphorAnalyticsFilterBase & {
 
 declare type SemaphorAnalyticsValueFilterOperator = Exclude<SemaphorAnalyticsFilterOperator, 'is_null' | 'is_not_null'>;
 
+declare type SemaphorAppDerivedFieldsSpec = {
+    derivedFields?: SemaphorDerivedFieldDefinition[];
+};
+
 declare type SemaphorCompiledQuery = {
     kind: 'config';
     queryId: string;
@@ -543,12 +547,51 @@ export declare type SemaphorDataAppValidationResult = {
     executionResults: SemaphorAnalyticsExecutionResult[];
 };
 
+declare type SemaphorDerivedFieldAggregationBehavior = 'additive' | 'non_additive' | 'ratio_of_sums' | 'weighted' | 'pre_aggregated' | 'snapshot';
+
+declare type SemaphorDerivedFieldAggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
+
+declare type SemaphorDerivedFieldComputeStage = 'row' | 'aggregate';
+
+declare type SemaphorDerivedFieldDefinition = {
+    kind: 'derived_field';
+    name: string;
+    label: string;
+    description?: string;
+    resultRole: SemaphorDerivedFieldResultRole;
+    dataType: NonNullable<SemaphorFieldRef['dataType']>;
+    computeStage: SemaphorDerivedFieldComputeStage;
+    expression: string;
+    expressionLanguage?: 'semaphor_sql_template';
+    inputs: Record<string, SemaphorDerivedFieldInput>;
+    defaultAggregate?: SemaphorAggregateFunction;
+    aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
+    aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
+    format?: unknown;
+    tags?: string[];
+};
+
+declare type SemaphorDerivedFieldInput = {
+    kind: 'field';
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+} | {
+    kind: 'metric';
+    metric: SemaphorFieldRef;
+} | {
+    kind: 'dimension';
+    dimension: SemaphorFieldRef;
+};
+
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'group' | 'date' | 'id' | 'filter';
+
 declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
 declare type SemaphorExecutionFieldRef = SemaphorFieldRef & {
     semanticAggregate?: SemaphorAggregateFunction;
     effectiveAggregate?: SemaphorAggregateFunction;
     aggregateSource?: SemaphorMetricAggregateSource;
+    derivedField?: SemaphorDerivedFieldDefinition;
 };
 
 /**
@@ -630,13 +673,14 @@ declare type SemaphorInputOptionsIntent = {
     field: SemaphorFieldRef;
     search?: string;
     limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 declare type SemaphorInputOptionsQueryDefinition = SemaphorInputOptionsQuerySpec & {
     queryKind: 'inputOptions';
 };
 
-declare type SemaphorInputOptionsQuerySpec = SemaphorQuerySourceSpec & {
+declare type SemaphorInputOptionsQuerySpec = SemaphorQuerySourceSpec & SemaphorAppDerivedFieldsSpec & {
     id?: string;
     label?: string;
     field: SemaphorQueryField;
@@ -869,13 +913,14 @@ declare type SemaphorMetricIntent = {
     };
     inputs?: SemaphorInputBinding[];
     limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 declare type SemaphorMetricQueryDefinition = SemaphorMetricQuerySpec & {
     queryKind: 'metric';
 };
 
-declare type SemaphorMetricQuerySpec = SemaphorQuerySourceSpec & {
+declare type SemaphorMetricQuerySpec = SemaphorQuerySourceSpec & SemaphorAppDerivedFieldsSpec & {
     id?: string;
     label?: string;
     metrics: SemaphorNonEmptyArray<SemaphorQueryField>;
@@ -941,7 +986,7 @@ declare type SemaphorQuerySourceSpec = {
     source: SemaphorSourceRef;
 };
 
-declare type SemaphorRecordsBaseQuerySpec = SemaphorQuerySourceSpec & {
+declare type SemaphorRecordsBaseQuerySpec = SemaphorQuerySourceSpec & SemaphorAppDerivedFieldsSpec & {
     id?: string;
     label?: string;
     dateField?: SemaphorQueryField;
@@ -976,6 +1021,7 @@ declare type SemaphorRecordsIntent = {
         direction: 'asc' | 'desc';
     };
     inputs?: SemaphorInputBinding[];
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 declare type SemaphorRecordsOrderBy = SemaphorQueryOrderBy;
@@ -1043,6 +1089,7 @@ declare type SemaphorResultColumn = {
     dataType?: SemaphorFieldRef['dataType'];
     aggregate?: SemaphorFieldRef['aggregate'];
     source?: SemaphorFieldRef['source'];
+    derivedField?: SemaphorDerivedFieldDefinition;
 };
 
 declare type SemaphorScalar = string | number | boolean | null;

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

@@ -343,6 +343,9 @@ export declare const semaphor: {
     filter<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: Omit<SemaphorFilterInputSpec<TValue>, "kind">): SemaphorFilterInputSpec<TValue>;
     control<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: SemaphorControlBuilderSpec<TValue>): SemaphorControlInputSpec<TValue>;
     sqlParam<TValue extends SemaphorSqlParameterValue = SemaphorSqlParameterValue>(spec: SemaphorSqlParamInputSpec<TValue>): SemaphorControlInputSpec<TValue>;
+    derivedField(spec: Omit<SemaphorDerivedFieldDefinition, "kind"> & {
+        kind?: "derived_field";
+    }): SemaphorDerivedFieldDefinition;
     metric(spec: SemaphorMetricQuerySpec): SemaphorMetricQueryDefinition;
     analysis(spec: SemaphorAnalysisQuerySpec): SemaphorAnalysisQueryDefinition;
     records(spec: SemaphorRecordsQuerySpec): SemaphorRecordsQueryDefinition;
@@ -542,6 +545,10 @@ declare type SemaphorAnalyticsValueFilterOperator = Exclude<SemaphorAnalyticsFil
 
 export declare type SemaphorAnyQueryResult<TRecord extends Record<string, unknown> = Record<string, unknown>> = SemaphorQueryResult<TRecord>;
 
+export declare type SemaphorAppDerivedFieldsSpec = {
+    derivedFields?: SemaphorDerivedFieldDefinition[];
+};
+
 declare type SemaphorCompiledQuery = {
     kind: 'config';
     queryId: string;
@@ -657,12 +664,51 @@ declare type SemaphorDataAppWindowRuntime = {
     };
 };
 
+declare type SemaphorDerivedFieldAggregationBehavior = 'additive' | 'non_additive' | 'ratio_of_sums' | 'weighted' | 'pre_aggregated' | 'snapshot';
+
+declare type SemaphorDerivedFieldAggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
+
+declare type SemaphorDerivedFieldComputeStage = 'row' | 'aggregate';
+
+export declare type SemaphorDerivedFieldDefinition = {
+    kind: 'derived_field';
+    name: string;
+    label: string;
+    description?: string;
+    resultRole: SemaphorDerivedFieldResultRole;
+    dataType: NonNullable<SemaphorFieldRef['dataType']>;
+    computeStage: SemaphorDerivedFieldComputeStage;
+    expression: string;
+    expressionLanguage?: 'semaphor_sql_template';
+    inputs: Record<string, SemaphorDerivedFieldInput>;
+    defaultAggregate?: SemaphorAggregateFunction;
+    aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
+    aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
+    format?: unknown;
+    tags?: string[];
+};
+
+declare type SemaphorDerivedFieldInput = {
+    kind: 'field';
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+} | {
+    kind: 'metric';
+    metric: SemaphorFieldRef;
+} | {
+    kind: 'dimension';
+    dimension: SemaphorFieldRef;
+};
+
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'group' | 'date' | 'id' | 'filter';
+
 declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
 declare type SemaphorExecutionFieldRef = SemaphorFieldRef & {
     semanticAggregate?: SemaphorAggregateFunction;
     effectiveAggregate?: SemaphorAggregateFunction;
     aggregateSource?: SemaphorMetricAggregateSource;
+    derivedField?: SemaphorDerivedFieldDefinition;
 };
 
 /**
@@ -744,6 +790,7 @@ declare type SemaphorInputOptionsIntent = {
     field: SemaphorFieldRef;
     search?: string;
     limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 export declare type SemaphorInputOptionsPayload = {
@@ -762,7 +809,7 @@ export declare type SemaphorInputOptionsQueryResult = SemaphorQueryState & Semap
     }>;
 };
 
-export declare type SemaphorInputOptionsQuerySpec = SemaphorQuerySourceSpec & {
+export declare type SemaphorInputOptionsQuerySpec = SemaphorQuerySourceSpec & SemaphorAppDerivedFieldsSpec & {
     id?: string;
     label?: string;
     field: SemaphorQueryField;
@@ -1007,6 +1054,7 @@ declare type SemaphorMetricIntent = {
     };
     inputs?: SemaphorInputBinding[];
     limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 export declare type SemaphorMetricPayload = {
@@ -1028,7 +1076,7 @@ export declare type SemaphorMetricQueryResult = SemaphorQueryState & SemaphorMet
     intent?: SemaphorMetricIntent;
 };
 
-export declare type SemaphorMetricQuerySpec = SemaphorQuerySourceSpec & {
+export declare type SemaphorMetricQuerySpec = SemaphorQuerySourceSpec & SemaphorAppDerivedFieldsSpec & {
     id?: string;
     label?: string;
     metrics: SemaphorNonEmptyArray<SemaphorQueryField>;
@@ -1127,7 +1175,7 @@ export declare type SemaphorQueryState = {
 
 export declare type SemaphorQueryStatus = 'idle' | 'loading' | 'success' | 'error';
 
-declare type SemaphorRecordsBaseQuerySpec = SemaphorQuerySourceSpec & {
+declare type SemaphorRecordsBaseQuerySpec = SemaphorQuerySourceSpec & SemaphorAppDerivedFieldsSpec & {
     id?: string;
     label?: string;
     dateField?: SemaphorQueryField;
@@ -1162,6 +1210,7 @@ declare type SemaphorRecordsIntent = {
         direction: 'asc' | 'desc';
     };
     inputs?: SemaphorInputBinding[];
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 export declare type SemaphorRecordsOrderBy = SemaphorQueryOrderBy;
@@ -1242,6 +1291,7 @@ export declare type SemaphorResultColumn = {
     dataType?: SemaphorFieldRef['dataType'];
     aggregate?: SemaphorFieldRef['aggregate'];
     source?: SemaphorFieldRef['source'];
+    derivedField?: SemaphorDerivedFieldDefinition;
 };
 
 export declare type SemaphorRowsQueryResult<TRecord extends Record<string, unknown> = Record<string, unknown>> = SemaphorRecordsQueryResult<TRecord> | SemaphorSqlQueryResult<TRecord>;