Skip to content

docs: warn against unfiltered count queries for existence checks - #22976

Draft
github-actions[bot] wants to merge 1 commit into
mainfrom
claude/update-agents-md-33ccf3d
Draft

docs: warn against unfiltered count queries for existence checks#22976
github-actions[bot] wants to merge 1 commit into
mainfrom
claude/update-agents-md-33ccf3d

Conversation

@github-actions

Copy link
Copy Markdown
Contributor

Automated AGENTS.md update triggered by commit 33ccf3d.

This PR was generated by Claude Code analyzing the diff from the latest push to main and updating any stale AGENTS.md files.

Why this belongs in AGENTS.md
Path: ui-v2/src/api/AGENTS.md

Proposed text: "For existence checks ("are there any records at all"), don't use an unfiltered `count` query — an unbounded COUNT scans the whole table and can exceed the API's statement timeout on large deployments. Use a filtered list query with `limit: 1` and check the response length instead."

Non-obvious evidence: The docstring for `buildCountFlowRunsQuery` in ui-v2/src/api/flow-runs/index.ts says nothing about statement-timeout risk on unfiltered counts, and no comment anywhere in the codebase flagged this before the fix. It took a production-relevant fix (PR #22920, "Remove the unbounded flow run count from the dashboard empty-state check") to surface it — not something a future agent would learn in 30 seconds of reading the query factory or dashboard.tsx.

Cross-cutting scope: Applies to any `count` query factory used purely to answer an existence question (flow runs, task runs, deployments, work pools, etc.), not just the one dashboard.tsx call site that triggered this diff. The api/AGENTS.md "Tanstack Query Guidelines" section is exactly where sibling rules about count/list query construction already live (refetchInterval bullet immediately above it), so this is the least-common-ancestor location for the pattern.

Why not code comment/docstring: A comment on `buildCountFlowRunsQuery` would only warn readers of that one factory; the actual risk is a decision future agents make when writing a *new* existence check against a different resource (e.g. task_runs, deployments) where they'd reach for the same unfiltered-count shortcut without ever opening flow-runs/index.ts. AGENTS.md is read before writing new query code in this directory, which is the point where the mistake needs to be prevented.

Durability: The underlying invariant (large-table COUNT can exceed statement timeout; bounded filter+limit is the safe existence-check pattern) is a database/API performance characteristic, not tied to the dashboard route or this PR's specifics. It will remain true and relevant long after this diff is old news.

Counter-evidence checked: Read ui-v2/src/api/flow-runs/index.ts docstrings for buildCountFlowRunsQuery and buildFilterFlowRunsQuery (neither mentions the timeout risk); read the existing ui-v2/src/api/AGENTS.md Tanstack Query Guidelines section (no existing bullet covers this); read ui-v2/src/routes/AGENTS.md (route-loader-focused, not the right home for a query-construction rule); confirmed via grep that buildFilterFlowRunsQuery/buildCountFlowRunsQuery are shared factories used by multiple call sites, not private to dashboard.tsx.

Changed files in triggering push
ui-v2/src/routes/dashboard.tsx
ui-v2/tests/dashboard/dashboard.test.tsx

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants