@query-doctor/core 0.5.0 → 0.6.0

package/dist/index.cjs

@@ -229,6 +229,17 @@ function parseNudges(node, stack) {
 			});
 		}
 	}
+	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")) {
 		if (node.A_Expr.kind === "AEXPR_IN") {
 			let list;
@@ -316,6 +327,23 @@ function getStringConstantValue(node) {
 	if (isANode$1(node) && is$1(node, "A_Const") && node.A_Const.sval) return node.A_Const.sval.sval || null;
 	return null;
 }
+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;
@@ -458,6 +486,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
@@ -538,11 +580,16 @@ 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 });
 				}
+				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++) {
@@ -626,6 +673,7 @@ var Walker = class Walker {
 		if (options?.sort) ref.sort = options.sort;
 		if (options?.where) ref.where = options.where;
 		if (options?.jsonbOperator) ref.jsonbOperator = options.jsonbOperator;
+		if (options?.jsonbExtraction) ref.jsonbExtraction = options.jsonbExtraction;
 		this.highlights.push(ref);
 	}
 	/**
@@ -693,6 +741,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
@@ -734,10 +833,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 = [];
@@ -770,7 +870,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);
@@ -794,6 +895,7 @@ var Analyzer = class {
 					if (colReference.sort) index.sort = colReference.sort;
 					if (colReference.where) index.where = colReference.where;
 					if (colReference.jsonbOperator) index.jsonbOperator = colReference.jsonbOperator;
+					if (colReference.jsonbExtraction) index.jsonbExtraction = colReference.jsonbExtraction;
 					addIndex(index);
 				}
 			} else if (tableReference) {
@@ -810,6 +912,7 @@ var Analyzer = class {
 					if (colReference.sort) index.sort = colReference.sort;
 					if (colReference.where) index.where = colReference.where;
 					if (colReference.jsonbOperator) index.jsonbOperator = colReference.jsonbOperator;
+					if (colReference.jsonbExtraction) index.jsonbExtraction = colReference.jsonbExtraction;
 					addIndex(index);
 				}
 			} else if (fullReference) {
@@ -822,6 +925,7 @@ var Analyzer = class {
 				if (colReference.sort) index.sort = colReference.sort;
 				if (colReference.where) index.where = colReference.where;
 				if (colReference.jsonbOperator) index.jsonbOperator = colReference.jsonbOperator;
+				if (colReference.jsonbExtraction) index.jsonbExtraction = colReference.jsonbExtraction;
 				addIndex(index);
 			} else {
 				console.error("Column reference has too many parts. The query is malformed", colReference);
@@ -1372,7 +1476,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);
+		const expressionCandidates = rootCandidates.filter((c) => c.jsonbExtraction);
+		const btreeCandidates = rootCandidates.filter((c) => !c.jsonbOperator && !c.jsonbExtraction);
 		const ginCandidates = rootCandidates.filter((c) => c.jsonbOperator);
 		const nextStage = [];
 		const permutedIndexes = this.groupPotentialIndexColumnsByTable(btreeCandidates);
@@ -1403,7 +1508,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 = {
@@ -1427,6 +1532,28 @@ var IndexOptimizer = class IndexOptimizer {
 				opclass
 			});
 		}
+		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 }) {
@@ -1457,6 +1584,12 @@ var IndexOptimizer = class IndexOptimizer {
 		const opclassSuffix = opclass ? ` ${opclass}` : "";
 		return `${fullyQualifiedTable} using gin (${column}${opclassSuffix})`;
 	}
+	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) {
@@ -2116,6 +2249,7 @@ var Statistics = class Statistics {
           ON n.oid = cl.relnamespace
         WHERE c.table_name NOT LIKE 'pg_%'
           AND n.nspname <> 'information_schema'
+          AND n.nspname NOT IN ('tiger', 'tiger_data', 'topology')
           AND c.table_name NOT IN ('pg_stat_statements', 'pg_stat_statements_info')
         GROUP BY c.table_name, c.table_schema, cl.reltuples, cl.relpages, cl.relallvisible, n.nspname
       ),
@@ -2137,6 +2271,7 @@ var Statistics = class Statistics {
         JOIN pg_namespace n ON n.oid = t.relnamespace
         WHERE t.relname NOT LIKE 'pg_%'
           AND n.nspname <> 'information_schema'
+          AND n.nspname NOT IN ('tiger', 'tiger_data', 'topology')
         GROUP BY t.relname
       )
       SELECT json_agg(