Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

10.5 KB
Raw Blame
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;
}