From 05905686c19b5d94c8c3a6e06e008cc45cc03e9b Mon Sep 17 00:00:00 2001 From: Patrick Ogenstad Date: Mon, 17 Aug 2026 12:47:50 +0200 Subject: [PATCH] docs: explain what query-report reports and where the query name comes from The command's help said only that it runs a query through InfrahubGraphQLQueryReport, which names an internal type and tells a user nothing about what the answer means. Describe the consequence first: artifact and generator definitions use the verdict to decide how much to regenerate when data changes. State the rule that produces it, note that NAME comes from the queries section of .infrahub.yml, and record on --branch that the answer is branch-dependent because uniqueness constraints live in the schema. --- changelog/+query-report-help-text.changed.md | 1 + docs/docs/infrahubctl/infrahubctl-graphql.mdx | 16 +++++++++---- infrahub_sdk/ctl/graphql.py | 23 ++++++++++++++++--- 3 files changed, 33 insertions(+), 7 deletions(-) create mode 100644 changelog/+query-report-help-text.changed.md diff --git a/changelog/+query-report-help-text.changed.md b/changelog/+query-report-help-text.changed.md new file mode 100644 index 000000000..a1f56dd0c --- /dev/null +++ b/changelog/+query-report-help-text.changed.md @@ -0,0 +1 @@ +Rewrote the help text for `infrahubctl graphql query-report` so it explains what the report means rather than naming the internal GraphQL type it calls. It now states that artifact and generator definitions use the verdict to decide how much to regenerate when data changes, gives the rule that makes a query target unique nodes, notes that `NAME` is the query name declared under `queries` in `.infrahub.yml`, and records that `--branch` matters because uniqueness constraints come from the schema. diff --git a/docs/docs/infrahubctl/infrahubctl-graphql.mdx b/docs/docs/infrahubctl/infrahubctl-graphql.mdx index e97d5216b..143fc027d 100644 --- a/docs/docs/infrahubctl/infrahubctl-graphql.mdx +++ b/docs/docs/infrahubctl/infrahubctl-graphql.mdx @@ -16,13 +16,21 @@ $ infrahubctl graphql [OPTIONS] COMMAND [ARGS]... **Commands**: -* `query-report`: Run a GraphQL query through... +* `query-report`: Report how Infrahub will interpret a... * `export-schema`: Export the GraphQL schema to a file. * `generate-return-types`: Create Pydantic Models for GraphQL query... ## `infrahubctl graphql query-report` -Run a GraphQL query through InfrahubGraphQLQueryReport and report its analysis. +Report how Infrahub will interpret a GraphQL query. + +Reports whether the query targets unique nodes, meaning every query it contains returns a +single object. Artifact and generator definitions use this to decide how much to regenerate +when data changes: when it is true, only the artifacts or generator instances of the objects +that changed are regenerated, and when it is false, all of them are. + +A query returns a single object when it filters on ids or hfid, or on every part of one +uniqueness constraint of the model, and the values it filters on are always provided. **Usage**: @@ -32,12 +40,12 @@ $ infrahubctl graphql query-report [OPTIONS] NAME **Arguments**: -* `NAME`: Name of the GraphQL query to analyze. [required] +* `NAME`: Name of the GraphQL query to analyze, as declared under queries in .infrahub.yml. [required] **Options**: * `--online`: Fetch the query from the Infrahub server (CoreGraphQLQuery by name) instead of reading it from the local .infrahub.yml file. -* `--branch TEXT`: Branch on which to run the report. +* `--branch TEXT`: Branch on which to run the report. Uniqueness constraints come from the schema, so the result can differ between branches. * `--config-file TEXT`: [env var: INFRAHUBCTL_CONFIG; default: infrahubctl.toml] * `--help`: Show this message and exit. diff --git a/infrahub_sdk/ctl/graphql.py b/infrahub_sdk/ctl/graphql.py index 37d551374..c46a893ea 100644 --- a/infrahub_sdk/ctl/graphql.py +++ b/infrahub_sdk/ctl/graphql.py @@ -112,7 +112,9 @@ def callback() -> None: @app.command(name="query-report") @catch_exception(console=console) async def query_report( - name: str = typer.Argument(..., help="Name of the GraphQL query to analyze."), + name: str = typer.Argument( + ..., help="Name of the GraphQL query to analyze, as declared under queries in .infrahub.yml." + ), online: bool = typer.Option( False, "--online", @@ -121,10 +123,25 @@ async def query_report( "instead of reading it from the local .infrahub.yml file." ), ), - branch: str | None = typer.Option(None, help="Branch on which to run the report."), + branch: str | None = typer.Option( + None, + help=( + "Branch on which to run the report. Uniqueness constraints come from the schema, " + "so the result can differ between branches." + ), + ), _: str = CONFIG_PARAM, ) -> None: - """Run a GraphQL query through InfrahubGraphQLQueryReport and report its analysis.""" + """Report how Infrahub will interpret a GraphQL query. + + Reports whether the query targets unique nodes, meaning every query it contains returns a + single object. Artifact and generator definitions use this to decide how much to regenerate + when data changes: when it is true, only the artifacts or generator instances of the objects + that changed are regenerated, and when it is false, all of them are. + + A query returns a single object when it filters on ids or hfid, or on every part of one + uniqueness constraint of the model, and the values it filters on are always provided. + """ client = initialize_client(branch=branch) if online: