docs: document how query targeting scopes artifact regeneration [IFC-2504] by ogenstad · Pull Request #10293 · opsmill/infrahub

ogenstad · 2026-08-17T12:45:20Z

What changed

Extracts the IFC-2504 spec (InfrahubGraphQLQueryReport) into the documentation system and closes the user-facing gap it left behind. Documentation only, no code changes.

User-facing docs

docs/docs/development-resources/graphql/single-target-queries.mdx is the canonical page for this concept. Its "Ensuring your query is single-target" section opened with "There is currently no automated way to verify that a query is single-target" and closed by saying integrated checks were planned. infrahubctl graphql query-report is that check, so the section now documents it, including what --online and --branch are for.

The same section described a run-time warning. That warning is real, but the description was off in two ways, and both are corrected:

It is emitted by the proposed change pipeline when it works out what to regenerate for an artifact or Generator definition, not when a query is loaded into the system.
It fires only when a relevant field actually changed (ImpactScope.ALL). A pipeline that touches nothing the query reads stays quiet regardless, so a quiet pipeline is not evidence that a query is single-target. The page now says so, since that is the trap.

docs/docs/artifacts/overview.mdx explains why a data change sometimes regenerates one artifact and sometimes every artifact under the definition, and traces the query from the artifact definition through the Transformation to .infrahub.yml - the page previously referred to "the definition's GraphQL query" without establishing that an artifact definition has no query field of its own. The criteria themselves stay on the single-target page rather than being restated.

Internal docs

dev/knowledge/backend/query-target-uniqueness.md (new) - the current pinning rules, the SPECIFIC/ALL/NONE impact scopes, and the two ways to inspect a query. Note that the spec's research.md describes the original narrower rules; PR fix: scope artifact/generator regeneration for complex uniqueness constraints #9487 broadened them to hfid, cardinality-one relationships, and composite constraints. This documents current behavior.
dev/guidelines/backend/graphql.md (new) - the root-level query field pattern this feature followed, resolver conventions, and how invalid user input must surface.
dev/adr/0020-analyzer-single-source-of-truth-for-query-targeting.md (new) - why the analyzer stays the single source of truth rather than the rules being reimplemented client-side.
The spec is archived under dev/specs/archive/.

Note on the ADR number

Numbered 0020 rather than 0006: develop already uses 0006 through 0019 and release-1.11 through 0015. dev/adr/README.md now says numbers must be free on every long-lived branch, so the index on stable will have gaps.

Testing

uv run invoke docs.lint - clean (4 remaining warnings are pre-existing in other files)
uv run invoke docs.validate - no stale generated files
Cross-page anchors verified by hand

cubic-dev-ai

2 issues found across 16 files

Confidence score: 4/5

In dev/knowledge/backend/query-target-uniqueness.md, the documented infrahubctl graphql query-report command appears to be nonexistent, which can send readers down a dead path and erode trust in the migration guidance—update the doc to a real command/workflow or explicitly mark it as removed.
In dev/adr/0020-analyzer-single-source-of-truth-for-query-targeting.md, the relative link to the archived spec is incorrect, so readers cannot reach the supporting context from the ADR—fix the path to point to dev/specs/... (drop one ../).

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="dev/adr/0020-analyzer-single-source-of-truth-for-query-targeting.md">

<violation number="1" location="dev/adr/0020-analyzer-single-source-of-truth-for-query-targeting.md:88">
P3: The relative link to the archived spec is broken. From `dev/adr/`, `../../specs/...` climbs to the repo root and points at `specs/archive/...`, which does not exist; the spec lives under `dev/specs/`. Drop one `../` so it resolves to `../specs/archive/ifc-2504-graphql-query-report/research.md`.</violation>
</file>

<file name="dev/knowledge/backend/query-target-uniqueness.md">

<violation number="1" location="dev/knowledge/backend/query-target-uniqueness.md:103">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**

