Use JSONB containment for GIN-friendly EQ filters

[sambhav]

Summary

• Rewrites _format_conditions to emit data @> '{"field": value}' (JSONB containment) instead of data->'field' = 'value'::jsonb for EQ filters on scalar data fields (str, int, float, bool, None)
• Rewrites CONTAINS filters to use top-level containment (data @> '{"field": [values]}') instead of sub-expression containment (data->'field' @> '[values]'), removing the now-redundant jsonb_typeof guard
• Array/object EQ values keep using arrow extraction to preserve exact equality semantics (@> uses superset matching for non-scalars)
• Normalizes _format_sorting JSONB accessor expressions to match _format_conditions format (removes redundant parentheses)
• Documents the recommended GIN index in the Storage class docstring

Why this matters

The @> containment operator is the only JSONB operator that GIN indexes accelerate. Previously, EQ used data->'field' = value and CONTAINS used data->'field' @> value — neither form can use a GIN index on data. By rewriting both to top-level data @> '{"field": value}', a single GIN index accelerates all equality and array-contains queries across all collections and fields:

CREATE INDEX CONCURRENTLY idx_objects_data_gin
    ON objects USING gin (data jsonb_path_ops)
    WHERE NOT deleted;

Without this index, the query rewrites have zero performance impact — they're semantically equivalent to the old form. The index is intentionally not auto-created; it's documented as an optional optimization for large deployments.

What the GIN index accelerates:

• ?status=active → data @> '{"status": "active"}'
• ?person.name=Alice → data @> '{"person": {"name": "Alice"}}'
• ?contains_colors=red → data @> '{"colors": ["red"]}'

What it does NOT accelerate:

• Range filters (min_, max_, gt_, lt_)
• LIKE/text search
• contains_any_ (uses && array overlap)
• Sorting on JSONB fields

Test plan

• 19 new unit tests for SQL generation (EQ scalars, EQ arrays/objects, CONTAINS, CONTAINS_ANY, nested fields, non-EQ operators, id/modified exclusion, sorting normalization)
• 2 new integration tests for array/object exact equality
• All 183 existing non-PostgreSQL storage tests pass
• All 64 filter/sort resource tests pass

🤖 Generated with Claude Code