@query-doctor/core 0.4.1-rc.2 → 0.4.1-rc.4

package/dist/index.cjs

@@ -56,7 +56,7 @@ const SPATIAL_FUNCTIONS = new Set([
 	"st_overlaps",
 	"st_touches"
 ]);
-const JSONB_EXTRACTION_OPS = new Set([
+const JSONB_EXTRACTION_OPS$1 = new Set([
 	"->>",
 	"->",
 	"#>>",
@@ -74,7 +74,7 @@ function getAExprOpName(node) {
 function findExtractionExpr(node) {
 	if (is$1(node, "A_Expr")) {
 		const op = getAExprOpName(node);
-		if (op && JSONB_EXTRACTION_OPS.has(op)) {
+		if (op && JSONB_EXTRACTION_OPS$1.has(op)) {
 			if (node.A_Expr.lexpr && hasColumnRefInNode(node.A_Expr.lexpr)) return node;
 			return null;
 		}
@@ -144,7 +144,7 @@ const findJsonbExtractionInWhere = (whereClause) => {
 	function walk(node) {
 		if (is$1(node, "A_Expr")) {
 			const op = getAExprOpName(node);
-			if (op && JSONB_EXTRACTION_OPS.has(op)) return;
+			if (op && JSONB_EXTRACTION_OPS$1.has(op)) return;
 			if (node.A_Expr.lexpr) emit(node.A_Expr.lexpr);
 			if (node.A_Expr.rexpr) emit(node.A_Expr.rexpr);
 			return;
@@ -400,6 +400,17 @@ function parseNudges(node, stack) {
 			location: node.FuncCall.location
 		});
 	}
+	if (is$1(node, "FuncCall")) {
+		if (stack.some((item) => item === "whereClause") && node.FuncCall.args) {
+			const name = getFuncName(node);
+			if (name && JSONB_SET_RETURNING_FUNCTIONS.has(name) && containsColumnRef(node.FuncCall.args)) nudges.push({
+				kind: "CONSIDER_JSONB_CONTAINMENT_OPERATOR",
+				severity: "INFO",
+				message: "JSONB set-returning functions (e.g. jsonb_array_elements) cannot be used as an index access path. If the query checks for containment or key existence, GIN-compatible operators (@>, ?, ?|, ?&, @?, @@) may allow index usage.",
+				location: node.FuncCall.location
+			});
+		}
+	}
 	if (is$1(node, "A_Expr") && node.A_Expr.kind === "AEXPR_OP" && node.A_Expr.name && node.A_Expr.name.length > 0) {
 		const opNode = node.A_Expr.name[0];
 		const op = is$1(opNode, "String") ? opNode.String.sval : null;
@@ -567,6 +578,23 @@ function containsAggregate(node) {
 	for (const child of Object.values(node)) if (containsAggregate(child)) return true;
 	return false;
 }
+const JSONB_SET_RETURNING_FUNCTIONS = new Set([
+	"jsonb_array_elements",
+	"json_array_elements",
+	"jsonb_array_elements_text",
+	"json_array_elements_text",
+	"jsonb_each",
+	"json_each",
+	"jsonb_each_text",
+	"json_each_text"
+]);
+function getFuncName(node) {
+	const names = node.FuncCall.funcname;
+	if (!names || names.length === 0) return null;
+	const last = names[names.length - 1];
+	if (isANode$1(last) && is$1(last, "String") && last.String.sval) return last.String.sval;
+	return null;
+}
 function getLastColumnRefField(columnRef) {
 	const fields = columnRef.ColumnRef.fields;
 	if (!fields || fields.length === 0) return null;
@@ -752,6 +780,20 @@ function _defineProperty(e, r, t) {
 
 //#endregion
 //#region src/sql/walker.ts
+const JSONB_EXTRACTION_OPS = new Set(["->", "->>"]);
+const COMPARISON_OPS = new Set([
+	"=",
+	"<>",
+	"!=",
+	"<",
+	"<=",
+	">",
+	">=",
+	"~~",
+	"~~*",
+	"!~~",
+	"!~~*"
+]);
 /**
 * Walks the AST of a sql query and extracts query metadata.
 * This pattern is used to segregate the mutable state that's more common for the
@@ -832,7 +874,7 @@ var Walker = class Walker {
 			}
 			if (is(node, "A_Expr") && node.A_Expr.kind === "AEXPR_OP") {
 				const opName = node.A_Expr.name?.[0] && is(node.A_Expr.name[0], "String") && node.A_Expr.name[0].String.sval;
-				if (opName && (opName === "@>" || opName === "?" || opName === "?|" || opName === "?&")) {
+				if (opName && (opName === "@>" || opName === "?" || opName === "?|" || opName === "?&" || opName === "@@" || opName === "@?")) {
 					const jsonbOperator = opName;
 					if (node.A_Expr.lexpr && is(node.A_Expr.lexpr, "ColumnRef")) this.add(node.A_Expr.lexpr, { jsonbOperator });
 					if (node.A_Expr.rexpr && is(node.A_Expr.rexpr, "ColumnRef")) this.add(node.A_Expr.rexpr, { jsonbOperator });
@@ -842,6 +884,11 @@ var Walker = class Walker {
 					if (node.A_Expr.lexpr && is(node.A_Expr.lexpr, "ColumnRef")) this.add(node.A_Expr.lexpr, { gistOperator });
 					if (node.A_Expr.rexpr && is(node.A_Expr.rexpr, "ColumnRef")) this.add(node.A_Expr.rexpr, { gistOperator });
 				}
+				if (opName && COMPARISON_OPS.has(opName)) for (const operand of [node.A_Expr.lexpr, node.A_Expr.rexpr]) {
+					if (!operand) continue;
+					const extraction = extractJsonbPath(operand);
+					if (extraction) this.add(extraction.columnRef, { jsonbExtraction: extraction.expression });
+				}
 			}
 			if (is(node, "ColumnRef")) {
 				for (let i = 0; i < stack.length; i++) {
@@ -926,6 +973,7 @@ var Walker = class Walker {
 		if (options?.where) ref.where = options.where;
 		if (options?.jsonbOperator) ref.jsonbOperator = options.jsonbOperator;
 		if (options?.gistOperator) ref.gistOperator = options.gistOperator;
+		if (options?.jsonbExtraction) ref.jsonbExtraction = options.jsonbExtraction;
 		this.highlights.push(ref);
 	}
 	/**
@@ -993,6 +1041,57 @@ function isANode(node) {
 	const keys = Object.keys(node);
 	return keys.length === 1 && /^[A-Z]/.test(keys[0]);
 }
+/**
+* Given an operand of a comparison (e.g. the left side of `=`), check whether
+* it is a JSONB path extraction expression such as `data->>'email'` or
+* `(data->>'age')::int`.  If so, return the root ColumnRef (for the walker to
+* register) and the full expression string (for use in the expression index).
+*
+* Handles:
+* - `data->>'email'`            — simple extraction
+* - `(data->>'age')::int`       — extraction with cast
+* - `data->'addr'->>'city'`     — chained extraction
+* - `t.data->>'email'`          — table-qualified (strips qualifier from expression)
+*/
+function extractJsonbPath(node) {
+	let exprNode = node;
+	if (is(exprNode, "TypeCast") && exprNode.TypeCast.arg) exprNode = exprNode.TypeCast.arg;
+	if (!is(exprNode, "A_Expr") || exprNode.A_Expr.kind !== "AEXPR_OP") return;
+	const innerOp = exprNode.A_Expr.name?.[0] && is(exprNode.A_Expr.name[0], "String") && exprNode.A_Expr.name[0].String.sval;
+	if (!innerOp || !JSONB_EXTRACTION_OPS.has(innerOp)) return;
+	const rootCol = findRootColumnRef(exprNode);
+	if (!rootCol) return;
+	const cloned = JSON.parse(JSON.stringify(node));
+	stripTableQualifiers(cloned);
+	return {
+		columnRef: rootCol,
+		expression: (0, pgsql_deparser.deparseSync)(cloned)
+	};
+}
+/**
+* Walk the left side of a chain of `->` / `->>` operators to find the
+* root ColumnRef (the JSONB column itself).
+*/
+function findRootColumnRef(node) {
+	if (is(node, "ColumnRef")) return node;
+	if (is(node, "A_Expr") && node.A_Expr.lexpr) return findRootColumnRef(node.A_Expr.lexpr);
+	if (is(node, "TypeCast") && node.TypeCast.arg) return findRootColumnRef(node.TypeCast.arg);
+}
+/**
+* Remove table/schema qualifiers from ColumnRef nodes inside the
+* expression so the deparsed expression contains only the column name.
+* e.g.  `t.data->>'email'`  →  `data->>'email'`
+*/
+function stripTableQualifiers(node) {
+	if (typeof node !== "object" || node === null) return;
+	if ("ColumnRef" in node && node.ColumnRef?.fields) {
+		const fields = node.ColumnRef.fields;
+		if (fields.length > 1) node.ColumnRef.fields = [fields[fields.length - 1]];
+		return;
+	}
+	for (const value of Object.values(node)) if (Array.isArray(value)) for (const item of value) stripTableQualifiers(item);
+	else if (typeof value === "object" && value !== null) stripTableQualifiers(value);
+}
 
 //#endregion
 //#region src/sql/analyzer.ts
@@ -1034,10 +1133,11 @@ var Analyzer = class {
 			const queryBeforeMatch = currQuery.slice(0, highlight.position.start);
 			const queryAfterToken = currQuery.slice(highlight.position.end);
 			currQuery = `${queryBeforeMatch}${color(queryRepr)}${this.colorizeKeywords(queryAfterToken, color)}`;
-			if (indexRepresentations.has(queryRepr)) skip = true;
+			const reprKey = highlight.jsonbExtraction ? `${queryRepr}::${highlight.jsonbExtraction}` : queryRepr;
+			if (indexRepresentations.has(reprKey)) skip = true;
 			if (!skip) {
 				indexesToCheck.push(highlight);
-				indexRepresentations.add(queryRepr);
+				indexRepresentations.add(reprKey);
 			}
 		}
 		const referencedTables = [];
@@ -1070,7 +1170,8 @@ var Analyzer = class {
 		const allIndexes = [];
 		const seenIndexes = /* @__PURE__ */ new Set();
 		function addIndex(index) {
-			const key = `"${index.schema}":"${index.table}":"${index.column}"`;
+			const extractionSuffix = index.jsonbExtraction ? `:"${index.jsonbExtraction}"` : "";
+			const key = `"${index.schema}":"${index.table}":"${index.column}"${extractionSuffix}`;
 			if (seenIndexes.has(key)) return;
 			seenIndexes.add(key);
 			allIndexes.push(index);
@@ -1095,6 +1196,7 @@ var Analyzer = class {
 					if (colReference.where) index.where = colReference.where;
 					if (colReference.jsonbOperator) index.jsonbOperator = colReference.jsonbOperator;
 					if (colReference.gistOperator) index.gistOperator = colReference.gistOperator;
+					if (colReference.jsonbExtraction) index.jsonbExtraction = colReference.jsonbExtraction;
 					addIndex(index);
 				}
 			} else if (tableReference) {
@@ -1112,6 +1214,7 @@ var Analyzer = class {
 					if (colReference.where) index.where = colReference.where;
 					if (colReference.jsonbOperator) index.jsonbOperator = colReference.jsonbOperator;
 					if (colReference.gistOperator) index.gistOperator = colReference.gistOperator;
+					if (colReference.jsonbExtraction) index.jsonbExtraction = colReference.jsonbExtraction;
 					addIndex(index);
 				}
 			} else if (fullReference) {
@@ -1125,6 +1228,7 @@ var Analyzer = class {
 				if (colReference.where) index.where = colReference.where;
 				if (colReference.jsonbOperator) index.jsonbOperator = colReference.jsonbOperator;
 				if (colReference.gistOperator) index.gistOperator = colReference.gistOperator;
+				if (colReference.jsonbExtraction) index.jsonbExtraction = colReference.jsonbExtraction;
 				addIndex(index);
 			} else {
 				console.error("Column reference has too many parts. The query is malformed", colReference);
@@ -1670,7 +1774,8 @@ var IndexOptimizer = class IndexOptimizer {
 	* Derive the list of indexes [tableA(X, Y, Z), tableB(H, I, J)]
 	**/
 	indexesToCreate(rootCandidates) {
-		const btreeCandidates = rootCandidates.filter((c) => !c.jsonbOperator && !c.gistOperator);
+		const expressionCandidates = rootCandidates.filter((c) => c.jsonbExtraction);
+		const btreeCandidates = rootCandidates.filter((c) => !c.jsonbOperator && !c.gistOperator && !c.jsonbExtraction);
 		const ginCandidates = rootCandidates.filter((c) => c.jsonbOperator);
 		const gistCandidates = rootCandidates.filter((c) => c.gistOperator);
 		const nextStage = [];
@@ -1702,7 +1807,7 @@ var IndexOptimizer = class IndexOptimizer {
 			const { schema: rawSchema, table: rawTable, column, operators } = group;
 			const schema = PgIdentifier.fromString(rawSchema);
 			const table = PgIdentifier.fromString(rawTable);
-			const opclass = operators.some((op) => op === "?" || op === "?|" || op === "?&") ? void 0 : "jsonb_path_ops";
+			const opclass = operators.some((op) => op !== "@>") ? void 0 : "jsonb_path_ops";
 			if (this.ginIndexAlreadyExists(table.toString(), column)) continue;
 			const indexName = this.indexName();
 			const candidate = {
@@ -1752,6 +1857,28 @@ var IndexOptimizer = class IndexOptimizer {
 				indexMethod: "gist"
 			});
 		}
+		const seenExpressions = /* @__PURE__ */ new Set();
+		for (const candidate of expressionCandidates) {
+			const expression = candidate.jsonbExtraction;
+			const key = `${candidate.schema}.${candidate.table}.${expression}`;
+			if (seenExpressions.has(key)) continue;
+			seenExpressions.add(key);
+			const schema = PgIdentifier.fromString(candidate.schema);
+			const table = PgIdentifier.fromString(candidate.table);
+			const indexName = this.indexName();
+			const definition = this.toExpressionDefinition({
+				table,
+				schema,
+				expression
+			});
+			nextStage.push({
+				name: indexName,
+				schema: schema.toString(),
+				table: table.toString(),
+				columns: [candidate],
+				definition
+			});
+		}
 		return nextStage;
 	}
 	toDefinition({ schema, table, columns }) {
@@ -1788,6 +1915,12 @@ var IndexOptimizer = class IndexOptimizer {
 		else fullyQualifiedTable = PgIdentifier.fromParts(schema, table);
 		return `${fullyQualifiedTable} using gist (${column})`;
 	}
+	toExpressionDefinition({ schema, table, expression }) {
+		let fullyQualifiedTable;
+		if (schema.toString() === "public") fullyQualifiedTable = table;
+		else fullyQualifiedTable = PgIdentifier.fromParts(schema, table);
+		return `${fullyQualifiedTable}((${expression}))`;
+	}
 	groupGinCandidatesByColumn(candidates) {
 		const groups = /* @__PURE__ */ new Map();
 		for (const c of candidates) {