suggest_joins
Read-onlyIdempotent
Find join paths between known tables by providing qualified names. Returns shortest foreign key path per pair with columns ready for SQL JOIN, or identifies unreachable pairs.
Instructions
Use this when you already know two or more tables and need the join paths between them. Pass qualified names (schema.table) and get one shortest FK path per pair, with columns on each side ready for a SQL JOIN. Multi-hop paths via intermediates are returned; pairs with no path within max_hops (default 6) land in unreachable_pairs. Use find_relevant_tables instead when you don't yet know the table names. Common composition: chain find_relevant_tables to suggest_joins.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tables | Yes | List of `schema.table` qualified names (minimum 2) to find join paths between. The tool returns one shortest FK path per unordered pair, plus an `unreachable_pairs` list for pairs with no path within `max_hops`. | |
| max_hops | No | Maximum number of FK-graph hops to traverse when searching for join paths. Default 6 — covers M:N junction-table chains common in normalised OLTP schemas. Increase only for unusually deep schemas; higher values make the search non-trivially slower. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | ||
| data | No | ||
| error | No | ||
| confidence | No | ||
| provenance | No | ||
| follow_up_hints | No | ||
| degradation_reason | No | ||
| charter_version | No | 1.2 |