Skip to content

Add relations() virtual table tests and documentation#9240

Draft
khanaffan wants to merge 1 commit into
masterfrom
affan.khan/relations-vtab-docs-tests
Draft

Add relations() virtual table tests and documentation#9240
khanaffan wants to merge 1 commit into
masterfrom
affan.khan/relations-vtab-docs-tests

Conversation

@khanaffan
Copy link
Copy Markdown
Contributor

Summary

Add comprehensive tests and documentation for the new experimental relations() virtual table (ECVLib.Relations), which provides fast one-hop relationship traversal.

Depends on iTwin/imodel-native#1400 — the native vtab implementation.

Changes

Tests (core/backend/src/test/ecdb/RelationsVTab.test.ts)

  • 16 active tests covering:
    • Link-table traversal (forward, backward, both, relationship class, unqualified syntax)
    • JOIN with entity class, subquery filtering
    • Multi-hop BFS, depth-limited BFS
    • Recursive CTE (full chain + depth limit)
    • Chained multi-hop via cross-join
    • Graph intersection and union
    • Edge cases (isolated node)
    • Real iModel (BIS relationships from root subject)
  • 3 skipped (nav-prop and mixed — not yet supported by vtab)
  • All queries use ECSQLOPTIONS ENABLE_EXPERIMENTAL_FEATURES

Documentation

  • docs/learning/ECSqlReference/RelationsVTab.md — ECSQL reference: syntax, columns, examples (basic, directional, JOIN, cross-join, chained, recursive CTE, subquery), TypeScript usage, comparison table
  • docs/learning/backend/RelationshipTraversal.md — Practical patterns: 6 patterns (neighbors, directional, JOINs, multi-hop CTE/cross-join/BFS, graph set ops, impact analysis)
  • docs/changehistory/NextVersion.md — Changelog entry with experimental note and examples
  • Navigation links added to index.md and leftNav.md

All docs include prominent experimental feature callouts noting the ECSQLOPTIONS ENABLE_EXPERIMENTAL_FEATURES requirement.

Validation

  • Targeted verification: npx mocha --grep "relations" lib/cjs/test/ecdb/RelationsVTab.test.js16 passing, 3 pending
  • Known baseline issues: None related to this PR

- Add comprehensive test suite (RelationsVTab.test.ts) with 16 tests covering
  link-table traversal, JOINs, recursive CTE, chained cross-join, BFS,
  graph set operations, edge cases, and real iModel traversal
- All queries use ECSQLOPTIONS ENABLE_EXPERIMENTAL_FEATURES (feature is experimental)
- Add ECSQL reference doc (RelationsVTab.md) with syntax, examples, and notes
- Add practical patterns guide (RelationshipTraversal.md) with 6 patterns
- Update NextVersion.md changelog with experimental note and CTE examples
- Add navigation links in index.md and leftNav.md

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant