Skip to content

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

15.1 KB
Raw Blame
import { expressionBuilder, sql, type ExpressionBuilder } from "kysely";
import { describe, expect, expectTypeOf, it } from "vitest";

import {
  compileClickhouseQuery,
  renderClickhouseExpression,
  renderClickhouseSelections,
} from "./compile";
import { getClickhouseKysely } from "./dialect";
import {
  QueryCompileError,
  TypeCompatibilityError,
  UnscopedRelationError,
} from "./errors";
import {
  arrayExists,
  arrayLength,
  arrayMap,
  count,
  countIf,
  latestNonEmpty,
  leftUTF8,
  literal,
  mapValue,
  medianExact,
  metadataMap,
  metadataValue,
  startsWith,
  uniq,
  uniqIf,
} from "./extensions";
import { ArrayIndexNode } from "./nodes";
import type { ClickHouseDatabase } from "./schema";
import { TenancyInjectionPlugin } from "./tenancy";
import { defineView, fromView } from "./views";

const projectId = "proj-1";

const eventsMetadata = (
  eb: ExpressionBuilder<{ e: ClickHouseDatabase["events"] }, "e">,
  key: string,
) =>
  metadataValue(eb.ref("e.metadata_names"), eb.ref("e.metadata_values"), key);

describe("schema-typed selection (condition 7)", () => {
  it("accepts sum() over a numeric column and emits SQL", () => {
    const qb = getClickhouseKysely()
      .selectFrom("events")
      .select((eb) => [eb.fn.sum("total_cost").as("s")]);

    const { sql: compiled } = compileClickhouseQuery(qb, projectId);
    expect(compiled.toLowerCase()).toContain("sum(total_cost)");
    expect(compiled.toLowerCase()).toContain("project_id");
  });

  it("rejects sum() over a String column at the runtime validation pass", () => {
    const qb = getClickhouseKysely()
      .selectFrom("events")
      .select((eb) => [eb.fn.sum("environment").as("s")]);

    expect(() => compileClickhouseQuery(qb, projectId)).toThrow(
      TypeCompatibilityError,
    );
    expect(() => compileClickhouseQuery(qb, projectId)).toThrow(/environment/);
  });

  it("does not type a column named like an Object prototype key", () => {
    // `constructor` is no registry column, so the pass has no type to reject.
    const db = getClickhouseKysely();
    const qb = db
      .selectFrom("scores")
      .select((eb) => [eb.fn.sum(db.dynamic.ref("constructor")).as("s")]);

    expect(() => compileClickhouseQuery(qb, projectId)).not.toThrow();
  });
});

