Skip to content

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

3.8 KB
Raw Blame
import { env } from "../../env";
import { queryClickhouse } from "../repositories/clickhouse";
import { quoteClickhouseString } from "./clickhouseIdentifiers";

// ============================================================================
// Types
// ============================================================================

export type QueryStatus = "running" | "completed" | "failed" | "not_found";

// ============================================================================
// Utilities
// ============================================================================

export function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

/**
 * Builds a system-table reference, optionally wrapped in clusterAllReplicas
 * when CH is deployed as a cluster. Single-node deployments (self-hosted) read
 * the local table directly.
 */
export function systemTableRef(
  table: "system.processes" | "system.query_log",
): string {
  if (env.CLICKHOUSE_CLUSTER_ENABLED === "true") {
    const clusterName = quoteClickhouseString(env.CLICKHOUSE_CLUSTER_NAME);
    if (table === "system.query_log") {
      return `clusterAllReplicas(${clusterName}, merge(system, '^query_log*'))`;
    }
    return `clusterAllReplicas(${clusterName}, '${table}')`;
  }
  return table;
}

// ============================================================================
// Query Status Polling
// ============================================================================

/**
 * Polls ClickHouse to determine the status of a query by its query_id.
 * First checks system.processes for running queries, then system.query_log for completed/failed.
 */
export async function pollQueryStatus(queryId: string): Promise<QueryStatus> {
  // First check if still running in system.processes
  const running = await queryClickhouse<{ query_id: string }>({
    query: `
        SELECT query_id
        FROM ${systemTableRef("system.processes")}
        WHERE query_id = {queryId: String}
        LIMIT 1
      `,
    params: { queryId },
    clickhouseConfigs: {
      request_timeout: 60_000,
    },
    clickhouseSettings: {
      skip_unavailable_shards: 1,
    },
  });

  if (running.length > 0) {
    return "running";
  }
  // Check query_log for completion status
  const result = await queryClickhouse<{
    type: string;
    exception_code: string;
  }>({
    query: `
      SELECT type, exception_code
      FROM ${systemTableRef("system.query_log")}
      WHERE query_id = {queryId: String}
      ORDER BY event_time_microseconds DESC
      LIMIT 1
    `,
    params: { queryId },
    clickhouseConfigs: {
      request_timeout: 60_000,
    },
    clickhouseSettings: {
      skip_unavailable_shards: 1,
    },
  });

  if (result.length === 0) {
    return "not_found";
  }

  const { type, exception_code } = result[0];
  if (type === "QueryStart") {
    return "running";
  }

  if (
    type === "ExceptionBeforeStart" ||
    type === "ExceptionWhileProcessing" ||
    parseInt(exception_code, 10) !== 0
  ) {
    return "failed";
  }

  if (type === "QueryFinish") {
    return "completed";
  }

  throw new Error(`Unknown query log type: ${type}`);
}

/**
 * Gets the error message for a failed query from system.query_log.
 */
export async function getQueryError(
  queryId: string,
): Promise<string | undefined> {
  const result = await queryClickhouse<{ exception_message: string }>({
    query: `
      SELECT exception as exception_message
      FROM ${systemTableRef("system.query_log")}
      WHERE query_id = {queryId: String}
        AND type != 'QueryStart'
        AND exception != ''
      ORDER BY event_time_microseconds DESC
      LIMIT 1
    `,
    params: { queryId },
    clickhouseSettings: {
      skip_unavailable_shards: 1,
    },
  });

  return result[0]?.exception_message;
}