This documentation references `infrahubctl graphql query-report`, but the command does not exist in this repository after the change. The PR description confirms the `python_sdk` submodule pointer was deliberately not bumped, and the spec archive notes the SDK change needs a separate commit and PR. Per Rule 1, docs should not reference commands that are not implemented by the changed code. Either remove the reference until the SDK PR lands, or add a note that the command requires the companion SDK update.</violation>
</file>

_{Shadow auto-approve: would not auto-approve because issues were found.

Re-trigger cubic}

cubic-dev-ai · 2026-08-17T12:51:03Z

+}
+```
+
+`infrahubctl graphql query-report <name>` wraps that field for the common case. It resolves the query by


P1: Custom agent: Flag AI Slop and Fabricated Changes

This documentation references infrahubctl graphql query-report, but the command does not exist in this repository after the change. The PR description confirms the python_sdk submodule pointer was deliberately not bumped, and the spec archive notes the SDK change needs a separate commit and PR. Per Rule 1, docs should not reference commands that are not implemented by the changed code. Either remove the reference until the SDK PR lands, or add a note that the command requires the companion SDK update.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At dev/knowledge/backend/query-target-uniqueness.md, line 103: <comment>This documentation references `infrahubctl graphql query-report`, but the command does not exist in this repository after the change. The PR description confirms the `python_sdk` submodule pointer was deliberately not bumped, and the spec archive notes the SDK change needs a separate commit and PR. Per Rule 1, docs should not reference commands that are not implemented by the changed code. Either remove the reference until the SDK PR lands, or add a note that the command requires the companion SDK update.</comment> <file context> @@ -0,0 +1,123 @@ +} +``` + +`infrahubctl graphql query-report <name>` wraps that field for the common case. It resolves the query by +name from the local `.infrahub.yml`, or from the server's `CoreGraphQLQuery` nodes with `--online`, and +prints the verdict. This is the check to run against an artifact definition's query before saving it. </file context>

Not a fabrication - the command exists and is already shipped.

infrahubctl graphql query-report was added to the SDK in opsmill/infrahub-sdk-python#976 (c26809b), which is an ancestor of the submodule commit this repo currently pins:

$ git -C python_sdk merge-base --is-ancestor c26809b 13f26b0 && echo yes yes

So the command is available to anyone running the pinned SDK today, which is why the docs can reference it without a pointer bump. The companion PR (opsmill/infrahub-sdk-python#1253) only rewrites the command's --help text; it does not introduce the command.

The reason the pointer is deliberately not bumped here is the reverse of what the review assumes: bumping it would make this PR depend on an unmerged SDK commit.

cubic-dev-ai · 2026-08-17T12:51:03Z

+## Implementation Notes
+
+- Rules and consumers: [`dev/knowledge/backend/query-target-uniqueness.md`](../knowledge/backend/query-target-uniqueness.md).
+- Spec: [`specs/archive/ifc-2504-graphql-query-report/research.md`](../../specs/archive/ifc-2504-graphql-query-report/research.md) (RES-001).


P3: The relative link to the archived spec is broken. From dev/adr/, ../../specs/... climbs to the repo root and points at specs/archive/..., which does not exist; the spec lives under dev/specs/. Drop one ../ so it resolves to ../specs/archive/ifc-2504-graphql-query-report/research.md.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At dev/adr/0020-analyzer-single-source-of-truth-for-query-targeting.md, line 88: <comment>The relative link to the archived spec is broken. From `dev/adr/`, `../../specs/...` climbs to the repo root and points at `specs/archive/...`, which does not exist; the spec lives under `dev/specs/`. Drop one `../` so it resolves to `../specs/archive/ifc-2504-graphql-query-report/research.md`.</comment> <file context> @@ -0,0 +1,88 @@ +## Implementation Notes + +- Rules and consumers: [`dev/knowledge/backend/query-target-uniqueness.md`](../knowledge/backend/query-target-uniqueness.md). +- Spec: [`specs/archive/ifc-2504-graphql-query-report/research.md`](../../specs/archive/ifc-2504-graphql-query-report/research.md) (RES-001). </file context>

Suggested change

- Spec: [`specs/archive/ifc-2504-graphql-query-report/research.md`](../../specs/archive/ifc-2504-graphql-query-report/research.md) (RES-001).

- Spec: [`specs/archive/ifc-2504-graphql-query-report/research.md`](../specs/archive/ifc-2504-graphql-query-report/research.md) (RES-001).

Fixed in 06c9e57.

Small correction to the diagnosis: the path did resolve, because specs is a tracked symlink to dev/specs (mode 120000), so ../../specs/archive/... reaches the file on a checkout. But GitHub's markdown renderer does not follow symlinks in relative links, so it would have 404'd in the web UI.

Changed to ../specs/archive/... as suggested, and also normalised the same path in EXTRACTED.md so neither depends on the symlink.

…2504] Extract the IFC-2504 spec into the documentation system and close the user-facing gap it left behind. - docs/docs/development-resources/graphql/single-target-queries.mdx is the canonical page for this concept. Its "Ensuring your query is single-target" section said no automated check existed; it now documents `infrahubctl graphql query-report`, which is the check it anticipated. The run-time warning it described is corrected: it is emitted by the proposed change pipeline when it cannot map a change to specific targets, not at query load time, and only when a relevant field actually changed. - docs/docs/artifacts/overview.mdx explains why some data changes regenerate a single artifact while others regenerate every artifact under the definition, and traces the query from the artifact definition through the Transformation to .infrahub.yml. The criteria themselves stay on the single-target page rather than being restated here. - dev/knowledge/backend/query-target-uniqueness.md records the current pinning rules, the SPECIFIC/ALL/NONE impact scopes, and the two ways to inspect a query. - dev/guidelines/backend/graphql.md captures the root-level query field pattern this feature followed. - ADR 0020 records that the analyzer remains the single source of truth for the targeting verdict, rather than the rules being reimplemented for users. The spec is archived under dev/specs/archive/.

