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

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.

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.
 

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: