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 (8b41c43) with main (7e80931)²}

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. ↩

2. No successful run was found on main (fed116f) during the generation of this report, so 7e80931 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[greptile-apps]

Greptile Summary

This PR upstreams AI-builder knowledge-base content as first-party docs across three files, adding practical guidance on SQL-side aggregation, NULL handling, on-demand FK lookups, horizontal table scrolling, debounced search inputs, and per-table pagination state.

• docs/database/queries.md: New "Writing Efficient Queries" section covers func.count/group_by, conditional aggregation with sqlalchemy.case, the N+1 pattern and .in_() / expanding bindparam alternatives, column selection, and limit/pagination guidance; new "Handling NULL Values" section shows func.coalesce and Python-side or/is not None guards. Previous review fixes (tuple(row) coercion, import additions) are incorporated.
• docs/database/relationships.md: Adds index=True to Flag.post_id with a migration note, and a new "Querying Related Rows on Demand" section demonstrating a master-detail pattern that avoids eager-loading every relationship up front.
• docs/library/tables-and-data-grids/table.md: Replaces three lambda-wrapped on_change handlers with .debounce(500), adds an overflow_x="auto" container tip, and an alert about resetting offset to 0 on filter/sort changes.

Confidence Score: 5/5

Documentation-only changes with no runtime code paths modified; all code examples in the new sections are correct and consistent with existing patterns in the repo.

All three changed files are Markdown documentation. The code snippets are syntactically correct, the scalar unpacking outside the session context is safe for materialized values, func.coalesce guards the nullable aggregate, and the .debounce(500) replacement of lambda handlers is a valid Reflex event-action pattern. Previously flagged issues have been addressed in earlier commits.

No files require special attention.

Important Files Changed

Filename	Overview
docs/database/queries.md	Adds 'Writing Efficient Queries' (aggregate in SQL, avoid N+1, limit result size) and 'Handling NULL Values' sections with correct, well-structured code examples; previous tuple-coercion fix is present.
docs/database/relationships.md	Adds index=True to Flag.post_id FK and a new on-demand master-detail query pattern; the previously flagged missing imports are now present in the code block.
docs/library/tables-and-data-grids/table.md	Replaces three lambda on_change handlers with .debounce(500), adds overflow_x container guidance, and adds pagination-reset tip; all changes look correct.

_{Reviews (3): Last reviewed commit: "docs: index Flag.post_id so the on-deman..." | 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.