docs: database efficiency and table recipes

[amsraman]

Fifth batch of upstreaming Reflex Build's AI-builder knowledge base. Database/table techniques, translated into the docs' own ORM idiom:

• database/queries: new "Writing Efficient Queries" section — aggregate in SQL not Python (func.count/group_by, conditional aggregation with case), avoid N+1 with .in_() (plus a raw-SQL expanding=True bindparam alternative), return only what the UI needs (column selection, LIMIT, load-once options, don't cache whole tables in per-user state); new "Handling NULL Values" section (func.coalesce, Python-side guards)
• database/relationships: "Querying Related Rows on Demand" — master-detail selection querying children by FK instead of eager-loading everything
• tables-and-data-grids/table: overflow_x container guidance, per-table pagination state (reset offset on filter change), debounced search inputs (.debounce(500)) with a per-keystroke-query warning

Flexgen-environment rules (raw-SQL-only mandates, schema conventions) were deliberately not upstreamed. Pre-commit clean.

🤖 Generated with Claude Code

[codspeed-hq]

Merging this PR will not alter performance

✅ 26 untouched benchmarks
⏩ 8 skipped benchmarks¹

---

_{Comparing docs/database-field-notes (a3fb8d5) with main (d932ee8)}

Footnotes

1. 8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[greptile-apps]

Greptile Summary

This PR adds two new sections to the database query docs ("Writing Efficient Queries" and "Handling NULL Values"), a "Querying Related Rows on Demand" subsection to the relationships page, and several table/pagination UX tips. It also migrates all existing User.select() calls to the select(User) form throughout queries.md.

• docs/database/queries.md: New subsections cover aggregate-in-SQL (func.count/group_by, conditional case aggregation), avoiding N+1 with .in_() (plus a safe raw-SQL expanding=True bindparam alternative), column selection and LIMIT guidance, and COALESCE/Python-guard patterns for NULLs. All new code examples are syntactically correct for SQLAlchemy 2 / SQLModel.
• docs/database/relationships.md: New PostFlagsState example demonstrates querying child rows on demand via FK filter; index=True is added to Flag.post_id with a migration caveat. The snippet includes from typing import List, Optional and import reflex as rx so it is copy-paste safe in isolation.
• docs/library/tables-and-data-grids/table.md: Adds overflow_x="auto" container tip, a pagination reset note, and replaces three lambda value: State.handler(value) bindings with State.handler.debounce(500) alongside an explanatory alert.

Confidence Score: 5/5

All changes are documentation additions and minor code-sample corrections; no runtime code is modified.

Every new code snippet was verified against SQLAlchemy 2 / SQLModel semantics — func.count/group_by, case() positional-tuple syntax, coalesce, expanding=True bindparam, and .debounce(500) event-action chaining are all correct. The User.select() → select(User) migration is consistent across all call sites. No runtime paths are touched.

No files require special attention.

Important Files Changed

Filename	Overview
docs/database/queries.md	Adds "Writing Efficient Queries" and "Handling NULL Values" sections with accurate SQLModel/SQLAlchemy examples; also migrates all User.select() calls to select(User) throughout the file.
docs/database/relationships.md	Adds "Querying Related Rows on Demand" subsection with a complete, copy-paste-safe PostFlagsState example; adds index=True to Flag.post_id with a correct migration caveat.
docs/library/tables-and-data-grids/table.md	Adds overflow_x container guidance and pagination-reset note; replaces three lambda value: State.handler(value) bindings with State.handler.debounce(500) and adds a contextual alert explaining why debounce matters.

_{Reviews (6): Last reviewed commit: "docs: address review — select() idiom, r..." | Re-trigger Greptile}

[FarhanAliRaza]

rx.Model is deprecated. do we want to add new docs using deprecated feature ? We can use new code example maybe.

[amsraman]

Thanks @FarhanAliRaza — addressed this round.

rx.Model deprecation (your comment): You're right that it's deprecated — in 0.9.6 rx.Model.__init_subclass__ emits a deprecation warning (deprecation_version="0.9.2", removal_version="1.0.0", reason "Directly use database ORM layer, like sqlalchemy or SQLModel"). But I'd rather not migrate just these two examples. Every database docs page uses rx.Model today: the canonical Tables page literally instructs "make a class that inherits from rx.Model", queries.md opens with class User(rx.Model, table=True), and the Post/Flag models these new examples build on are pre-existing rx.Model classes. Switching one section to bare SQLModel + explicit primary key (and select(Order) over Order.select()) would leave the page internally inconsistent — User(rx.Model) at the top, Order(SQLModel) halfway down — and confuse anyone reading top-to-bottom. I think the accurate fix is a separate, section-wide migration of all of docs/database/* off rx.Model in one pass, rather than piecemeal in this efficiency-notes PR. Happy to open that as a follow-up ticket if you agree.

While in here I also fixed two accuracy issues in the new content:

"single indexed query" claim (relationships.md, 8b41c43): Flag.post_id was only foreign_key="post.id", which does not create an index, so the per-selection lookup was actually a full table scan — the "indexed" claim was false. Added index=True to Flag.post_id (verified it emits the ix_flag_post_id index) and noted that adding an index to an existing table requires a migration, so the claim now holds.

Reserved keyword in raw SQL (queries.md, 2e6bb28): the expanding IN (...) example used SELECT * FROM user, but user is a reserved word in PostgreSQL and fails unquoted. Renamed the table to users in that snippet so it runs as written.