json-type tutorial teaches client-side filtering as a property of JSON

[dimitri-yatsenko]

Blocked on datajoint/datajoint-python#1564. Deliberately deferred so the tutorial is not rewritten twice.

The problem

src/tutorials/advanced/json-type.ipynb is the page a user opens to learn how to work with JSON. Its filtering section reads:

Filtering on JSON Content

Fetch then filter in Python:

followed by pulling the whole table into a list comprehension:

calibrated = [
    e for e in Equipment.to_dicts()
    if e['specs'] and e['specs'].get('calibrated')
]

and its Design Guidelines table lists this as an inherent property of the type:

JSON	Normalized Tables
Filter in Python	Filter in SQL

Why it is wrong

Server-side filtering works, on both backends. Equipment & {"specs.vendor": "Acme"} is translated to json_value() on MySQL and jsonb_extract_path_text() on PostgreSQL; ordering comparisons work through a typed projection, proj(ch="specs.channels:unsigned") & "ch > 32". The syntax is documented in #291.

So the tutorial teaches a full table scan into Python for something the database does, and presents it as a limitation of JSON rather than a choice.

Why it probably says that

The tutorial's own example is specs.calibrated, a boolean — and & {"specs.calibrated": True} returns no rows on MySQL and raises on PostgreSQL (datajoint-python#1564). Whoever wrote the section likely tried exactly that, got nothing back, and concluded JSON cannot be filtered server-side.

That is why this waits: writing the section against the string workaround ({"specs.calibrated": "true"}) would teach an idiom that becomes wrong as soon as #1564 lands.

When #1564 merges

1. Rewrite Filtering on JSON Content to filter server-side, keeping one short client-side example for genuinely non-SQL-expressible predicates.
2. Correct the Design Guidelines table — "Filter in Python" is not a property of JSON. The honest contrast is about indexing and type enforcement, not about where filtering happens.
3. Cross-link the reference section added in Document JSON path access in restriction and projection #291.
4. Re-execute the notebook: these are code cells with committed outputs.