@kazurolabs/psql-explorer 0.0.0-stage → 0.3.0

package/dist/explorer/cypher.js

@@ -0,0 +1,963 @@
+// Cypher queries over a relational database. Labels are tables, relationships are foreign keys (or
+// a chain of them through tables in between), and a query is turned into one SELECT. Before it runs,
+// Postgres is asked for its plan, which together with the shape of the query says how heavy it is.
+import { createHash } from 'node:crypto';
+import { quoteIdentifier } from '../db/identifiers.js';
+import { listColumns, listSchemas, listTables, qualified, tableLabel, } from './catalog.js';
+import { primaryKeyOf } from './edit.js';
+import { keyLabel, nodeId } from './graph.js';
+import { AGGREGATES, CypherError, parseCypher, } from './cypher-parse.js';
+import { foreignKeyId, listSchemaForeignKeys } from './references.js';
+import { describeQueryError } from './session.js';
+export { CypherError, parseCypher } from './cypher-parse.js';
+/** Foreign keys followed between two nodes at most: up to MAX_STEPS - 1 tables are only passed through. */
+export const MAX_STEPS = 4;
+/** Rows read when the query has no LIMIT, and the most rows any query reads. */
+export const DEFAULT_ROWS = 200;
+export const MAX_ROWS = 1000;
+export const DEFAULT_TIMEOUT_MS = 15_000;
+const labelsOf = (query) => query.patterns.flatMap((pattern) => pattern.nodes.flatMap((node) => (node.label ? [node.label] : [])));
+/** Reads what compiling needs from the database: tables, foreign keys, and the columns of the tables the query names. */
+export async function loadCypherModel(session, query) {
+    const tables = [];
+    const keys = new Map();
+    for (const schema of await listSchemas(session)) {
+        for (const table of await listTables(session, schema.name)) {
+            tables.push({
+                ref: { schema: table.schema, name: table.name },
+                kind: table.kind,
+                estimatedRows: table.estimatedRows,
+            });
+        }
+        for (const key of await listSchemaForeignKeys(session, schema.name)) {
+            keys.set(foreignKeyId(key), key);
+        }
+    }
+    const model = {
+        defaultSchema: session.params.schema,
+        tables,
+        keys: [...keys.values()],
+        columns: new Map(),
+    };
+    for (const label of labelsOf(query)) {
+        const table = findTable(model, label);
+        if (!model.columns.has(tableLabel(table.ref))) {
+            model.columns.set(tableLabel(table.ref), await listColumns(session, table.ref));
+        }
+    }
+    return model;
+}
+const plain = (text) => text
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/[\s-]+/g, '_')
+    .toLowerCase();
+/** `Customer` → customers, `OrderLine` → order_lines, `Category` → categories: the forms a table may be called. */
+function variantsOf(name) {
+    const base = plain(name);
+    const forms = new Set([base, `${base}s`, `${base}es`]);
+    if (base.endsWith('y'))
+        forms.add(`${base.slice(0, -1)}ies`);
+    if (base.endsWith('s'))
+        forms.add(base.slice(0, -1));
+    if (base.endsWith('ies'))
+        forms.add(`${base.slice(0, -3)}y`);
+    return [...forms];
+}
+/** The table a label names: exactly, then without regard to case, then in its plural or snake case form. */
+export function findTable(model, label) {
+    const dot = label.indexOf('.');
+    const schema = dot > 0 ? label.slice(0, dot) : undefined;
+    const name = dot > 0 ? label.slice(dot + 1) : label;
+    const inScope = model.tables.filter((table) => !schema || table.ref.schema === schema);
+    const steps = [
+        (table) => table.ref.name === name,
+        (table) => table.ref.name.toLowerCase() === name.toLowerCase(),
+        (table) => variantsOf(name).includes(plain(table.ref.name)),
+    ];
+    for (const matches of steps) {
+        const found = inScope.filter(matches);
+        if (found.length === 0)
+            continue;
+        const here = found.filter((table) => table.ref.schema === model.defaultSchema);
+        const pick = here.length > 0 ? here : found;
+        if (pick.length === 1)
+            return pick[0];
+        throw new CypherError(`${label} could be any of ${pick.map((table) => tableLabel(table.ref)).join(', ')}: write the schema, e.g. ${tableLabel(pick[0].ref)}`);
+    }
+    const known = inScope
+        .filter((table) => table.ref.schema === (schema ?? model.defaultSchema))
+        .map((table) => table.ref.name)
+        .slice(0, 12);
+    throw new CypherError(`no table matches the label ${label}${known.length > 0 ? `; tables here include ${known.join(', ')}` : ''}`);
+}
+const stepEnd = (step) => (step.forward ? step.key.to : step.key.from);
+const sameTable = (a, b) => a.schema === b.schema && a.name === b.name;
+const shortName = (model, table) => table.schema === model.defaultSchema ? table.name : tableLabel(table);
+/** `customers ← orders ← order_lines → products`: the arrow points at the table that is pointed at. */
+export function describeRoute(model, start, steps) {
+    let text = shortName(model, start);
+    for (const step of steps)
+        text += ` ${step.forward ? '→' : '←'} ${shortName(model, stepEnd(step))}`;
+    return text;
+}
+const matchesKey = (step, hint) => step.key.name.toLowerCase() === hint.toLowerCase() ||
+    step.key.fromColumns.some((column) => column.toLowerCase() === hint.toLowerCase());
+const matchesTable = (table, hint) => table.name.toLowerCase() === hint.toLowerCase() ||
+    tableLabel(table).toLowerCase() === hint.toLowerCase();
+function stepsFrom(keys, table) {
+    const steps = [];
+    for (const key of keys) {
+        if (sameTable(key.from, table))
+            steps.push({ key, forward: true });
+        if (sameTable(key.to, table))
+            steps.push({ key, forward: false });
+    }
+    return steps;
+}
+/**
+ * The foreign keys that join two tables. A key between them is used directly; otherwise the shortest
+ * chain of keys through other tables (the direction of the arrow is then not used, as the keys along a
+ * chain point both ways). Chains that tie are an error, since the query would mean something else for
+ * each: a hint (`-[:orders]-`, the name of a key, a column or a table on the way) settles it.
+ */
+export function routeBetween(model, from, to, direction, hint) {
+    const name = `${shortName(model, from)} and ${shortName(model, to)}`;
+    const all = stepsFrom(model.keys, from).filter((step) => sameTable(stepEnd(step), to));
+    const wanted = all
+        .filter((step) => direction === 'any' || (direction === 'out') === step.forward)
+        .filter((step) => !hint || matchesKey(step, hint));
+    if (wanted.length === 1)
+        return wanted;
+    if (wanted.length > 1) {
+        throw new CypherError(`${name} are joined by ${wanted.length} foreign keys (${wanted.map((step) => step.key.name).join(', ')}): name one, e.g. -[:${wanted[0].key.name}]-` +
+            (direction === 'any' && sameTable(from, to) ? ', or give the arrow a direction' : ''));
+    }
+    if (!hint && all.length > 0) {
+        throw new CypherError(`the foreign key between ${name} points the other way: ${describeRoute(model, from, all.slice(0, 1))}; use ${direction === 'out' ? '<-' : '->'} instead`);
+    }
+    if (hint && all.length > 0) {
+        // Keys join them directly, so the hint cannot be about a table on the way.
+        throw new CypherError(`no foreign key between ${name} is called "${hint}"; they have ${all.map((step) => `${step.key.name} (${step.key.fromColumns.join(', ')})`).join(', ')}`);
+    }
+    // Chains through other tables.
+    const reach = distancesTo(model.keys, to);
+    for (let limit = 2; limit <= MAX_STEPS; limit++) {
+        const found = [];
+        const walk = (at, steps) => {
+            if (steps.length === limit) {
+                if (sameTable(at, to) && (!hint || satisfies(steps, hint)))
+                    found.push(steps);
+                return;
+            }
+            for (const step of stepsFrom(model.keys, at)) {
+                const last = steps[steps.length - 1];
+                // Straight back along the key just followed is not a new way.
+                if (last && last.key === step.key && last.forward !== step.forward)
+                    continue;
+                const next = stepEnd(step);
+                if (steps.length + 1 + (reach.get(tableLabel(next)) ?? Infinity) > limit)
+                    continue;
+                walk(next, [...steps, step]);
+            }
+        };
+        walk(from, []);
+        if (found.length === 1)
+            return found[0];
+        if (found.length > 1) {
+            const ways = found.map((steps) => `  ${describeRoute(model, from, steps)}  (${steps.map((s) => s.key.name).join(', ')})`);
+            // A table on the first way that not every way goes through tells them apart, else one of its keys.
+            const inAll = (table) => found.every((steps) => steps.slice(0, -1).some((s) => sameTable(stepEnd(s), table)));
+            const odd = found[0]
+                .slice(0, -1)
+                .map(stepEnd)
+                .find((table) => !inAll(table));
+            throw new CypherError(`${name} are joined in ${found.length} equally short ways:\n${ways.join('\n')}\nname one with a table or key on the way, e.g. -[:${odd?.name ?? found[0][0].key.name}]-, or write the nodes along it`);
+        }
+    }
+    if (hint) {
+        throw new CypherError(`no way to join ${name} goes through "${hint}" within ${MAX_STEPS} foreign keys`);
+    }
+    throw new CypherError(`${name} are not joined by foreign keys, directly or through up to ${MAX_STEPS - 1} tables in between`);
+}
+function satisfies(steps, hint) {
+    return (steps.some((step) => matchesKey(step, hint)) ||
+        steps.slice(0, -1).some((step) => matchesTable(stepEnd(step), hint)));
+}
+/** Steps from each table to `target` along foreign keys either way, for not walking where it cannot lead. */
+function distancesTo(keys, target) {
+    const dist = new Map([[tableLabel(target), 0]]);
+    let level = [target];
+    for (let d = 1; d <= MAX_STEPS && level.length > 0; d++) {
+        const next = [];
+        for (const table of level) {
+            for (const step of stepsFrom(keys, table)) {
+                const other = stepEnd(step);
+                if (!dist.has(tableLabel(other))) {
+                    dist.set(tableLabel(other), d);
+                    next.push(other);
+                }
+            }
+        }
+        level = next;
+    }
+    return dist;
+}
+const quoteLiteral = (text) => `'${text.replaceAll("'", "''")}'`;
+function emitter(inline) {
+    const values = [];
+    return {
+        values,
+        value(value, cast) {
+            if (value === null)
+                return 'NULL';
+            if (typeof value === 'boolean')
+                return value ? 'TRUE' : 'FALSE';
+            if (typeof value === 'number')
+                return Number.isFinite(value) ? String(value) : 'NULL';
+            if (inline)
+                return quoteLiteral(value);
+            values.push(value);
+            return `$${values.length}${cast ? `::${cast}` : ''}`;
+        },
+    };
+}
+const walk = (expr, visit) => {
+    visit(expr);
+    switch (expr.kind) {
+        case 'compare':
+        case 'logic':
+            walk(expr.left, visit);
+            walk(expr.right, visit);
+            break;
+        case 'not':
+        case 'null':
+            walk(expr.operand, visit);
+            break;
+        case 'in':
+            walk(expr.operand, visit);
+            for (const item of expr.list)
+                walk(item, visit);
+            break;
+        case 'call':
+            for (const arg of expr.args)
+                walk(arg, visit);
+            break;
+        default:
+    }
+};
+const variablesIn = (expr) => {
+    const found = new Set();
+    walk(expr, (e) => {
+        if (e.kind === 'property')
+            found.add(e.variable);
+        if (e.kind === 'variable')
+            found.add(e.name);
+    });
+    return found;
+};
+const hasAggregate = (expr) => {
+    let found = false;
+    walk(expr, (e) => {
+        if (e.kind === 'call' && AGGREGATES.includes(e.name))
+            found = true;
+    });
+    return found;
+};
+export function compileCypher(query, model) {
+    const scope = new Map();
+    const order = [];
+    const hiddenCount = new Map();
+    const hiddenAlias = (table) => {
+        const n = (hiddenCount.get(table.name) ?? 0) + 1;
+        hiddenCount.set(table.name, n);
+        return quoteIdentifier(`${table.name}#${n}`);
+    };
+    // Nodes: variables and their tables.
+    let anonymous = 0;
+    const bind = (node) => {
+        const known = node.variable ? scope.get(node.variable) : undefined;
+        if (known) {
+            if (node.label && !sameTable(findTable(model, node.label).ref, known.table.ref)) {
+                throw new CypherError(`${node.variable} is already ${shortName(model, known.table.ref)}, not ${node.label}`, node.at);
+            }
+            return known;
+        }
+        if (!node.label) {
+            throw new CypherError(node.variable
+                ? `say which table ${node.variable} is a row of, e.g. (${node.variable}:Customer)`
+                : 'say which table this node is a row of, e.g. (:Customer)', node.at);
+        }
+        const table = findTable(model, node.label);
+        const columns = model.columns.get(tableLabel(table.ref));
+        if (!columns)
+            throw new CypherError(`the columns of ${node.label} were not loaded`, node.at);
+        const name = node.variable ?? `anonymous${++anonymous}`;
+        const binding = {
+            name,
+            alias: node.variable ? quoteIdentifier(name) : hiddenAlias(table.ref),
+            table,
+            columns,
+            anonymous: !node.variable,
+        };
+        scope.set(name, binding);
+        order.push(binding);
+        return binding;
+    };
+    const column = (binding, name, at) => {
+        const exact = binding.columns.find((c) => c.name === name);
+        const loose = binding.columns.filter((c) => c.name.toLowerCase() === name.toLowerCase());
+        const found = exact ?? (loose.length === 1 ? loose[0] : undefined);
+        if (!found) {
+            throw new CypherError(`${shortName(model, binding.table.ref)} has no column "${name}"; its columns are ${binding.columns
+                .slice(0, 12)
+                .map((c) => c.name)
+                .join(', ')}`, at);
+        }
+        return `${binding.alias}.${quoteIdentifier(found.name)}`;
+    };
+    // What identifies a row of a node: its primary key, or else its physical address.
+    const keyParts = (binding) => {
+        const primary = primaryKeyOf(binding.columns);
+        return primary.length > 0
+            ? primary.map((name) => `${binding.alias}.${quoteIdentifier(name)}`)
+            : [`${binding.alias}.ctid`];
+    };
+    // Relationships become joins, in the order they are written.
+    const from = [];
+    const bound = new Set();
+    const closing = [];
+    const joins = [];
+    const links = [];
+    const used = [];
+    const hiddenTables = [];
+    const addTable = (table, alias, on) => {
+        from.push({ table: qualified(table), alias, on });
+        bound.add(alias);
+    };
+    const connect = (pattern) => {
+        let left = bind(pattern.nodes[0]);
+        if (!bound.has(left.alias))
+            addTable(left.table.ref, left.alias, from.length === 0 ? [] : null);
+        pattern.relationships.forEach((relationship, index) => {
+            const right = bind(pattern.nodes[index + 1]);
+            const steps = routeBetween(model, left.table.ref, right.table.ref, relationship.direction, relationship.hint);
+            links.push([left.name, right.name]);
+            joins.push(`${nodeText(left)} – ${nodeText(right)}: ${steps.length === 1
+                ? `${describeStep(steps[0])}`
+                : `${describeRoute(model, left.table.ref, steps)} (${steps.map((s) => s.key.name).join(', ')})`}`);
+            const holders = [];
+            let at = left.alias;
+            steps.forEach((step, i) => {
+                const last = i === steps.length - 1;
+                const end = stepEnd(step);
+                let next;
+                if (last)
+                    next = right.alias;
+                else {
+                    next = hiddenAlias(end);
+                    hiddenTables.push({
+                        alias: next,
+                        table: model.tables.find((t) => sameTable(t.ref, end)) ?? {
+                            ref: end,
+                            kind: 'table',
+                            estimatedRows: null,
+                        },
+                    });
+                }
+                const mine = step.forward ? step.key.fromColumns : step.key.toColumns;
+                const theirs = step.forward ? step.key.toColumns : step.key.fromColumns;
+                const on = mine.map((c, j) => `${at}.${quoteIdentifier(c)} = ${next}.${quoteIdentifier(theirs[j])}`);
+                holders.push({ key: step.key, holder: step.forward ? at : next });
+                if (bound.has(next))
+                    closing.push(...on);
+                else
+                    addTable(end, next, on);
+                at = next;
+            });
+            used.push(holders);
+            left = right;
+        });
+    };
+    for (const pattern of query.patterns)
+        connect(pattern);
+    // A relationship is used once in a pattern: two that follow the same keys must differ in at least one
+    // of the rows holding them (a chain of keys is one relationship, so it may share some of its rows).
+    const distinct = [];
+    const holdersByKey = (holders) => {
+        const byKey = new Map(holders.map(({ key, holder }) => [foreignKeyId(key), holder]));
+        return byKey.size === holders.length ? byKey : null;
+    };
+    for (let i = 0; i < used.length; i++) {
+        for (let j = i + 1; j < used.length; j++) {
+            const [a, b] = [holdersByKey(used[i]), holdersByKey(used[j])];
+            if (!a || !b || a.size !== b.size || [...a.keys()].some((id) => !b.has(id)))
+                continue;
+            const apart = [
+                ...new Set([...a].flatMap(([id, holder]) => holder === b.get(id) ? [] : [`${holder}.ctid <> ${b.get(id)}.ctid`])),
+            ];
+            distinct.push(apart.length === 0 ? 'FALSE' : apart.length === 1 ? apart[0] : `(${apart.join(' OR ')})`);
+        }
+    }
+    function nodeText(binding) {
+        return `(${binding.anonymous ? '' : binding.name}:${shortName(model, binding.table.ref)})`;
+    }
+    function describeStep(step) {
+        const [a, b] = [step.key.fromColumns.join(', '), step.key.toColumns.join(', ')];
+        return `${shortName(model, step.key.from)}.${a} → ${shortName(model, step.key.to)}.${b} (${step.key.name})`;
+    }
+    // Expressions.
+    const lookup = (name, at) => {
+        const binding = scope.get(name);
+        if (!binding || binding.anonymous) {
+            throw new CypherError(`unknown variable ${name}${order.filter((b) => !b.anonymous).length > 0
+                ? `; the pattern has ${order
+                    .filter((b) => !b.anonymous)
+                    .map((b) => b.name)
+                    .join(', ')}`
+                : ''}`, at);
+        }
+        return binding;
+    };
+    const nodeEquality = (a, b, negate) => {
+        if (!sameTable(a.table.ref, b.table.ref)) {
+            throw new CypherError(`${a.name} (${shortName(model, a.table.ref)}) and ${b.name} (${shortName(model, b.table.ref)}) are rows of different tables, so they cannot be compared`);
+        }
+        const parts = keyParts(a).map((part, i) => `${part} ${negate ? '<>' : '='} ${keyParts(b)[i]}`);
+        return parts.length === 1 ? parts[0] : `(${parts.join(negate ? ' OR ' : ' AND ')})`;
+    };
+    const sqlOf = (expr, emit) => {
+        // Text functions take text, whatever the column is; what already is text is left as it is.
+        const text = (e) => {
+            const sql = sqlOf(e, emit);
+            if (e.kind === 'literal' && typeof e.value === 'string') {
+                return sql.replace(/^(\$\d+)$/, '$1::text');
+            }
+            return e.kind === 'call' && ['lower', 'tolower', 'upper', 'toupper'].includes(e.name)
+                ? sql
+                : `${sql}::text`;
+        };
+        switch (expr.kind) {
+            case 'literal':
+                return emit.value(expr.value);
+            case 'property':
+                return column(lookup(expr.variable, expr.at), expr.column, expr.at);
+            case 'variable':
+                lookup(expr.name, expr.at);
+                throw new CypherError(`${expr.name} is a whole row: compare it only with another row (${expr.name} <> other), or use one of its columns (${expr.name}.${scope.get(expr.name).columns[0]?.name ?? 'id'})`, expr.at);
+            case 'not':
+                return `NOT (${sqlOf(expr.operand, emit)})`;
+            case 'logic':
+                return `(${sqlOf(expr.left, emit)} ${expr.op.toUpperCase()} ${sqlOf(expr.right, emit)})`;
+            case 'null':
+                return `${sqlOf(expr.operand, emit)} IS ${expr.negated ? 'NOT ' : ''}NULL`;
+            case 'in':
+                return expr.list.length === 0
+                    ? 'FALSE'
+                    : `${sqlOf(expr.operand, emit)} IN (${expr.list.map((item) => sqlOf(item, emit)).join(', ')})`;
+            case 'compare': {
+                const { left, right, op } = expr;
+                if (left.kind === 'variable' && right.kind === 'variable') {
+                    if (op !== '=' && op !== '<>') {
+                        throw new CypherError(`rows can only be compared with = and <>, not ${op}`, left.at);
+                    }
+                    return nodeEquality(lookup(left.name, left.at), lookup(right.name, right.at), op === '<>');
+                }
+                const l = sqlOf(left, emit);
+                const compare = (o) => {
+                    switch (o) {
+                        case 'starts':
+                            return `starts_with(${text(left)}, ${text(right)})`;
+                        case 'ends':
+                            return `right(${text(left)}, char_length(${text(right)})) = ${text(right)}`;
+                        case 'contains':
+                            return `strpos(${text(left)}, ${text(right)}) > 0`;
+                        case '=~':
+                            return `${text(left)} ~ ('^(?:' || ${text(right)} || ')$')`;
+                        default:
+                            return `${l} ${o} ${sqlOf(right, emit)}`;
+                    }
+                };
+                return compare(op);
+            }
+            case 'call': {
+                if (AGGREGATES.includes(expr.name))
+                    return aggregate(expr, emit);
+                const args = expr.args.map((arg) => sqlOf(arg, emit));
+                switch (expr.name) {
+                    case 'lower':
+                    case 'tolower':
+                        return `lower(${text(expr.args[0])})`;
+                    case 'upper':
+                    case 'toupper':
+                        return `upper(${text(expr.args[0])})`;
+                    case 'abs':
+                        return `abs(${args[0]})`;
+                    default:
+                        return `coalesce(${args.join(', ')})`;
+                }
+            }
+        }
+    };
+    const aggregate = (call, emit) => {
+        if (call.star)
+            return 'count(*)';
+        const argument = call.args[0];
+        const modifier = call.distinct ? 'DISTINCT ' : '';
+        if (argument.kind === 'variable') {
+            const binding = lookup(argument.name, argument.at);
+            if (call.name === 'collect')
+                return `jsonb_agg(${modifier}to_jsonb(${binding.alias}))`;
+            if (call.name !== 'count') {
+                throw new CypherError(`${call.name}() needs a column, e.g. ${call.name}(${argument.name}.${binding.columns[0]?.name ?? 'id'})`, call.at);
+            }
+            const parts = keyParts(binding);
+            return `count(${modifier}${parts.length === 1 ? parts[0] : `ROW(${parts.join(', ')})`})`;
+        }
+        const sql = sqlOf(argument, emit);
+        return call.name === 'collect'
+            ? `array_agg(${modifier}${sql})`
+            : `${call.name}(${modifier}${sql})`;
+    };
+    // WHERE and the properties written in the nodes.
+    const conditions = (emit) => {
+        const out = [...closing, ...distinct];
+        for (const filter of nodeFilters) {
+            const sql = column(filter.binding, filter.column, filter.at);
+            out.push(filter.value === null ? `${sql} IS NULL` : `${sql} = ${emit.value(filter.value)}`);
+        }
+        for (const where of query.where)
+            out.push(sqlOf(where, emit));
+        return out;
+    };
+    // Properties of nodes: those of unnamed nodes are matched to the binding made for them, in order.
+    const nodeFilters = [];
+    {
+        let unnamed = 0;
+        const anonymousBindings = order.filter((b) => b.anonymous);
+        for (const pattern of query.patterns) {
+            for (const node of pattern.nodes) {
+                const binding = node.variable ? scope.get(node.variable) : anonymousBindings[unnamed++];
+                for (const property of node.properties) {
+                    nodeFilters.push({
+                        binding,
+                        column: property.column,
+                        value: property.value,
+                        at: property.at,
+                    });
+                }
+            }
+        }
+    }
+    // RETURN.
+    const items = query.returns ??
+        order
+            .filter((b) => !b.anonymous)
+            .map((b) => ({ expr: { kind: 'variable', name: b.name, at: 0 }, text: b.name }));
+    if (items.length === 0)
+        throw new CypherError('RETURN * needs named nodes, e.g. (c:Customer)');
+    const aggregated = items.some((item) => hasAggregate(item.expr));
+    const columns = items.map((item) => {
+        const name = item.alias ?? item.text;
+        if (item.expr.kind === 'variable') {
+            const binding = lookup(item.expr.name, item.expr.at);
+            return {
+                name,
+                kind: 'node',
+                variable: binding.name,
+                table: binding.table.ref,
+                aggregate: false,
+            };
+        }
+        return { name, kind: 'value', aggregate: hasAggregate(item.expr) };
+    });
+    const selectOf = (item, emit) => item.expr.kind === 'variable'
+        ? `to_jsonb(${lookup(item.expr.name, item.expr.at).alias})`
+        : sqlOf(item.expr, emit);
+    const groupBy = (emit) => {
+        const out = [];
+        for (const item of items) {
+            if (hasAggregate(item.expr))
+                continue;
+            if (item.expr.kind === 'variable') {
+                const binding = lookup(item.expr.name, item.expr.at);
+                const primary = primaryKeyOf(binding.columns);
+                out.push(...(primary.length > 0 ? keyParts(binding) : [`to_jsonb(${binding.alias})`]));
+            }
+            else if (item.expr.kind !== 'literal')
+                out.push(sqlOf(item.expr, emit));
+        }
+        return out;
+    };
+    const orderTerm = (term, emit) => {
+        const named = items.findIndex((item) => (item.alias ?? item.text) === term.text ||
+            (term.expr.kind === 'variable' && item.alias === term.expr.name));
+        const sql = named >= 0 ? quoteIdentifier(columns[named].name) : orderExpr(term.expr, emit);
+        return `${sql}${term.descending ? ' DESC' : ''}`;
+    };
+    const orderExpr = (expr, emit) => {
+        if (expr.kind === 'variable') {
+            const binding = lookup(expr.name, expr.at);
+            return keyParts(binding).join(', ');
+        }
+        return sqlOf(expr, emit);
+    };
+    const limit = query.limit === undefined ? undefined : Math.min(query.limit, MAX_ROWS);
+    const rowCap = limit ?? DEFAULT_ROWS;
+    const build = (inline) => {
+        const emit = emitter(inline);
+        const select = items.map((item, i) => `${selectOf(item, emit)} AS ${quoteIdentifier(columns[i].name)}`);
+        const lines = [`SELECT ${query.distinct ? 'DISTINCT ' : ''}${select.join(',\n       ')}`];
+        const [first, ...rest] = from;
+        lines.push(`FROM ${first.table} AS ${first.alias}`);
+        for (const entry of rest) {
+            lines.push(entry.on === null
+                ? `CROSS JOIN ${entry.table} AS ${entry.alias}`
+                : `JOIN ${entry.table} AS ${entry.alias} ON ${entry.on.join(' AND ')}`);
+        }
+        const where = conditions(emit);
+        if (where.length > 0)
+            lines.push(`WHERE ${where.join('\n  AND ')}`);
+        if (aggregated) {
+            const group = groupBy(emit);
+            if (group.length > 0)
+                lines.push(`GROUP BY ${group.join(', ')}`);
+        }
+        if (query.orderBy.length > 0)
+            lines.push(`ORDER BY ${query.orderBy.map((term) => orderTerm(term, emit)).join(', ')}`);
+        if (limit !== undefined)
+            lines.push(`LIMIT ${limit}`);
+        if (query.skip)
+            lines.push(`OFFSET ${query.skip}`);
+        return { text: lines.join('\n'), values: emit.values };
+    };
+    const param = build(false);
+    let display = build(true).text;
+    if (limit === undefined)
+        display += `\n-- only the first ${DEFAULT_ROWS} rows are read`;
+    // Parts of the pattern that nothing joins: variables linked by a relationship, or compared in WHERE.
+    const parent = new Map([...scope.keys()].map((name) => [name, name]));
+    const root = (name) => {
+        let at = name;
+        while (parent.get(at) !== at)
+            at = parent.get(at);
+        return at;
+    };
+    const join = (a, b) => parent.set(root(a), root(b));
+    for (const [a, b] of links)
+        join(a, b);
+    for (const where of query.where) {
+        const names = [...variablesIn(where)].filter((name) => scope.has(name));
+        for (const name of names.slice(1))
+            join(names[0], name);
+    }
+    const filteredAliases = new Set();
+    for (const filter of nodeFilters)
+        filteredAliases.add(filter.binding.alias);
+    for (const where of query.where) {
+        for (const name of variablesIn(where))
+            if (scope.has(name))
+                filteredAliases.add(scope.get(name).alias);
+    }
+    const facts = {
+        tables: [
+            ...order.map((b) => ({
+                alias: b.alias,
+                table: b.table.ref,
+                estimatedRows: b.table.estimatedRows,
+                passThrough: false,
+                filtered: filteredAliases.has(b.alias),
+            })),
+            ...hiddenTables.map((h) => ({
+                alias: h.alias,
+                table: h.table.ref,
+                estimatedRows: h.table.estimatedRows,
+                passThrough: true,
+                filtered: false,
+            })),
+        ],
+        crossJoins: new Set([...scope.keys()].map(root)).size - 1,
+        aggregated,
+        ordered: query.orderBy.length > 0,
+        limit: limit ?? null,
+    };
+    return {
+        sql: param.text,
+        values: param.values,
+        display,
+        columns,
+        joins,
+        facts,
+        rowCap,
+        links,
+    };
+}
+// Postgres's cost units are arbitrary, but about 10 000 is a few milliseconds' work on a typical server.
+const COST_MEDIUM = 50_000;
+const COST_HIGH = 1_000_000;
+const ROWS_MEDIUM = 1_000_000;
+const ROWS_HIGH = 20_000_000;
+const BIG_TABLE = 100_000;
+export function compact(n) {
+    if (n >= 1e9)
+        return `${(n / 1e9).toFixed(1)}B`;
+    if (n >= 1e6)
+        return `${(n / 1e6).toFixed(1)}M`;
+    if (n >= 1e3)
+        return `${(n / 1e3).toFixed(1)}k`;
+    return String(Math.round(n));
+}
+const maxJoinRows = (plan) => {
+    const own = /Join|Nested Loop/.test(plan['Node Type']) ? plan['Plan Rows'] : 0;
+    return Math.max(own, ...(plan.Plans ?? []).map(maxJoinRows));
+};
+export function assessComplexity(facts, plan) {
+    const warnings = [];
+    const passThrough = facts.tables.filter((t) => t.passThrough);
+    if (facts.crossJoins > 0) {
+        warnings.push({
+            level: 'high',
+            message: `The pattern has ${facts.crossJoins + 1} parts that nothing joins, so every row of one is paired with every row of the others (a cross join). Connect them with a relationship or a WHERE condition.`,
+        });
+    }
+    // Many joins matter when the planner does not say they are cheap.
+    if (facts.tables.length >= 5 && (!plan || plan['Total Cost'] >= COST_MEDIUM / 2)) {
+        warnings.push({
+            level: facts.tables.length >= 9 ? 'high' : 'medium',
+            message: `Joins ${facts.tables.length} tables${passThrough.length > 0 ? `, ${passThrough.length} of them only to connect nodes (${[...new Set(passThrough.map((t) => t.table.name))].join(', ')})` : ''}.`,
+        });
+    }
+    const biggest = Math.max(0, ...facts.tables.map((t) => t.estimatedRows ?? 0));
+    if ((facts.aggregated || facts.ordered) &&
+        biggest >= BIG_TABLE &&
+        !facts.tables.some((t) => t.filtered)) {
+        warnings.push({
+            level: 'medium',
+            message: `${facts.aggregated ? 'Grouping' : 'Sorting'} needs every matching row before LIMIT can cut the result, and nothing narrows the tables (the largest has about ${compact(biggest)} rows). Filter with WHERE or a {property: value} on a node.`,
+        });
+    }
+    let cost = null;
+    let joinRows = null;
+    if (plan) {
+        cost = plan['Total Cost'];
+        joinRows = maxJoinRows(plan);
+        if (cost >= COST_MEDIUM) {
+            warnings.push({
+                level: cost >= COST_HIGH ? 'high' : 'medium',
+                message: `Postgres estimates a cost of ${compact(cost)}${cost >= COST_HIGH ? ', which can take a long time' : ', which may take a few seconds'}.`,
+            });
+        }
+        if (joinRows >= ROWS_MEDIUM) {
+            warnings.push({
+                level: joinRows >= ROWS_HIGH ? 'high' : 'medium',
+                message: `A join in the plan is expected to produce about ${compact(joinRows)} rows.`,
+            });
+        }
+    }
+    const level = warnings.some((w) => w.level === 'high')
+        ? 'high'
+        : warnings.length > 0
+            ? 'medium'
+            : 'low';
+    return {
+        level,
+        warnings,
+        cost,
+        joinRows,
+        tables: facts.tables.length,
+        passThrough: passThrough.length,
+    };
+}
+const TITLE_COLUMNS = [
+    'name',
+    'title',
+    'label',
+    'full_name',
+    'display_name',
+    'username',
+    'email',
+    'sku',
+    'code',
+    'slug',
+    'description',
+];
+const cellOf = (value) => value === null || value === undefined
+    ? null
+    : typeof value === 'object'
+        ? JSON.stringify(value)
+        : String(value);
+/** The node a returned row (as JSON) is: its id from the primary key, and a label to show it by. */
+function identify(table, cell, model) {
+    const parsed = JSON.parse(cell);
+    const data = {};
+    for (const [name, value] of Object.entries(parsed))
+        data[name] = cellOf(value);
+    const columns = model.columns.get(tableLabel(table)) ?? [];
+    const primary = primaryKeyOf(columns);
+    const key = {};
+    let id;
+    if (primary.length > 0) {
+        for (const name of primary)
+            key[name] = data[name] ?? null;
+        id = nodeId(table, primary.map((name) => data[name] ?? ''));
+    }
+    else {
+        id = nodeId(table, `~${createHash('sha1').update(cell).digest('hex').slice(0, 12)}`);
+    }
+    const title = TITLE_COLUMNS.map((name) => columns.find((c) => c.name === name)).find((c) => c && /char|text/.test(c.type) && data[c.name])?.name;
+    return { id, table, label: title ? data[title] : keyLabel(key), key, row: data };
+}
+/** The graph of a result: a node for each row returned, linked as the pattern links them. */
+export function graphOf(compiled, rows, model) {
+    const nodes = new Map();
+    const edges = new Map();
+    const nodeColumns = compiled.columns.flatMap((column, index) => column.kind === 'node' ? [{ column, index }] : []);
+    const weightAt = compiled.columns.findIndex((column) => column.kind === 'value' && column.aggregate);
+    const returned = new Set(nodeColumns.map(({ column }) => column.variable));
+    // Which returned variables are linked, through variables that are not returned.
+    const near = new Map();
+    for (const [a, b] of compiled.links) {
+        if (!near.has(a))
+            near.set(a, new Set());
+        if (!near.has(b))
+            near.set(b, new Set());
+        near.get(a).add(b);
+        near.get(b).add(a);
+    }
+    const pairs = [];
+    for (const start of returned) {
+        const seen = new Set([start]);
+        const queue = [start];
+        while (queue.length > 0) {
+            for (const next of near.get(queue.shift()) ?? []) {
+                if (seen.has(next))
+                    continue;
+                seen.add(next);
+                if (returned.has(next)) {
+                    if (start < next)
+                        pairs.push([start, next]);
+                }
+                else
+                    queue.push(next);
+            }
+        }
+    }
+    for (const row of rows) {
+        const ids = new Map();
+        for (const { column, index } of nodeColumns) {
+            const cell = row[index];
+            if (cell === null || cell === undefined)
+                continue;
+            const node = identify(column.table, cell, model);
+            // The unmatched side of an outer join is a row of nothing but nulls, not a row.
+            if (Object.values(node.row).every((value) => value === null))
+                continue;
+            ids.set(column.variable, node.id);
+            if (!nodes.has(node.id))
+                nodes.set(node.id, node);
+        }
+        for (const [a, b] of pairs) {
+            const [from, to] = [ids.get(a), ids.get(b)];
+            if (!from || !to || from === to)
+                continue;
+            const [low, high] = from < to ? [from, to] : [to, from];
+            const id = `edge:${low}|${high}`;
+            if (!edges.has(id))
+                edges.set(id, {
+                    id,
+                    from: low,
+                    to: high,
+                    weight: weightAt >= 0 ? (row[weightAt] ?? null) : null,
+                });
+        }
+    }
+    return { nodes: [...nodes.values()], edges: [...edges.values()] };
+}
+export function parseCypherRequest(body) {
+    const entry = body;
+    if (typeof entry?.query !== 'string')
+        throw new CypherError('send {"query", "run"?, "force"?}');
+    if (entry.query.length > 20_000)
+        throw new CypherError('the query is too long');
+    return { query: entry.query, run: entry.run === true, force: entry.force === true };
+}
+const readPlan = async (session, sql, values) => {
+    const [row] = await session.rows(`EXPLAIN (FORMAT JSON) ${sql}`, values);
+    const raw = row?.['QUERY PLAN'];
+    const plan = (typeof raw === 'string' ? JSON.parse(raw) : raw);
+    if (!plan?.[0]?.Plan)
+        throw new Error('Postgres did not return a plan');
+    return plan[0].Plan;
+};
+/**
+ * Translates a query, has Postgres plan it (which runs nothing), and, when asked, runs it: in a read only
+ * transaction with a time limit, unless the plan is judged heavy and `force` is not set.
+ */
+export async function runCypher(session, request) {
+    const query = parseCypher(request.query);
+    const model = await loadCypherModel(session, query);
+    const compiled = compileCypher(query, model);
+    const plan = await readPlan(session, compiled.sql, compiled.values).catch((error) => {
+        throw new CypherError(`Postgres cannot plan the generated SQL: ${describeQueryError(error)}`);
+    });
+    const complexity = assessComplexity(compiled.facts, plan);
+    const base = {
+        sql: compiled.display,
+        joins: compiled.joins,
+        complexity,
+        rowCap: compiled.rowCap,
+    };
+    const columns = compiled.columns.map((column) => ({
+        name: column.name,
+        type: column.kind === 'node' ? 'row' : '',
+        node: column.kind === 'node',
+    }));
+    if (!request.run || (complexity.level === 'high' && !request.force)) {
+        return {
+            ...base,
+            ran: false,
+            columns,
+            rows: [],
+            truncated: false,
+            nodes: [],
+            edges: [],
+            durationMs: null,
+        };
+    }
+    const timeout = Math.floor(request.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    await session.run('BEGIN READ ONLY');
+    let result;
+    try {
+        await session.run(`SET LOCAL statement_timeout = ${timeout}`);
+        result = await session.run(compiled.sql, compiled.values, { maxRows: compiled.rowCap });
+    }
+    catch (error) {
+        if (error?.code === '57014') {
+            throw new CypherError(`The query was stopped after ${Math.round(timeout / 1000)} s. Narrow it with WHERE or a {property: value} on a node, or add a LIMIT.`);
+        }
+        throw new CypherError(describeQueryError(error));
+    }
+    finally {
+        await session.run('ROLLBACK').catch(() => undefined);
+    }
+    const graph = graphOf(compiled, result.rows, model);
+    return {
+        ...base,
+        ran: true,
+        columns: result.columns.map((column, i) => ({
+            name: compiled.columns[i]?.name ?? column.name,
+            type: compiled.columns[i]?.kind === 'node' ? 'row' : column.type,
+            node: compiled.columns[i]?.kind === 'node',
+        })),
+        // A node is shown in the table by its label.
+        rows: result.rows.map((row) => row.map((cell, i) => {
+            const column = compiled.columns[i];
+            return cell !== null && column?.kind === 'node'
+                ? identify(column.table, cell, model).label
+                : cell;
+        })),
+        truncated: result.truncated,
+        nodes: graph.nodes,
+        edges: graph.edges,
+        durationMs: result.durationMs,
+    };
+}