An empty bloom filter makes `eql_v3.matches()` vacuously true — a match query with no terms returns every row

[coderdan]

Important

The "Suggested fix" and "Storage-side check" sections below are superseded — see the LIKE-shaped proposal in the comments. Returning NULL for an empty bloom breaks empty vs empty (which should be true, per '' LIKE '') and drops empty-bloom rows out of NOT matches. The guard belongs in matches(), not bloom_filter, because the correct behaviour is asymmetric between the stored value and the needle.

Summary

eql_v3.matches() is jsonb containment against the query term's bloom filter. If the query term's bloom filter is an empty array, containment is vacuously true and the predicate matches every row in the table — silently, with no error.

SELECT '[1,2,3]'::jsonb @> '[]'::jsonb;   -- true

Observed in practice as a free-text search over an encrypted column returning the entire table (capped only by the query's LIMIT) where the plaintext baseline returned 10 rows.

The chain

eql_v3.matches(a, b)  →  eql_v3.match_term(a) @> eql_v3.match_term(b)
eql_v3.match_term(q)  →  eql_v3_internal.bloom_filter(q::jsonb)

eql_v3_internal.bloom_filter(val jsonb)
  → CASE WHEN jsonb_typeof(val -> 'bf') = 'array'
      THEN ARRAY(SELECT jsonb_array_elements(val -> 'bf'))::eql_v3_internal.bloom_filter
    END        -- no ELSE

The two "no bits" cases behave in opposite ways

Query term	match_term	matches()	Behaviour
{"bf": []} — empty array	{}	true for every row	fails open
{} — no bf key	NULL	NULL ⇒ no rows (function is STRICT)	fails safe
{"bf": [1,2]}	{1,2}	normal containment	—

Reproduced directly:

SELECT eql_v3_internal.bloom_filter('{"bf":[10,20,30]}'::jsonb)
    @> eql_v3_internal.bloom_filter('{"bf":[]}'::jsonb);   -- true

The missing-key path already fails closed, courtesy of STRICT plus the CASE with no ELSE. It is specifically the empty array that produces {} and turns containment vacuous.

Blast radius — one fix point

Every matches() overload routes through match_term() → bloom_filter(). On a 3.0.2 install that is 15 overloads across eql_v3_text_match, eql_v3_text_search, and eql_v3_text_search_ore (including the jsonb-cast variants), and match_term is the only caller of bloom_filter. So the fix belongs in eql_v3_internal.bloom_filter and needs no call-site changes.

Suggested fix

Make the empty-array case land where the missing-key case already does — return NULL rather than {}:

CREATE OR REPLACE FUNCTION eql_v3_internal.bloom_filter(val jsonb)
  RETURNS eql_v3_internal.bloom_filter
  LANGUAGE sql IMMUTABLE PARALLEL SAFE STRICT
AS $$
  SELECT CASE
    WHEN jsonb_typeof(val -> 'bf') = 'array'
     AND jsonb_array_length(val -> 'bf') > 0
    THEN ARRAY(SELECT jsonb_array_elements(val -> 'bf'))::eql_v3_internal.bloom_filter
  END
$$;

STRICT propagation then kills the predicate instead of opening it. Raising an exception is the other option if you'd rather an empty needle be loud than silently match nothing — the important part is that it stops matching everything.

Storage-side check — no regression

bloom_filter is also applied to the stored value (the LHS), so it is worth confirming this change is safe there. Empty blooms do occur naturally in stored data: in a 320-row fixture table with a text_search column, 10 rows have bf: [] (a 2-character value, below the trigram floor; bf lengths across the table run 0–87).

Those rows behave identically before and after:

• today: {} @> {needle} → false — never match a free-text query
• after: NULL @> {needle} → NULL — still never match

The only behavioural change on the storage side is empty-needle-vs-empty-stored-value, which goes from true to no-match — which is the intent.

Note

The SDK documents short needles as "rejected rather than silently matching every row", so there is a client-side guard. This is the server-side backstop for the same invariant, and it should hold regardless of which client constructed the term.

[coderdan]

Correction to the "no regression" claim in the storage-side section above — it holds for the positive predicate but not for the negated one.

Measured on the same 320-row fixture table (10 rows carry bf: []), using a real stored value as the query term and simulating the proposed bloom_filter in pg_temp:

	matches	NOT matches
current	10	310
proposed fix	10	300

Today an empty stored bloom yields {} @> {term} → false, so those rows are returned by NOT matches. Under the fix they become NULL and drop out of both sides. Here that is 10 of 320 rows (~3%) silently leaving a negated result set.

Worth deciding explicitly, because it is arguably the more correct semantics — a value with no indexable terms is genuinely "unknown" rather than "does not contain" — but it does mean matches and NOT matches stop partitioning the non-NULL rows, and any caller relying on that today changes behaviour.

Related NULL semantics, for completeness (matches is STRICT, so a NULL column value short-circuits before the body runs):

bloom_filter(NULL)  => NULL        populated @> NULL  => NULL
NULL @> populated   => NULL        NULL @> NULL       => NULL

So a row with a SQL-NULL encrypted column already satisfies neither matches nor NOT matches — verified by adding one NULL row to the 320: total 321, matches 10, NOT matches 310, sum 320. Since EQL requires encrypted columns to be nullable, that case is the norm rather than an edge case, and the fix widens the set of rows in it from "SQL NULL only" to "SQL NULL or no indexable terms".

If the negated-query behaviour is a concern, raising on an empty needle (rather than returning NULL) keeps the storage side untouched: the LHS is a stored value that was never a needle, so a needle-side-only guard fixes the vacuous-truth bug without changing NOT matches at all.

[coderdan]

Superseding both earlier proposals. Modelling the empty cases on LIKE (ignoring wildcards, which bloom match doesn't support) gives a better answer, and it moves the fix out of bloom_filter.

LIKE as the reference

SELECT ''      LIKE '';     -- true
SELECT ''      LIKE 'cat';  -- false
SELECT 'catty' LIKE '';     -- false

Mapped onto containment, only one of four cells is actually wrong today:

stored (LHS)	needle (RHS)	LIKE analogue	want	current
empty	empty	'' LIKE ''	true	true ✅
empty	non-empty	'' LIKE 'cat'	false	false ✅
non-empty	empty	'catty' LIKE ''	false	true ❌
non-empty	non-empty	—	containment	containment ✅

This also rules out the bloom_filter → NULL fix I suggested above: it would break row 1 (empty vs empty becomes NULL, not true), and as measured in the previous comment it drops empty-bloom rows out of NOT matches.

Why it can't live in bloom_filter

The required behaviour is asymmetric — an empty needle is a malformed query, an empty stored value is legitimate data (a sub-trigram value like BP). bloom_filter has no idea which side it is being applied to, so it cannot distinguish them. The guard has to sit where both sides are visible, i.e. in matches().

Proposed

SELECT CASE
  WHEN cardinality(eql_v3.match_term(b)) = 0
    THEN cardinality(eql_v3.match_term(a)) = 0
  ELSE eql_v3.match_term(a) @> eql_v3.match_term(b)
END

"If the needle has no terms, match only a value that also has no terms." No exceptions raised, consistent with the rest of the operator surface.

Verified against a live 3.0.2 install:

  empty      vs empty      => true    want true
  empty      vs non-empty  => false   want false
  non-empty  vs empty      => false   want false   <-- was true
  non-empty  vs non-empty  => true    want true
  NULL       vs non-empty  => NULL    want NULL
  missing-bf vs non-empty  => NULL    want NULL

NULL handling falls out for free: cardinality(NULL) is NULL, so the CASE drops to ELSE and the existing STRICT + NULL-propagation behaviour is unchanged.

No regression

Same 320-row fixture table (10 rows with bf: []), real stored value as the needle:

	matches	NOT matches
current	10	310
LIKE-shaped fix	10	310
bloom_filter → NULL	10	300

Identical to current on both sides, while still fixing the vacuous-truth case.

Cost

It applies to all 15 matches() overloads rather than one function. If a single fix point is preferred, put the CASE in an internal helper (eql_v3_internal.bloom_match(a, b)) and have every overload delegate — one place to change, correct asymmetric semantics, no behavioural change for existing callers.