🪢 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 IdentifierNode,
type OperationNode,
type SelectQueryNode,
} from "kysely";
/**
* ClickHouse `ARRAY JOIN` / `LEFT ARRAY JOIN` / `INNER ARRAY JOIN`.
*
* Not a Kysely `OperationNode` kind — Kysely's `kind` union is closed, so a
* real custom kind would collapse to `never`. These nodes live as extra
* fields on {@link ClickHouseSelectQueryNode}. Children (`expression`,
* `alias`) are traced Kysely nodes, not raw SQL.
*/
export type ArrayJoinVariant = "default" | "left" | "inner";
type ArrayJoinItemNode = {
readonly expression: OperationNode;
readonly alias: IdentifierNode;
};
export type ArrayJoinNode = {
readonly kind: "ArrayJoinNode";
readonly variant: ArrayJoinVariant;
readonly items: ReadonlyArray<ArrayJoinItemNode>;
};
export const ArrayJoinNode = {
is(node: { kind: string }): node is ArrayJoinNode {
return node.kind === "ArrayJoinNode";
},
create(
items: ReadonlyArray<ArrayJoinItemNode>,
variant: ArrayJoinVariant = "default",
): ArrayJoinNode {
return Object.freeze({
kind: "ArrayJoinNode",
variant,
items: Object.freeze([...items]),
});
},
};
/**
* ClickHouse `LIMIT n BY col1, col2, ...`.
*
* Distinct from Kysely's `LimitNode` (`LIMIT n`). ClickHouse places LIMIT BY
* after ORDER BY and before a plain LIMIT.
*/
export type LimitByNode = {
readonly kind: "LimitByNode";
readonly count: OperationNode;
readonly columns: ReadonlyArray<OperationNode>;
};
export const LimitByNode = {
is(node: { kind: string }): node is LimitByNode {
return node.kind === "LimitByNode";
},
create(
count: OperationNode,
columns: ReadonlyArray<OperationNode>,
): LimitByNode {
return Object.freeze({
kind: "LimitByNode",
count,
columns: Object.freeze([...columns]),
});
},
};
/**
* ClickHouse array subscript `arr[index]`. Children are traced nodes
* (typically a `mapFromArrays(...)` FunctionNode and a bound key), not raw SQL.
*
* Same closed-`kind` constraint as ARRAY JOIN: not a Kysely visitor-map
* kind. The dialect compiler and transformer special-case this object.
*/
export type ArrayIndexNode = {
readonly kind: "ArrayIndexNode";
readonly array: OperationNode;
readonly index: OperationNode;
/**
* `metadata[key]` over one relation's `metadata_names`/`metadata_values`,
* so events routing can keep a short metadata predicate on `events_core`.
*/
readonly metadataLookup?: true;
};
export const ArrayIndexNode = {
is(node: { kind: string }): node is ArrayIndexNode {
return node.kind === "ArrayIndexNode";
},
create(
array: OperationNode,
index: OperationNode,
metadataLookup = false,
): ArrayIndexNode {
return Object.freeze({
kind: "ArrayIndexNode",
array,
index,
...(metadataLookup ? { metadataLookup: true as const } : {}),
});
},
};
/**
* Select query extended with ClickHouse-only clauses.
* Extra fields are ignored by Kysely's default compiler/transformer; our
* dialect compiler and {@link ClickHouseOperationNodeTransformer} are the
* ones that read them. Tenancy is stamped by identity (WeakSet), not a
* copyable property on this node.
*/
export type ClickHouseSelectQueryNode = SelectQueryNode & {
readonly arrayJoins?: ReadonlyArray<ArrayJoinNode>;
readonly limitBy?: LimitByNode;
/** Set by `includeDeleted()`: the soft-delete pass skips this select. */
readonly includeDeleted?: true;
/**
* Set by `softDeleteAfterLimit()`: the soft-delete pass filters this
* select's output instead of its relation.
*/
readonly softDeleteAfterLimit?: true;
};
export function isClickHouseSelectQueryNode(
node: OperationNode,
): node is ClickHouseSelectQueryNode {
return node.kind === "SelectQueryNode";
}
/**
* ClickHouse `FROM <table> FINAL` / `JOIN <table> AS alias FINAL`.
*
* Wraps a table expression (bare `TableNode` or `AliasNode`) so the compiler
* emits `final` after that expression. Same closed-`kind` constraint as
* ARRAY JOIN: not a Kysely visitor-map kind. The dialect compiler and
* transformer special-case this object.
*/
export type FinalTableNode = {
readonly kind: "FinalTableNode";
readonly table: OperationNode;
};
export const FinalTableNode = {
is(node: { kind: string }): node is FinalTableNode {
return node.kind === "FinalTableNode";
},
create(table: OperationNode): FinalTableNode {
return Object.freeze({
kind: "FinalTableNode",
table,
});
},
};
/** {@link FinalTableNode.create}, typed as the FROM/JOIN item it stands in for. */
export function finalTable(table: OperationNode): OperationNode {
return FinalTableNode.create(table) as unknown as OperationNode;
}
/**
* Read the wrapped table expression. `FinalTableNode.kind` is outside
* Kysely's closed `OperationNodeKind`, so a narrowed
* `OperationNode & FinalTableNode` is `never` and `.table` is unreadable
* without this cast.
*/
export function unwrapFinalTable(node: { kind: string }): OperationNode {
return (node as unknown as FinalTableNode).table;
}
/**
* Calls `visit` on every node object under `value`, ClickHouse extra fields
* included, parents before children. `visit` returns `false` to skip a
* node's children.
*/
export function walkNodes(
value: unknown,
visit: (node: OperationNode) => boolean | void,
): void {
if (!value || typeof value !== "object") return;
if ("kind" in value && typeof value.kind === "string") {
if (visit(value as OperationNode) === false) return;
}
for (const child of Object.values(value)) walkNodes(child, visit);
}