🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
import { type QueryType, type ViewVersion } from "./types";
import { getViewDeclaration } from "./dataModel";
/**
* Result of query validation.
* Either valid (query is safe to run) or invalid with a reason.
*/
export type HighCardinalityValidationCode =
| "entity_dimension_unbounded"
| "time_dimension"
| "additional_entity_dimension"
| "missing_top_n"
| "invalid_order_by";
export type HighCardinalityValidationError = {
code: HighCardinalityValidationCode;
/** Schema-owned dimension field names, never dimension values. */
dimensions: string[];
};
export type QueryValidationResult =
| { valid: true }
| {
valid: false;
reason: string;
highCardinality?: HighCardinalityValidationError;
};
const MAX_ENTITY_DIMENSION_BOUND_VALUES = 50;
function hasSameFieldEntityDimensionBound(
filters: QueryType["filters"],
field: string,
): boolean {
return filters.some((filter) => {
if (filter.column !== field) {
return false;
}
if (filter.type === "string") {
return filter.operator === "=" && filter.value.length > 0;
}
if (filter.type === "stringOptions" || filter.type === "categoryOptions") {
return (
filter.operator === "any of" &&
filter.value.length > 0 &&
filter.value.length <= MAX_ENTITY_DIMENSION_BOUND_VALUES &&
filter.value.every((value) => value.length > 0)
);
}
return false;
});
}
/**
* Gets the list of high cardinality dimension fields used in the query.
*
* @param query - The query configuration
* @param version - The view version (v1 or v2)
* @returns Array of high cardinality field names
*/
function getHighCardinalityDimensions(
query: QueryType,
version: ViewVersion,
): string[] {
if (!query.dimensions || query.dimensions.length === 0) {
return [];
}
const view = getViewDeclaration(query.view, version);
return query.dimensions
.filter((dim) => view.dimensions[dim.field]?.highCardinality)
.map((dim) => dim.field);
}
/**
* Finds the measure name that matches an orderBy field.
* OrderBy fields can be:
* - "{aggregation}_{measureName}" like "sum_totalCost" or "count_count"
* - Just the measure name like "totalCost"
* We search for known measure names as suffixes of the orderBy field.
*
* @param orderByField - The orderBy field string
* @param knownMeasures - List of known measure names from the query
* @returns The matching measure name, or null if no match found
*/
function findMeasureInOrderByField(
orderByField: string,
knownMeasures: string[],
): string | null {
for (const measure of knownMeasures) {
// Check exact match (e.g., orderBy: "totalCost" matches measure "totalCost")
if (orderByField === measure) {
return measure;
}
// Check suffix match (e.g., orderBy: "sum_totalCost" matches measure "totalCost")
if (orderByField.endsWith(`_${measure}`)) {
return measure;
}
}
return null;
}
function validateEntityDimension(
query: QueryType,
version: ViewVersion,
): QueryValidationResult {
const view = getViewDeclaration(query.view, version);
const field = query.entityDimension!.field;
const dimension = view.dimensions[field];
if (
!dimension ||
dimension.explodeArray ||
dimension.pairExpand ||
dimension.aggregationFunction
)
return {
valid: false,
reason: `Invalid entity dimension: ${field}. Entity dimensions must be scalar view dimensions.`,
};
if (
dimension.highCardinality &&
!hasSameFieldEntityDimensionBound(query.filters, field)
) {
return {
valid: false,
reason: `High cardinality dimension '${field}' must be filtered with a finite positive filter.`,
highCardinality: {
code: "entity_dimension_unbounded",
dimensions: [field],
},
};
}
return { valid: true };
}
/**
* Validates a query for safety before execution.
* Performs sanity checks for high cardinality dimension validation.
*
* High cardinality dimensions (id, traceId, userId, sessionId, etc.) are only allowed when:
* 1. timeDimension is NOT set (timeseries with high cardinality produces unbounded results)
* 2. config.row_limit (or chartConfig.row_limit) is explicitly specified (LIMIT)
* 3. orderBy with direction 'desc' on a measure field is specified (for top-N queries)
*
* High cardinality entityDimension can also be allowed by a finite positive
* same-field filter, which bounds the grouped keyspace before GROUP BY.
* @param query - The query configuration (with original config, before defaults applied)
* @param version - The view version (v1 or v2)
* @returns Validation result: { valid: true } or { valid: false, reason: string }
*/
export function validateQuery(
query: QueryType,
version: ViewVersion,
): QueryValidationResult {
if (query.timeDimension && query.entityDimension) {
return {
valid: false,
reason: "timeDimension and entityDimension are mutually exclusive",
};
}
if (query.entityDimension && version !== "v2") {
return {
valid: false,
reason: "entityDimension is only supported for v2 queries",
};
}
// Only enforce remaining high-cardinality validation for v2 queries.
if (version !== "v2") {
return { valid: true };
}
if (query.entityDimension) {
const validation = validateEntityDimension(query, version);
if (!validation.valid) {
return validation;
}
}
// 1. Check for high cardinality dimensions, including entityDimension.
const highCardDims = getHighCardinalityDimensions(query, version);
if (highCardDims.length === 0) {
return { valid: true };
}
// 2. Reject high cardinality dimensions in timeseries queries
// A timeseries grouped by e.g. traceId produces unbounded rows (one per ID per time bucket)
// and cannot be meaningfully limited with row_limit.
if (query.timeDimension) {
return {
valid: false,
reason: `High cardinality dimension(s) '${highCardDims.join(", ")}' cannot be used with timeDimension. Time series queries with high cardinality dimensions produce unbounded result sets.`,
highCardinality: {
code: "time_dimension",
dimensions: highCardDims,
},
};
}
// An entity-dimension query with additional high cardinality dimensions produces unbounded result sets and cannot be meaningfully limited with row_limit.
if (query.entityDimension) {
return {
valid: false,
reason: `High cardinality dimension(s) '${highCardDims.join(", ")}' cannot be used with entityDimension. Entity-dimension queries with additional high cardinality dimensions produce unbounded result sets.`,
highCardinality: {
code: "additional_entity_dimension",
dimensions: highCardDims,
},
};
}
// 3. Validate required conditions for high cardinality
// Support both public API "config" and internal "chartConfig" field names
const chartConfig =
(query as unknown as { config?: QueryType["chartConfig"] }).config ??
query.chartConfig;
const hasExplicitLimit = chartConfig?.row_limit !== undefined;
// 4. Validate ORDER BY - must have at least one desc on a measure field
const orderByDescFields =
query.orderBy?.filter((o) => o.direction === "desc") ?? [];
if (!hasExplicitLimit || orderByDescFields.length === 0) {
return {
valid: false,
reason: `High cardinality dimension(s) '${highCardDims.join(", ")}' require both 'config.row_limit' and 'orderBy' with direction 'desc' on a measure field.`,
highCardinality: {
code: "missing_top_n",
dimensions: highCardDims,
},
};
}
// Extract measure names from orderBy fields and validate they are measures in the query
const queryMeasureNames = query.metrics.map((m) => m.measure);
const invalidOrderByFields: string[] = [];
for (const orderBy of orderByDescFields) {
const matchedMeasure = findMeasureInOrderByField(
orderBy.field,
queryMeasureNames,
);
if (!matchedMeasure) {
invalidOrderByFields.push(orderBy.field);
}
}
if (invalidOrderByFields.length > 0) {
return {
valid: false,
reason:
`High cardinality dimension(s) '${highCardDims.join(", ")}' require 'orderBy' with direction 'desc' on a measure field. ` +
`'${invalidOrderByFields.join(", ")}' ${invalidOrderByFields.length === 1 ? "is" : "are"} not a measure in this query.`,
highCardinality: {
code: "invalid_order_by",
dimensions: highCardDims,
},
};
}
return { valid: true };
}
/**
* Extracts only query-engine fields from a widget's persisted chartConfig.
* Strips rendering-only fields (defaultSort, show_value_labels, etc.)
* that are only used by Chart components.
*
* Accepts any object with at least `type: string` — the discriminated union
* from ChartConfigSchema satisfies this via tRPC inference.
*/
export function toQueryChartConfig<
T extends { type: string; bins?: number; row_limit?: number },
>(
widgetChartConfig: T,
options?: { defaultRowLimit?: number },
): NonNullable<QueryType["chartConfig"]> {
const rowLimit = widgetChartConfig.row_limit ?? options?.defaultRowLimit;
return {
type: widgetChartConfig.type,
...(widgetChartConfig.bins !== undefined && {
bins: widgetChartConfig.bins,
}),
...(rowLimit !== undefined && { row_limit: rowLimit }),
};
}
/**
* Checks if a non-timeseries chart with a dimension on v2 needs top-N
* enforcement (orderBy desc + row_limit).
*/
export function isV2BreakdownChart(params: {
version: ViewVersion;
hasDimension: boolean;
isTimeSeries: boolean;
chartType: string;
}): boolean {
return (
params.version === "v2" &&
params.hasDimension &&
!params.isTimeSeries &&
params.chartType !== "HISTOGRAM" &&
params.chartType !== "PIVOT_TABLE"
);
}
/**
* Builds the orderBy clause for a widget query.
* - PIVOT_TABLE: uses the provided sort state
* - v2 breakdown charts: auto-sorts desc on the first metric for top-N
* - Otherwise: null
*/
export function buildWidgetOrderBy(params: {
chartType: string;
sortState: { column: string; order: string } | null;
needsTopN: boolean;
firstMetric: { aggregation: string; measure: string } | undefined;
}): QueryType["orderBy"] {
if (params.chartType === "PIVOT_TABLE" && params.sortState) {
return [
{
field: params.sortState.column,
direction: params.sortState.order.toLowerCase() as "asc" | "desc",
},
];
}
if (params.needsTopN && params.firstMetric) {
return [
{
field: `${params.firstMetric.aggregation}_${params.firstMetric.measure}`,
direction: "desc",
},
];
}
return null;
}