cubic-dev-ai

2 issues found across 16 files

Confidence score: 3/5

docs/docs/development-resources/graphql/single-target-queries.mdx documents query-report, --online, and --branch even though the pinned python_sdk submodule in this PR does not provide them, so readers can hit immediate command failures and lose trust in the setup docs — either bump the pinned submodule to a version that includes these features or remove/guard these flags from the doc.
docs/docs/artifacts/overview.mdx includes infrahubctl graphql query-report, which is also unavailable with the current pinned dependency, creating a second user-facing dead end in the documentation flow — align this page with the shipped CLI surface (or explicitly note version requirements) before merge.

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/docs/development-resources/graphql/single-target-queries.mdx">

<violation number="1" location="docs/docs/development-resources/graphql/single-target-queries.mdx:161">
P2: Custom agent: **Flag AI Slop and Fabricated Changes**

This documents `query-report`, `--online`, and `--branch` without updating the pinned `python_sdk` submodule that provides them. Users on the dependency version from this commit may not have the command or these options; merge the SDK update first or version-gate/defer these instructions.</violation>
</file>

<file name="docs/docs/artifacts/overview.mdx">

<violation number="1" location="docs/docs/artifacts/overview.mdx:141">
P2: Custom agent: **Flag AI Slop and Fabricated Changes**

The documented `infrahubctl graphql query-report` command is unavailable in this change because the pinned `python_sdk` submodule was not bumped. Remove this instruction until the SDK update lands, or merge the matching SDK bump with the documentation.</violation>
</file>

_{Shadow auto-approve: would not auto-approve because issues were found.

Re-trigger cubic}

cubic-dev-ai · 2026-08-17T15:01:31Z

 ## Ensuring your query is single-target

-There is currently no automated way to verify that a query is single-target. The best way to verify is to review the query and ensure it meets all the criteria outlined above.
+Rather than reviewing a query against the criteria above by hand, ask Infrahub how it will interpret it. Run [`infrahubctl graphql query-report`]($(base_url)infrahubctl/infrahubctl-graphql) with the name of the query as declared under `queries` in your `.infrahub.yml`:


P2: Custom agent: Flag AI Slop and Fabricated Changes

This documents query-report, --online, and --branch without updating the pinned python_sdk submodule that provides them. Users on the dependency version from this commit may not have the command or these options; merge the SDK update first or version-gate/defer these instructions.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/development-resources/graphql/single-target-queries.mdx, line 161: <comment>This documents `query-report`, `--online`, and `--branch` without updating the pinned `python_sdk` submodule that provides them. Users on the dependency version from this commit may not have the command or these options; merge the SDK update first or version-gate/defer these instructions.</comment> <file context> @@ -158,11 +158,31 @@ query DeviceConfig($device_name: String!) { ## Ensuring your query is single-target -There is currently no automated way to verify that a query is single-target. The best way to verify is to review the query and ensure it meets all the criteria outlined above. +Rather than reviewing a query against the criteria above by hand, ask Infrahub how it will interpret it. Run [`infrahubctl graphql query-report`]($(base_url)infrahubctl/infrahubctl-graphql) with the name of the query as declared under `queries` in your `.infrahub.yml`: -When loaded into the system, Infrahub will analyze the query and determine if it is single-target or not. If it is not single-target, Infrahub will log a warning. </file context>

Same false positive as the one already answered on dev/knowledge/backend/query-target-uniqueness.md - the command and both options exist at the currently pinned submodule commit, so no bump is needed.

$ git -C python_sdk show 13f26b0:infrahub_sdk/ctl/graphql.py | grep -nE '"--online"|branch: str|name="query-report"' 112:@app.command(name="query-report") 118: "--online", 124: branch: str | None = typer.Option(None, help="Branch on which to run the report."),

query-report, --online and --branch all shipped together in opsmill/infrahub-sdk-python#976, which is an ancestor of the pinned 13f26b0. The companion SDK PR only rewrites the command's --help text.

Bumping the pointer here would be the actual problem: it would tie this PR to an unmerged SDK commit.

cubic-dev-ai · 2026-08-17T15:01:31Z

+
+This returns a single device, because `$name` is required and the schema marks `name` as unique.
+
+For the full criteria a single-target query has to meet, the patterns that break it, and how to check a query with `infrahubctl graphql query-report` before you deploy the definition, see [Single-target queries](../development-resources/graphql/single-target-queries).


P2: Custom agent: Flag AI Slop and Fabricated Changes

The documented infrahubctl graphql query-report command is unavailable in this change because the pinned python_sdk submodule was not bumped. Remove this instruction until the SDK update lands, or merge the matching SDK bump with the documentation.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/artifacts/overview.mdx, line 141: <comment>The documented `infrahubctl graphql query-report` command is unavailable in this change because the pinned `python_sdk` submodule was not bumped. Remove this instruction until the SDK update lands, or merge the matching SDK bump with the documentation.</comment> <file context> @@ -86,12 +86,62 @@ For step-by-step instructions, see [Composing artifact content](./content-compos + +This returns a single device, because `$name` is required and the schema marks `name` as unique. + +For the full criteria a single-target query has to meet, the patterns that break it, and how to check a query with `infrahubctl graphql query-report` before you deploy the definition, see [Single-target queries](../development-resources/graphql/single-target-queries). + +Generator definitions are scoped the same way, from the same `parameters` mapping. See [Query parameter mapping](../generators/overview#query-parameter-mapping) for how the extraction paths are resolved. </file context>

Suggested change

For the full criteria a single-target query has to meet, the patterns that break it, and how to check a query with `infrahubctl graphql query-report` before you deploy the definition, see [Single-target queries](../development-resources/graphql/single-target-queries).

For the full criteria a single-target query has to meet and the patterns that break it, see [Single-target queries](../development-resources/graphql/single-target-queries).

Same false positive as the one already answered on dev/knowledge/backend/query-target-uniqueness.md - the command and both options exist at the currently pinned submodule commit, so no bump is needed.

$ git -C python_sdk show 13f26b0:infrahub_sdk/ctl/graphql.py | grep -nE '"--online"|branch: str|name="query-report"' 112:@app.command(name="query-report") 118: "--online", 124: branch: str | None = typer.Option(None, help="Branch on which to run the report."),

query-report, --online and --branch all shipped together in opsmill/infrahub-sdk-python#976, which is an ancestor of the pinned 13f26b0. The companion SDK PR only rewrites the command's --help text.

Bumping the pointer here would be the actual problem: it would tie this PR to an unmerged SDK commit.

dgarros · 2026-08-17T20:22:16Z

@@ -0,0 +1,88 @@
+# 20. Analyzer is the single source of truth for query targeting


an ADR feels a bit overkill for this feature but I guess our current guidelines to define what should be an ADR or not aren't clearly defined

github-actions Bot added type/documentation Improvements or additions to documentation type/spec A specification for an upcoming change to the project labels Aug 17, 2026

ogenstad mentioned this pull request Aug 17, 2026

docs: explain what query-report reports and where the query name comes from opsmill/infrahub-sdk-python#1253

Merged

cubic-dev-ai Bot reviewed Aug 17, 2026

View reviewed changes

ogenstad mentioned this pull request Aug 17, 2026

Follow up docs (ifc-2504-graphql-query-report) - For discussion #9056

Closed

ogenstad force-pushed the pog-document-query-target-uniqueness branch from f58c800 to 342ec38 Compare August 17, 2026 13:13

ogenstad force-pushed the pog-document-query-target-uniqueness branch from 342ec38 to 06c9e57 Compare August 17, 2026 14:54

cubic-dev-ai Bot reviewed Aug 17, 2026

View reviewed changes

dgarros approved these changes Aug 17, 2026

View reviewed changes

saltas888 mentioned this pull request Aug 21, 2026

docs: harvest review lessons from PRs reviewed 2026-08-14 to 2026-08-21 #10360

Draft

5 tasks

Navigation Menu

Uh oh!

docs: document how query targeting scopes artifact regeneration [IFC-2504] - #10293

docs: document how query targeting scopes artifact regeneration [IFC-2504]#10293
ogenstad wants to merge 1 commit into
stablefrom
pog-document-query-target-uniqueness

ogenstad commented Aug 17, 2026 •

edited

Loading

Uh oh!

cubic-dev-ai Bot left a comment

Uh oh!

cubic-dev-ai Bot Aug 17, 2026

Uh oh!

ogenstad Aug 17, 2026

Uh oh!

cubic-dev-ai Bot Aug 17, 2026

Uh oh!

ogenstad Aug 17, 2026

Uh oh!

cubic-dev-ai Bot left a comment

Uh oh!

cubic-dev-ai Bot Aug 17, 2026

Uh oh!

ogenstad Aug 18, 2026

Uh oh!

cubic-dev-ai Bot Aug 17, 2026

Uh oh!

ogenstad Aug 18, 2026

Uh oh!

dgarros Aug 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	- Spec: [`specs/archive/ifc-2504-graphql-query-report/research.md`](../../specs/archive/ifc-2504-graphql-query-report/research.md) (RES-001).
	- Spec: [`specs/archive/ifc-2504-graphql-query-report/research.md`](../specs/archive/ifc-2504-graphql-query-report/research.md) (RES-001).


		This returns a single device, because `$name` is required and the schema marks `name` as unique.

		For the full criteria a single-target query has to meet, the patterns that break it, and how to check a query with `infrahubctl graphql query-report` before you deploy the definition, see [Single-target queries](../development-resources/graphql/single-target-queries).

		@@ -0,0 +1,88 @@
		# 20. Analyzer is the single source of truth for query targeting

Uh oh!

Conversation

ogenstad commented Aug 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed

User-facing docs

Internal docs

Note on the ADR number

Related

Testing

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Aug 17, 2026

Choose a reason for hiding this comment

Uh oh!

ogenstad Aug 17, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Aug 17, 2026

Choose a reason for hiding this comment

Uh oh!

ogenstad Aug 17, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Aug 17, 2026

Choose a reason for hiding this comment

Uh oh!

ogenstad Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Aug 17, 2026

Choose a reason for hiding this comment

Uh oh!

ogenstad Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

dgarros Aug 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ogenstad commented Aug 17, 2026 •

edited

Loading