Clarify USING Clause Equivalence and Document NATURAL Join Limitation in Relational API

[isaacnfairplay]

Description:
The current DuckDB documentation for the Relational API does not explain that specifying a comma-separated list of column names in the join method is equivalent to the SQL USING clause. Additionally, the documentation does not clarify that NATURAL JOIN is not supported in the Relational API. These gaps may lead to confusion for users familiar with SQL standards.

Proposed Improvements:

1. Document USING Clause Equivalence:

   • Clearly state that passing a comma-separated list of column names (e.g., "id, date") to the join method is functionally equivalent to the SQL USING clause.
   • Provide examples across join types (INNER, LEFT, RIGHT, etc.).

   Example:

   result = rel1.join(rel2, "id, date", how="inner")
   # Equivalent to SQL: ... USING (id, date)
   result.show()

2. Highlight NATURAL Join Limitation:

   • Explicitly note that NATURAL JOIN is not supported in the Relational API.
   • Explain that users must explicitly list matching columns to achieve similar functionality.

3. Provide a Workaround for NATURAL Join:

   • Demonstrate how to replicate NATURAL JOIN behavior by explicitly specifying columns using the join method.

   Example Workaround:

   # Mimicking NATURAL JOIN by specifying common columns
   result = rel1.join(rel2, "id, date", how="inner")
   result.show()

4. Update Documentation with Compatibility Table:

   • Add a table indicating which join types (INNER, LEFT, RIGHT, FULL OUTER, ANTI, SEMI, etc.) are compatible with the USING clause.
   • Note that NATURAL JOIN is not available.

Benefits:

• Enhances clarity by explicitly documenting an important feature (USING clause equivalence).
• Provides transparency about the lack of NATURAL JOIN support.
• Offers clear guidance and workarounds to help users achieve expected functionality.

Relevant Section: Relational API Documentation