feat: Add @join:unique and @join:required hints for safe join removal

[stevehansen]

Introduce SQL comment-based join cardinality hints that let view authors
declare whether a join follows a foreign key (unique match) and whether
that FK is required (NOT NULL). The tool uses these hints combined with
the join type to determine if removal is safe:

• LEFT JOIN + @join:unique → safe (at most 1 match, all rows preserved)
• INNER JOIN + @join:unique + @join:required → safe (exactly 1 match)
• INNER JOIN + @join:unique (no @required) → not safe (may filter rows)
• No hint → backward-compatible existing behavior

Hints are placed as SQL comments near the JOIN clause:
LEFT JOIN /* @join:unique / dbo.B b ON a.BId = b.Id
INNER JOIN / @join:unique @join:required */ dbo.Status s ON s.Id = p.StatusId

https://claude.ai/code/session_01QmAhVuiQRDaotn1cAXBbrJ

[gemini-code-assist]

Summary of Changes

Hello @stevehansen, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the SQL inliner tool by providing a mechanism for view authors to explicitly guide the safe removal of unused joins. By embedding specific hints within SQL comments, the inliner can now make more informed decisions about which joins can be stripped without affecting the query's row count or semantics, leading to potentially more optimized SQL output.

Highlights

• New Join Cardinality Hints: Introduced SQL comment-based hints, @join:unique and @join:required, allowing view authors to declare join cardinality and nullability properties.
• Safe Join Removal Logic: Implemented logic to use these hints, combined with the join type (LEFT JOIN, INNER JOIN), to determine if an unused join can be safely removed without altering query results.
• Backward Compatibility: Maintained existing behavior for joins without hints, where unused joins are still stripped.
• Comprehensive Testing: Added extensive unit tests to validate the parsing of join hints and the correctness of the safe removal logic under various scenarios, including case-insensitivity and multiple hints.

Changelog

• src/SqlInliner.Tests/JoinHintTests.cs
  • Added new test file to cover various scenarios for join hint parsing and safe removal logic.
  • Included tests for LEFT JOIN with unique hint, INNER JOIN with unique and required hints, and INNER JOIN with only unique hint.
  • Verified backward compatibility for joins without hints.
  • Tested hint parsing when placed after the alias and with separate hint comments.
  • Ensured hints are parsed case-insensitively.
• src/SqlInliner/DatabaseViewInliner.cs
  • Modified DetectUnusedTablesToStrip method to check for join hints before stripping unused joins.
  • Introduced a new private static method IsJoinSafeToRemove to encapsulate the logic for determining if a join can be safely removed based on its hint and type.
  • Added a warning message when a join hint prevents the removal of an otherwise unused join.
• src/SqlInliner/JoinHint.cs
  • Added a new JoinHint enum with None, Unique, and Required flags.
  • Provided XML documentation explaining the purpose and usage of the join hints, including safety rules for removal.
• src/SqlInliner/ReferencesVisitor.cs
  • Added JoinTypes and JoinHints dictionaries to store the type and parsed hints for each named table reference in a qualified join.
  • Updated the ExplicitVisit(QualifiedJoin node) method to populate these new dictionaries.
  • Implemented a ParseJoinHints static method to extract @join:unique and @join:required from SQL comments within a QualifiedJoin node's token stream.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

The pull request introduces a valuable feature by allowing SQL comment-based join cardinality hints (@join:unique and @join:required). This enables the inliner to make more intelligent decisions about safely stripping unused joins, preventing potential data changes. The implementation includes comprehensive test cases covering various scenarios, and the logic for parsing hints and determining join removal safety appears robust and well-considered. The JoinHint enum is appropriately defined as a [Flags] enum with clear documentation. Overall, this is a well-executed enhancement that improves the utility and safety of the SQL inliner.