describe("metadata subscript access (condition 7b)", () => {
  // These tests use a two-layer strategy. This first test inspects the AST
  // itself (serialized to JSON) to prove `metadata[key]` is *lowered* to real
  // operation nodes — an `ArrayIndexNode` subscript over a `mapFromArrays(...)`
  // `FunctionNode` — and never a `RawNode` (a raw SQL string). The sibling
  // tests below assert the SQL the compiler then emits. Separating them
  // isolates "the builder produced the right tree" (composable, escaped,
  // parameter-bound) from "the compiler rendered that tree correctly".
  it("lowers metadata[key] to ArrayIndexNode + mapFromArrays FunctionNode, not RawNode", () => {
    const qb = getClickhouseKysely()
      .selectFrom("events as e")
      .select((eb) => [eventsMetadata(eb, "a").as("a")])
      .where((eb) => eb(eventsMetadata(eb, "a"), "=", "x"));

    const node = qb
      .withPlugin(new TenancyInjectionPlugin(projectId))
      .toOperationNode();
    const json = JSON.stringify(node);
    expect(json).toContain('"kind":"ArrayIndexNode"');
    expect(json).toContain('"func":"mapFromArrays"');
    expect(json).not.toMatch(/"kind":"RawNode"/);

    // `.as("a")` wraps the expression in an AliasNode, so the first selection's
    // inner node must be that AliasNode rather than the bare ArrayIndexNode.
    const selections = (
      node as { selections?: { selection?: { kind: string } }[] }
    ).selections;
    expect(selections?.[0]?.selection?.kind).toBe("AliasNode");
  });

  it("emits subscript + bound key param in SELECT and WHERE", () => {
    const qb = getClickhouseKysely()
      .selectFrom("events as e")
      .select((eb) => [eventsMetadata(eb, "a").as("a")])
      .where((eb) => eb(eventsMetadata(eb, "a"), "=", "x"));

    const { sql: compiled, params } = compileClickhouseQuery(qb, projectId);
    const lower = compiled.toLowerCase();
    expect(lower).toContain(
      "mapfromarrays(arrayreverse(e.metadata_names), arrayreverse(e.metadata_values))[",
    );
    expect(lower).toContain("as a");
    expect(Object.values(params)).toContain("a");
    expect(Object.values(params)).toContain("x");
    expect(compiled).not.toMatch(/\['a'\]/);
  });

  it("emits the same lowering in HAVING", () => {
    const qb = getClickhouseKysely()
      .selectFrom("events as e")
      .select("environment")
      .groupBy("environment")
      .having((eb) => eb(eventsMetadata(eb, "a"), "=", "x"));

    const { sql: compiled, params } = compileClickhouseQuery(qb, projectId);
    expect(compiled.toLowerCase()).toContain("having");
    expect(compiled.toLowerCase()).toContain(
      "mapfromarrays(arrayreverse(e.metadata_names), arrayreverse(e.metadata_values))[",
    );
    expect(Object.values(params)).toContain("a");
  });

  // The routing pass keeps a short metadata `=` / `startsWith` on events_core
  // by trusting the lookup's marker, so the lookup may only read the metadata
  // columns of one relation.
  describe("rejects a lookup over anything but one relation's metadata columns", () => {
    const eb = expressionBuilder<{ e: ClickHouseDatabase["events"] }, "e">();
    it.each([
      // Any expression, not only `input`: the pass doesn't walk the
      // arguments, so a column inside `values` would escape routing.
      [
        "an expression as values",
        () =>
          metadataValue(
            eb.ref("e.metadata_names"),
            arrayMap<string, string>(
              () => eb.ref("e.input"),
              eb.ref("e.metadata_names"),
            ),
            "k",
          ),
      ],
      // Unqualified, the pass can't resolve which relation it reads.
      [
        "unqualified columns",
        () =>
          metadataValue(
            eb.ref("metadata_names"),
            eb.ref("metadata_values"),
            "k",
          ),
      ],
      // Swapped, the map's keys would be the values.
      [
        "swapped columns",
        () =>
          metadataValue(
            eb.ref("e.metadata_values"),
            eb.ref("e.metadata_names"),
            "k",
          ),
      ],
    ])("%s", (_, build) => {
      expect(build).toThrow(QueryCompileError);
    });

    it("rejects names and values from two relations", () => {
      const joined = expressionBuilder<
        {
          e: ClickHouseDatabase["events"];
          f: ClickHouseDatabase["events"];
        },
        "e" | "f"
      >();
      expect(() =>
        metadataValue(
          joined.ref("e.metadata_names"),
          joined.ref("f.metadata_values"),
          "k",
        ),
      ).toThrow(QueryCompileError);
    });
  });
});

describe("virtual view (condition 8)", () => {
  const environmentsView = defineView("environments_view")<{
    environment: string;
  }>(() =>
    getClickhouseKysely().selectFrom("events").select("environment").distinct(),
  );

  it("treats the view as a table and emits a WITH CTE", () => {
    const qb = fromView(environmentsView)
      .select("environment")
      .where("environment", "=", "production");

    const { sql: compiled, params } = compileClickhouseQuery(qb, projectId);
    const lower = compiled.toLowerCase();
    expect(lower).toContain("with environments_view as");
    expect(lower).toContain("from events_core");
    expect(lower).toContain("from environments_view");
    expect(lower).toContain("environment =");
    expect(Object.values(params)).toContain("proj-1");
    expect(Object.values(params)).toContain("production");
  });

  it("injects tenancy on the inner physical table, not the view alias", () => {
    const qb = fromView(environmentsView).select("environment");
    const { sql: compiled } = compileClickhouseQuery(qb, projectId);
    const lower = compiled.toLowerCase();
    expect(lower).toMatch(
      /with environments_view as \([\s\S]*project_id[\s\S]*\)[\s\S]*from environments_view/,
    );
    const afterView = lower.split("from environments_view")[1] ?? "";
    expect(afterView).not.toContain("project_id");
  });
});

describe("ArrayIndexNode identity", () => {
  it("is a real node kind", () => {
    expect(
      ArrayIndexNode.is(
        ArrayIndexNode.create(
          {
            kind: "ColumnNode",
            column: { kind: "IdentifierNode", name: "x" },
          } as never,
          { kind: "ValueNode", value: 1 } as never,
        ),
      ),
    ).toBe(true);
  });
});

describe("leftUTF8", () => {
  it("inlines a positive integer length", () => {
    const qb = getClickhouseKysely()
      .selectFrom("events as e")
      .select((eb) => [leftUTF8(eb.ref("e.input"), 100).as("input")]);

    const { sql: compiled } = compileClickhouseQuery(qb, projectId);
    expect(compiled).toContain("leftUTF8(e.input, 100)");
  });

  it.each([0, -1, 1.5, Number.NaN])("rejects length %s", (length) => {
    expect(() =>
      getClickhouseKysely()
        .selectFrom("events as e")
        .select((eb) => [leftUTF8(eb.ref("e.input"), length).as("input")]),
    ).toThrow(QueryCompileError);
  });
});

describe("arrayMap", () => {
  it("names nested lambda parameters apart so the inner one does not shadow", () => {
    const qb = getClickhouseKysely()
      .selectFrom("events as e")
      .select((eb) => [
        arrayMap<string, string[]>(
          (name) =>
            arrayMap<string, string>(
              (tag) => eb.fn<string>("concat", [name, tag]),
              eb.ref("e.tags"),
            ),
          eb.ref("e.metadata_names"),
        ).as("nested"),
        arrayMap<string, string>(
          (value) => leftUTF8(value, 2),
          eb.ref("e.tags"),
        ).as("sibling"),
      ]);

    const { sql: compiled } = compileClickhouseQuery(qb, projectId);
    expect(compiled).toContain(
      "arrayMap(v -> arrayMap(v1 -> concat(v, v1), e.tags), e.metadata_names)",
    );
    expect(compiled).toContain("arrayMap(v -> leftUTF8(v, 2), e.tags)");
  });
});

describe("arrayExists", () => {
  it("names nested lambda parameters apart so the inner one does not shadow", () => {
    const eb = expressionBuilder<{ e: ClickHouseDatabase["events"] }, "e">();
    const nested = arrayExists<string>(
      (name) =>
        arrayExists<string>((tag) => eb(tag, "=", name), eb.ref("e.tags")),
      eb.ref("e.metadata_names"),
    );

    expect(renderClickhouseExpression(nested)).toBe(
      "arrayExists(x -> arrayExists(x1 -> x1 = x, e.tags), e.metadata_names)",
    );
  });
});

describe("renderClickhouseExpression", () => {
  const eb = expressionBuilder<{ e: ClickHouseDatabase["events"] }, "e">();
  const metadata = metadataMap(
    eb.ref("e.metadata_names"),
    eb.ref("e.metadata_values"),
  );

  it("renders a typed expression as the SQL the compiler emits inline", () => {
    expect(renderClickhouseExpression(metadata)).toBe(
      "mapFromArrays(arrayReverse(e.metadata_names), arrayReverse(e.metadata_values))",
    );
    expect(
      renderClickhouseExpression(
        latestNonEmpty(eb.ref("session_id"), eb.ref("event_ts")),
      ),
    ).toBe("argMaxIf(session_id, event_ts, session_id != '')");
  });

  it("rejects a subquery", () => {
    const subquery = getClickhouseKysely()
      .selectFrom("events")
      .select("trace_id");
    expect(() => renderClickhouseExpression(subquery)).toThrow(
      UnscopedRelationError,
    );
  });

  it("rejects a raw fragment that introduces a relation", () => {
    expect(() =>
      renderClickhouseExpression(sql`(select trace_id from events_core)`),
    ).toThrow(UnscopedRelationError);
  });

  it("rejects a bound value", () => {
    expect(() => renderClickhouseExpression(mapValue(metadata, "key"))).toThrow(
      /cannot bind parameters/,
    );
  });
});

