docs: explain what query-report reports and where the query name comes from

[ogenstad]

What changed

Improves the help text for infrahubctl graphql query-report. No behavior change.

The command's description was "Run a GraphQL query through InfrahubGraphQLQueryReport and report its analysis." That names an internal server type and tells a user nothing about what the answer means or why they would want it.

It now:

• Leads with the consequence: artifact and generator definitions use the verdict to decide how much to regenerate when data changes. true means only the objects that changed are reprocessed, false means all of them are.
• States the rule that produces the verdict.
• Says on NAME that it is the query name declared under queries in .infrahub.yml.
• Records on --branch that the answer is branch-dependent, because uniqueness constraints come from the schema.

Kept as plain prose with no markdown links, since the same text renders in terminal --help.

Rendered output

Regenerated with uv run invoke docs-generate; docs/docs/infrahubctl/infrahubctl-graphql.mdx is included.

Related

The Infrahub docs are updated in a companion PR (opsmill/infrahub#10293), which documents the command on the canonical Single-target queries page. The concept this command reports on is called a single-target query in user documentation.

Testing

• uv run invoke format and uv run invoke lint-code - clean
• uv run invoke lint-docs - no findings on the changed pages (20 pre-existing spelling errors remain in generated sdk_ref/ files)

---

Summary by cubic

Clarifies the help text for infrahubctl graphql query-report so users understand the verdict, the uniqueness rule, where the query name comes from, and branch dependence. No behavior change; this clarifies how artifact and generator definitions determine regeneration scope.

• Updates CLI help and docstring in infrahub_sdk/ctl/graphql.py and the docs page docs/docs/infrahubctl/infrahubctl-graphql.mdx.
• Defines “unique nodes” (filters on ids/hfid, or fully satisfies one uniqueness constraint with provided values) and states consequences: true → only changed objects’ artifacts/generators regenerate; false → all regenerate.
• Notes that NAME is from the queries section of .infrahub.yml and that --branch can change results because constraints come from the schema.
• Removes a redundant changelog entry.

^{Written for commit 8deae32. Summary will update on new commits.}

[cubic-dev-ai]

No issues found across 3 files

_{Re-trigger cubic}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@            Coverage Diff             @@
##           stable    #1253      +/-   ##
==========================================
+ Coverage   82.47%   82.54%   +0.06%     
==========================================
  Files         138      138              
  Lines       12186    12186              
  Branches     1833     1833              
==========================================
+ Hits        10051    10059       +8     
+ Misses       1572     1568       -4     
+ Partials      563      559       -4     

Flag	Coverage Δ
integration-tests	40.57% <ø> (+<0.01%)	⬆️
python-3.10	56.34% <ø> (+0.06%)	⬆️
python-3.11	56.34% <ø> (+0.06%)	⬆️
python-3.12	56.32% <ø> (+0.04%)	⬆️
python-3.13	56.32% <ø> (+0.06%)	⬆️
python-3.14	56.34% <ø> (+0.08%)	⬆️
python-filler-3.12	22.27% <ø> (+0.06%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
infrahub_sdk/ctl/graphql.py	91.05% <ø> (ø)

... and 3 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[gmazoyer]

Does this actually need a changelog?

[ogenstad]

Does this actually need a changelog?

No I guess that's a bit redundant for this.

[cloudflare-workers-and-pages]

Deploying infrahub-sdk-python with    Cloudflare Pages

Latest commit:	8deae32
Status:	✅  Deploy successful!
Preview URL:	https://3764716a.infrahub-sdk-python.pages.dev
Branch Preview URL:	https://pog-query-report-help-text.infrahub-sdk-python.pages.dev

View logs