Repository navigation
Description
GV005 function-on-filter-column flags WHERE LOWER(event_type) = 'x' because the function hides the raw column from partition pruning, clustering and min/max statistics. The same wrapper inside a join condition does the same harm (the engine cannot use clustering, indexes or key statistics on the wrapped side, and often cannot prune), but only WHERE is looked at:
gulliver lint "SELECT e.user_id FROM events e JOIN users u ON LOWER(e.user_id) = LOWER(u.id) LIMIT 10"
# No scale problems found.
gulliver lint "SELECT e.user_id FROM events e JOIN users u ON CAST(e.user_id AS VARCHAR) = u.id LIMIT 10"
# No scale problems found.
gulliver lint "SELECT user_id FROM events WHERE LOWER(event_type) = 'purchase' LIMIT 10"
# warn GV005 function-on-filter-column: The filter wraps event_type in a function or calculation, ...The CAST(int AS VARCHAR) = varchar_key case is the most common real one: a type mismatch that someone papered over with a cast on the big table's key.
Before and after (the fix is usually to clean the key once, upstream, or to cast the small side):
-- before: the big table's key is wrapped
SELECT e.user_id FROM events e JOIN users u ON CAST(e.user_id AS VARCHAR) = u.id_text
-- after: cast the small side, or store the key with the right type
SELECT e.user_id FROM events e JOIN users u ON e.user_id = CAST(u.id_text AS BIGINT)This one cannot be rewritten automatically (casts can fail or change which rows match), so it is a finding without an autofix.
Checked on current main (c48adf8): the 18 rules (gulliver rules) have nothing for this and no open or closed issue asks for it. (Lint rule GV019 is taken by the open issue #125 and the issue for = NULL is open too, so take the next free id when you start.)
Suggested direction
- New rule
function-on-join-key, severityinfo(engines differ: some hash on expressions without trouble, and the lint cannot see the table sizes), messageThe join key e.user_id is wrapped in a function or cast, so clustering, indexes and statistics on that side cannot be used.and the fixCompare the raw columns, cast the smaller side, or fix the column type upstream. - Look at every equality in a
JOIN ... ONwhere one side is a function or cast of columns from one table (exp.Func,exp.Cast,::) and the other side refers to a column of another table. Do not flag:ON a.x = b.y(no function),USING (...), a function that wraps only a literal (b.d = DATE '2024-01-01'), and non-equality orORconditions (GV008 owns those) - Report the node position like the other rules. One finding per join condition is enough
- Reuse as much of GV005's column and function detection as possible; if it needs a small refactor to share, do that first in its own commit
Where to start
src/gulliver/lint.py: the join checks (GV003 / GV008, around line 247) and GV005 (around line 309) are the two blocks to combine;_join_condition(join)(around line 93) and_aliases_in(expr)(around line 97) already give the pieces for "which tables does this side use"src/gulliver/lint_report.py(around line 73):RULE_DOCSforgulliver rules;README.md(the lint rule table around line 747) andskills/gulliver/SKILL.md(rule table around line 83)- Tests:
tests/test_lint.py
How to test
gulliver lint "SELECT e.user_id FROM events e JOIN users u ON LOWER(e.user_id) = LOWER(u.id) LIMIT 10" # new finding
gulliver lint "SELECT e.user_id FROM events e JOIN users u ON e.user_id = u.id LIMIT 10" # clean
gulliver lint "SELECT e.user_id FROM events e JOIN users u USING (user_id) LIMIT 10" # clean
gulliver rules
pytest tests/test_lint.pyDone when
- The rule fires for
LOWER(a.x) = b.y,CAST(a.x AS VARCHAR) = b.y,a.x::text = b.yandDATE(a.ts) = b.din aJOIN ... ON(a test for each, and one that parses in each of the four dialects where the syntax exists) - It does not fire for a plain
a.x = b.y,USING, a function that only wraps a literal, or a function inWHERE(GV005 owns that, no double report) - It is in
gulliver rules,rule_docs(), the README table andskills/gulliver/SKILL.md, and works with-- gulliver: ignore GVxxxand[lint] disable/severity - Leave CHANGELOG.md alone; the maintainer adds the entry with credit to you when it is merged
-
pytestandruff check .pass
Please comment with your plan before writing a lot of code, as CONTRIBUTING.md asks for bigger changes.
Comment here to claim it and you'll be assigned.
Activity
dianatofficial commentedon Nov 15, 2026
Hi @laaielichter! I would love to work on this issue.
Here is my implementation plan:
Rule Definition & ID:
col = NULLandcol <> NULLare never true, so the query scans the table and returns nothing #129; happy to adjust if you prefer another identifier)Detection in src/gulliver/lint.py:
Documentation & Registry:
Testing & Verification:
uff check . 100% clean.
Could you please assign #131 to me so I can proceed with the PR?
laaielichter commentedon Nov 15, 2026
Thanks @dianatofficial, that is a thoughtful plan. We keep a limit of 3 open assigned issues per person, and you already hold three: #119 (PR #121), #112 (PR #115) and #152 (PR #168). So I can't assign #131 to you right now.
As soon as one of those is merged you can claim another, and #131 stays free until then. The quickest way forward is to finish and merge the PRs you already have open; that frees a slot right away.
Generated by Claude Code
AzalHoseinian commentedon Nov 15, 2026
Hi! I'd like to claim this one. My first PR (#163, GV003) was just merged, so I have no other open issues. Plan: extend the GV005 check in
lint.pyto also look at JOIN ... ON conditions (a function or CAST wrapping a column on either side of the comparison), report it as a finding with advice (no auto-rewrite), and add tests for the LOWER/CAST examples from the issue plus a plainON a.id = b.idthat stays clean. I'll read CONTRIBUTING.md first and ask here if anything about the rule ID or severity is unclear.AzalHoseinian commentedon Nov 15, 2026
Small correction to my plan above: I'm implementing this as a new rule, as the issue describes, not by extending GV005. Details: rule id GV021
function-on-join-key(GV019 is taken by #125), severityinfo, message and fix text as suggested in the issue. It looks at each equality in aJOIN ... ONwhere one side wraps columns of one table in a function or cast and the other side uses a column of another table. It does not flag plain keys,USING/NATURAL, literal-only functions,OR/non-equality conditions, or functions inWHERE(GV005 keeps those, no double report). Also updatesgulliver rules, README, SKILL.md, CHANGELOG and tests. I have it working locally (full pytest and ruff pass) and will open the PR once I've double-checked it.laaielichter commentedon Nov 15, 2026
Thanks @AzalHoseinian, it's yours, assigned. Your revised plan (a separate GV021
function-on-join-keyrule,info, no double report with GV005) is exactly the direction we want.One small change: please leave
CHANGELOG.mdout of the PR. The maintainer adds the credit line under## Unreleasedafter merging, which also avoids merge conflicts.Generated by Claude Code