docs(dsl): state that path_finding always requires rel_types

What does this MR do and why?

Path queries without relationship types are rejected, but the query schema and the query language guide say they are optional when both endpoints are pinned by ID, so an agent that follows the schema gets a validation error. This states the rule the compiler has applied since !1621 (merged), and points the guide's path example the way path finding traverses, so it returns rows.

Closes #1329 (closed)

Testing

Before, the path relationship types description the schema serves:

Relationship types to traverse. Required when an endpoint is constrained by filters or id_range; optional when both endpoints use node_ids.

After:

Relationship types to traverse, each followed only in its defined direction. Required, including when both endpoints use node_ids.

Checked locally: markdownlint-cli2 0.22.1 with this repository's configuration reports no errors on the changed Markdown; Vale with .vale.ini reports no errors, and the same warnings as on main; scripts/linting/prose_lint.py passes on the skill files; the schema is valid JSON; and the skill copy is byte-identical to the guide, which is what mise run skill:sync:orbit produces. I did not run lychee, and the change adds no links.

Performance Analysis

Text only: no query is accepted or rejected differently.

  • This merge request does not introduce any performance regression. If a performance regression is expected, explain why.
Agent context: long-form analysis, file-by-file walkthroughs, profiler output, alternatives considered

[skip pinned-version-check]: the check asks for a query_dsl bump because config/schemas/graph_query.schema.json changes, but only a description's text changes there, and no query is accepted or rejected differently, which is the case the check's own message says to skip. The query_dsl patch bump comes with the follow-up, which changes the schema's shape by making rel_types required, as agreed in the review.

Files:

  • config/schemas/graph_query.schema.json: PathConfig.rel_types.description.
  • docs/source/remote/queries/query-language.md, Path finding: the rel_types row, the paragraph under the table, a new paragraph on direction, and the example now runs User to Project.
  • skills/orbit/references/query_language.md: synced from the guide.
  • skills/orbit/references/recipes.md: the sentence above the path recipe.
  • skills/orbit/SKILL.md: version 0.33.1.
  • skills/orbit/SKILL.gql.md: version 0.33.1+gql, the JSON version plus +gql, as references/maintaining.md asks and gql_callers_get_the_gql_manifest checks. Nothing else in the GQL skill changes: GQL mode serves neither query_language.md nor recipes.md.
  • crates/orbit-server/src/grpc/service/tests/skills.rs and crates/orbit-server/src/skills/mod.rs: the four assertions that pin the skill versions, one of them the GQL version, moved with them. !2651 carries 0.33.2, so whichever of the two merges second conflicts on these lines and is rebased with a version above the other's: the CLI caches the skill by version, so the same version must not ship different content.

Evidence that the old example returned nothing: on GitLab.com, the guide's query with my own IDs (Project to User, CREATOR, AUTHORED, IN_PROJECT) answered row_count: 0, and the same query from User to Project answered two paths. The rule itself: check_path in crates/query-engine/compiler/src/passes/validate.rs, pinned by the node_ids case of its path test.

Edited by José M. Requena Plens

Merge request reports

Loading
Loading