describe("renderClickhouseSelections", () => {
  const events = getClickhouseKysely().selectFrom("events as e");

  it("keys each select by its output name, in select order", () => {
    const rendered = renderClickhouseSelections(
      events.select((eb) => [
        "e.span_id as id",
        "e.trace_id",
        eb.fn.min("e.start_time").as("start"),
      ]),
    );
    expect(Object.entries(rendered)).toEqual([
      ["id", "e.span_id as id"],
      ["trace_id", "e.trace_id"],
      ["start", "min(e.start_time) as start"],
    ]);
    expectTypeOf(rendered).toEqualTypeOf<
      Record<"id" | "trace_id" | "start", string>
    >();
  });

  it("keys an output name that is also an Object prototype key", () => {
    expect(
      renderClickhouseSelections(
        events.select((eb) => eb.ref("e.trace_id").as("constructor")),
      ),
    ).toEqual({ constructor: "e.trace_id as constructor" });
  });

  it("rejects a select without an output name", () => {
    expect(() => renderClickhouseSelections(events.selectAll())).toThrow(
      QueryCompileError,
    );
  });

  it("rejects two selects with one output name", () => {
    expect(() =>
      renderClickhouseSelections(
        events.select((eb) => [
          "e.trace_id",
          eb.ref("e.span_id").as("trace_id"),
        ]),
      ),
    ).toThrow(/share the output name "trace_id"/);
  });

  it("rejects a select containing a subquery", () => {
    expect(() =>
      renderClickhouseSelections(
        events.select((eb) =>
          eb.selectFrom("events as x").select("x.trace_id").as("t"),
        ),
      ),
    ).toThrow(UnscopedRelationError);
  });
});

describe("64-bit results", () => {
  const eb = expressionBuilder<{ e: ClickHouseDatabase["events"] }, "e">();
  const isError = eb("e.level", "=", literal("ERROR"));

  // ClickHouse 25.8+ (Langfuse v4 needs 25.12) sends (U)Int64 as JSON numbers.
  it("types count and length results as number", () => {
    expectTypeOf(count().expressionType).toEqualTypeOf<number | undefined>();
    expectTypeOf(countIf(isError).expressionType).toEqualTypeOf<
      number | undefined
    >();
    expectTypeOf(uniq(eb.ref("e.trace_id")).expressionType).toEqualTypeOf<
      number | undefined
    >();
    expectTypeOf(
      uniqIf(eb.ref("e.trace_id"), isError).expressionType,
    ).toEqualTypeOf<number | undefined>();
    expectTypeOf(arrayLength(eb.ref("e.tags")).expressionType).toEqualTypeOf<
      number | undefined
    >();
    expectTypeOf(
      medianExact(eb.ref("e.total_cost")).expressionType,
    ).toEqualTypeOf<number | undefined>();
  });
});

describe("literal", () => {
  it("inlines a string with its quotes doubled", () => {
    expect(renderClickhouseExpression(literal("it's"))).toBe("'it''s'");
  });

  it("rejects a backslash, which ClickHouse reads as an escape", () => {
    expect(() => literal("a\\")).toThrow(QueryCompileError);
  });
});

describe("startsWith", () => {
  it("binds a string prefix and inlines a literal one", () => {
    const { sql, params } = compileClickhouseQuery(
      getClickhouseKysely()
        .selectFrom("events as e")
        .select("e.span_id")
        .where((eb) => startsWith(eb.ref("e.name"), "caller"))
        .where((eb) => startsWith(eb.ref("e.user_id"), literal("const"))),
      projectId,
    );
    expect(sql).toMatch(/startsWith\(e\.name, \{p\d+:String\}\)/);
    expect(sql).toContain("startsWith(e.user_id, 'const')");
    expect(Object.values(params)).toContain("caller");
  });
});