The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
[MBQL lib] Add user docs for joins to `lib.core` (#71442)
Braden Shepherdson8020b65546ed
diff --git a/src/metabase/lib/core.cljc b/src/metabase/lib/core.cljcindex 5c7a0c4b69d..a9cf7e9a884 100644--- a/src/metabase/lib/core.cljc+++ b/src/metabase/lib/core.cljc@@ -77,7 +77,7 @@[metabase.lib.filter.simplify-compound][metabase.lib.filter.update :as lib.filter.update][metabase.lib.join :as lib.join]- [metabase.lib.join.util]+ [metabase.lib.join.util :as lib.join.util][metabase.lib.limit :as lib.limit][metabase.lib.measure :as lib.measure][metabase.lib.metadata]@@ -104,8 +104,10 @@[metabase.lib.schema.common :as lib.schema.common][metabase.lib.schema.expression :as lib.schema.expression][metabase.lib.schema.id :as lib.schema.id]+ [metabase.lib.schema.join :as lib.schema.join][metabase.lib.schema.metadata :as lib.schema.metadata][metabase.lib.schema.ref :as lib.schema.ref]+ [metabase.lib.schema.temporal-bucketing :as lib.schema.temporal-bucketing][metabase.lib.schema.util][metabase.lib.segment :as lib.segment][metabase.lib.serialize]@@ -186,7 +188,7 @@metabase.lib.filter.simplify-compound/keep-melib.filter/keep-melib.join/keep-me- metabase.lib.join.util/keep-me+ lib.join.util/keep-melib.limit/keep-memetabase.lib.metadata/keep-melib.metadata.calculation/keep-me@@ -710,6 +712,388 @@time-intervalsegment]) ; TODO: Move segment to sit with the `lib.segment` functions.+;;; ## Joins+;;; Joins, often referred to as "explicit joins" to distinguish them from *implicit joins*, combine the source query+;;; (the "left-hand side" or LHS) with a new source or subquery (the "right-hand side" or RHS).+;;;+;;; The columns of the RHS are added to those of the LHS. Combining the data rows is more complicated, and depends+;;; on the *strategy* and *conditions*. Metabase supports four join strategies:+;;;+;;; - `:left-join` (the default) is a left outer join+;;; - `:right-join` is a right outer join+;;; - `:full-join` is a full outer join, the union of `:left-join` and `:right-join`+;;; - `:inner-join` is an inner join, returning exactly the intersection without `NULL`s+;;; - *Cross joins*, with one row for every pair of LHS and RHS rows regardless of the conditions, are not supported.+;;;+;;; Join *conditions* are similar to top-level filters, but there are three differences. First, only a handful of+;;; operators are supported. Second, there are no literals - the first argument is always a LHS column and the second+;;; always a RHS column. Third, one or both of those columns can have **temporal bucketing** applied before comparison.+;;; This only applies to the condition; those columns are not bucketed elsewhere in the query.+;;;+;;; ### Aliases+;;; Join *aliases* are stage-unique names for each join. They are not user editable in the current FE, though MBQL's+;;; data model would support it. Aliases are an arbitrary string, and default to the *display name of the RHS* - a+;;; table or card. If the aliases collides with another, it gets disambiguated as `foo_2`, `foo_3`, etc.++(mu/defn join :- ::lib.schema/query+ "Add an explicit join to the target stage of `a-query`.++ The `a-join-or-joinable` can be either a proper join clause as returned by [[join-clause]], or any *joinable*. See+ the docstring for [[join-clause]] for what can be passed in as a *joinable*.++ The new join can be incomplete in several ways; this function populates any missing join parameters with defaults:+ - Strategy defaults to `:left-join`.+ - Join aliases default to the display name of the RHS - the table' or card's display name.+ - Selected fields defaults to `:all` on the join, or nil if the target stage (of `a-query`) has aggregations or+ breakouts.+ - Conditions are complicated. See [[suggested-join-conditions]] for the details.++ The new join is appended as the last on the target stage.++ **Code Health:** Healthy. This is a core API."++ ([a-query a-join-or-joinable] (join a-query -1 a-join-or-joinable))+ ([a-query :- ::lib.schema/query+ stage-number :- :int+ a-join-or-joinable :- [:or ::lib.join.util/partial-join ::lib.join/joinable]]+ (lib.join/join a-query stage-number a-join-or-joinable)))++(mu/defn join-clause :- ::lib.join.util/partial-join+ "Construct a join clause from `a-joinable`, which can serve as the RHS of a join. This clause is \"freestanding\";+ it is not part of any particular query.++ The returned clause is also partially populated, since some details (alias, etc.) can't be specified until the clause+ is attached to a query.++ Valid *joinables* include:++ - Table metadata (`lib.metadata/table`)+ - Card metadata (`lib.metadata/card`)+ - Another query (MBQL or native)+ - A join clause - it's an identity function++ There are some optional arguments:++ - `conditions` is a list of boolean expressions or expression editor ASTs; see [[with-join-conditions]].+ - `strategy` is one of the strategy keywords: `:left-join`, `:right-join`, `:inner-join`, or `:full-join`.+ - See also [[available-join-strategies]], since some engines only support certain kinds of joins.++ **Code Health:** Healthy. This is a core API."+ ([a-joinable] (lib.join/join-clause a-joinable))+ ([a-joinable conditions] (lib.join/join-clause a-joinable conditions))+ ([a-joinable conditions strategy] (lib.join/join-clause a-joinable conditions strategy)))++(mu/defn joins :- [:maybe ::lib.schema.join/joins]+ "Return the list of all explicit join clauses on the target stage of `a-query`, or nil if there are none.++ **Code Health:** Healthy. This is a core API."+ ([a-query] (joins a-query -1))+ ([a-query :- ::lib.schema/query+ stage-number :- :int]+ (lib.join/joins a-query stage-number)))++;;; ### Join Strategies++(mu/defn join-strategy :- ::lib.schema.join/strategy.option+ "Get the strategy (join type) of `a-join-clause`, a complete join clause either under construction with+ [[join-clause]] or returned by [[joins]].++ The return value is a map, not a bare keyword, to support [[display-name]] and similar functions.++ **Code Health:** Healthy. This is a core API."+ [a-join-clause :- ::lib.join.util/partial-join]+ (lib.join/join-strategy a-join-clause))++(mu/defn with-join-strategy :- ::lib.join.util/partial-join+ "Sets the strategy of `a-join-clause` to the provided `strategy`.++ The strategy can be either the raw keyword (e.g. `:left-join`) or a map from [[available-join-strategies]].++ **Code Health:** Healthy. This is a core API."+ [a-join-clause :- ::lib.join.util/partial-join+ strategy :- [:or ::lib.schema.join/strategy ::lib.schema.join/strategy.option]]+ (lib.join/with-join-strategy a-join-clause strategy))++(mu/defn available-join-strategies :- [:sequential ::lib.schema.join/strategy.option]+ "Get the list of available join strategies for `a-query`.++ This doesn't really depend on the *query*, but on its target *database*, since different (versions of) database+ engines support different kinds of joins.++ The return value is a map, not a bare keyword. This allows the join strategies to answer [[display-name]] and similar+ generic calls. See the schema `::lib.schema.join/strategy.option` for the full details.++ `stage-number` is ignored and deprecated - the stage doesn't affect the possible joins.++ **Code Health:** Healthy with one arg, Deprecated with two args."+ ([a-query :- ::lib.schema/query]+ (lib.join/available-join-strategies a-query))+ ([a-query :- ::lib.schema/query+ _stage-number :- :int]+ (available-join-strategies a-query)))++;;; ### Join Conditions+;;; Join conditions are a special case of boolean expressions. They differ from [[filters]] in three ways:+;;;+;;; - Only a few operators are supported (mainly `=` and similar)+;;; - First arg is always a column from the LHS (the containing stage), second arg from the RHS.+;;; - The columns can be bucketed by temporal unit, similar to breakouts, but without affecting the original columns.+;;;+;;; There can be multiple join conditions on a single join. The conditions are often based on a foreign key+;;; relationship, but they don't need to be.++(mu/defn join-conditions :- [:maybe ::lib.schema.join/conditions]+ "Returns the list of conditions on `a-join-clause`, either under construction with [[join-clause]] or from [[joins]].+ Nil if there are no conditions.++ **Code Health:** Healthy. This is a core API."+ [a-join-clause :- ::lib.join.util/partial-join]+ (lib.join/join-conditions a-join-clause))++(mu/defn with-join-conditions :- ::lib.join.util/partial-join+ "Replaces the conditions on `a-join` with the provided `conditions`, returning the updated join clause.++ Note that this **does not** update the query `a-join` is attached to! That requires a [[replace-clause]] call.+ For a join clause still under construction, note that `conditions` can also be passed directly to [[join-clause]]+ if that is more convenient.++ The conditions should be a sequence of either MBQL clauses or expression editor ASTs from [[expression-clause]].+ Passing `conditions` as nil will remove the conditions from this join clause.++ **Code Health:** Healthy. This is a core API."+ [a-join :- ::lib.join.util/partial-join+ conditions :- [:maybe [:sequential [:or ::lib.schema.expression/boolean ::lib.schema.common/external-op]]]]+ (lib.join/with-join-conditions a-join conditions))++(mu/defn suggested-join-conditions :- [:maybe [:sequential {:min 1} ::lib.schema.expression/boolean]]+ "Given `a-query` and `a-joinable` - the LHS and RHS of a (real or contemplated) join - return a suggested or default+ join condition. See [[join-clause]] for the definition of *joinables*.++ If `position` is provided, only joins at earlier indexes in [[joins]] than `position` are considered as sources of+ the LHS column for the suggested condition. This is necessary when editing a join in the UI. When `position` is nil+ (the default) then all joins on the target stage of `a-query` are considered.++ There are two cases for suggested joins, which are checked in this order:++ - A FK in the LHS points to a PK in the RHS, e.g. joining `Orders` to `Products` on `Orders.PRODUCT_ID`.+ - A FK in the RHS points back at a PK in the LHS, e.g. joining `Products` to `Orders` on `Orders.PRODUCT_ID`.++ When there are several FKs available which could be suggested, the *leftmost* is preferred. So FKs from the main+ source have priority over joined FKs, and earlier joins have priority over later ones. Of course all such FKs are+ *valid* join conditions! But the suggestion needs to pick just one, and it prefer the leftmost.++ If no plausible FK/PK pairs are found, this function returns nil and the join does not get a default condition.++ **Code Health:** Healthy. This is a core API."+ ([a-query a-joinable] (suggested-join-conditions a-query -1 a-joinable))+ ([a-query stage-number a-joinable] (suggested-join-conditions a-query stage-number a-joinable nil))+ ([a-query :- ::lib.schema/query+ stage-number :- :int+ a-joinable :- ::lib.join/join-or-joinable+ position :- [:maybe :int]]+ (lib.join/suggested-join-conditions a-query stage-number a-joinable position)))++(mu/defn join-condition-lhs-columns :- [:sequential ::lib.schema.metadata/column]+ "Returns the list of column metadata for those columns which can be used as the left-hand-side (source column) in a+ join condition for `a-joinable`.++ This is the LHS counterpart to [[join-condition-rhs-columns]].++ If `a-joinable` is a join clause already attached to the target stage of `a-query`, its own columns will be removed+ from the list, since they cannot be the LHS column.++ - `lhs-expression-or-nil` should be the current LHS column, if any. Then it can be marked as selected in the output.+ - `rhs-expression-or-nil` should be the current RHS column, if any.+ - Theoretically this could be used to return only LHS columns which can be compared with the chosen RHS.+ - In practice, this parameter is *unused* - we don't grok the comparisons different DBs (dis)allow well enough.++ **Code Health:** Healthy. This is the correct way to get the columns for software or a user to pick as the LHS of+ a join condition."+ ([a-query a-joinable lhs-expression-or-nil rhs-expression-or-nil]+ (join-condition-lhs-columns a-query -1 a-joinable lhs-expression-or-nil rhs-expression-or-nil))+ ([a-query :- ::lib.schema/query+ stage-number :- :int+ a-joinable :- [:maybe ::lib.join/join-or-joinable]+ lhs-expression-or-nil :- [:maybe ::lib.schema.expression/expression]+ rhs-expression-or-nil :- [:maybe ::lib.schema.expression/expression]]+ (lib.join/join-condition-lhs-columns a-query stage-number a-joinable lhs-expression-or-nil rhs-expression-or-nil)))++(mu/defn join-condition-rhs-columns :- [:sequential ::lib.schema.metadata/column]+ "Returns the list of column metadata for those columns which can be used as the right-hand-side (joined column) in a+ join condition for `a-joinable`.++ This is the RHS counterpart to [[join-condition-lhs-columns]].++ - `rhs-expression-or-nil` should be the current RHS column, if any. Then it can be marked as selected in the output.+ - `lhs-expression-or-nil` should be the current LHS column, if any.+ - Theoretically this could be used to return only RHS columns which can be compared with the chosen LHS.+ - In practice, this parameter is *unused* - we don't grok the comparisons different DBs (dis)allow well enough.++ **Code Health:** Healthy. This is the correct way to get the columns for software or a user to pick as the RHS of+ a join condition."+ ([a-query a-joinable lhs-expression-or-nil rhs-expression-or-nil]+ (join-condition-rhs-columns a-query -1 a-joinable lhs-expression-or-nil rhs-expression-or-nil))+ ([a-query :- ::lib.schema/query+ stage-number :- :int+ a-joinable :- ::lib.join/join-or-joinable+ lhs-expression-or-nil :- [:maybe ::lib.schema.expression/expression]+ rhs-expression-or-nil :- [:maybe ::lib.schema.expression/expression]]+ (lib.join/join-condition-rhs-columns a-query stage-number a-joinable lhs-expression-or-nil rhs-expression-or-nil)))++(mu/defn join-condition-operators :- [:sequential ::lib.schema.join/condition.operator]+ "Return a sequence of filter clause operators that are valid for use in a join condition.++ The `lhs-expression-or-nil` and `rhs-expression-or-nil` parameters should be set to the LHS and RHS columns for this+ join condition, if already set. (See [[join-condition-lhs-columns]] and [[join-condition-rhs-columns]] for details.)+ However, this inputs are **currently ignored** because we do not grok what operators can be used for what column types+ on a given database well enough to get it right. See #31174.++ The returned operators are maps, so that they can support [[display-name]] etc.++ **Code Health:** Healthy."+ ([a-query lhs-expression-or-nil rhs-expression-or-nil]+ (join-condition-operators a-query -1 lhs-expression-or-nil rhs-expression-or-nil))+ ([a-query :- ::lib.schema/query+ stage-number :- :int+ lhs-expression-or-nil :- [:maybe ::lib.schema.expression/expression]+ rhs-expression-or-nil :- [:maybe ::lib.schema.expression/expression]]+ (lib.join/join-condition-operators a-query stage-number lhs-expression-or-nil rhs-expression-or-nil)))++(mu/defn join-condition-update-temporal-bucketing :- ::lib.schema.expression/boolean+ "Given a provided `join-condition` clause, and the context of `a-query` and target stage, adjusts the temporal+ bucketing of the columns in this condition and returns the updated condition.++ Note that this **does not** update the query, only return an adjusted condition clause.++ The condition must be a *standard* join condition, of the kind returned by [[suggested-join-conditions]], or this+ function will do nothing. That means the both arguments are simple columns and not subexpressions, constants, etc.++ If either of the columns does not support the requested unit (e.g. bucketing a date by `:hour`) then the bucketing+ of just that column is unchanged.++ Passing an `option-or-unit` of nil will un-set the bucketing of both arguments.++ **Code Health:** Healthy."+ ([a-query join-condition option-or-unit]+ (join-condition-update-temporal-bucketing a-query -1 join-condition option-or-unit))+ ([a-query :- ::lib.schema/query+ stage-number :- :int+ join-condition :- [:or ::lib.schema.expression/boolean ::lib.schema.common/external-op]+ option-or-unit :- [:maybe [:or ::lib.schema.temporal-bucketing/option ::lib.schema.temporal-bucketing/unit]]]+ (lib.join/join-condition-update-temporal-bucketing a-query stage-number join-condition option-or-unit)))++;;; ### Join columns and projection+;;; Like a main source, joins support selecting only a subset of fields to return from a query. By default, when a join+;;; clause is added to a query, all its fields are selected. The deselected fields are not returned, but they are not+;;; *hidden* either. You can deselect a field but still use it in a filter or expression on the same stage.++(mu/defn join-fields :- [:maybe ::lib.schema.join/fields]+ "Returns the list of column references for the fields selected on `a-join`, or the keyword `:all`, or nil.++ Nil means unspecified, which means \"none\" for joins. **Note** that this differs from the default on the main source!++ **Code Health:** Healthy. This is a core API."+ [a-join :- ::lib.join.util/partial-join]+ (lib.join/join-fields a-join))++(mu/defn with-join-fields :- ::lib.join.util/partial-join+ "Updates `a-join` to set the fields it should be returning to the provided `fields`.++ `fields` is one of the following:++ - `:all`, to return all the fields+ - `:none`, to confirm that no fields are returned+ - Nil, to remove the fields setting entirely and rely on the default (return nothing)+ - A list of column metadata or references for columns from the RHS of `a-join`.++ To get a list of all columns this join *could* return in order to filter them, see [[join-fieldable-columns]].++ **Code Health:** Healthy. This is a core API."+ {:style/indent [:form]}+ [a-join :- ::lib.join.util/partial-join+ fields :- [:maybe [:or [:enum :all :none] [:sequential some?]]]] ;; TODO: More precise schema.+ (lib.join/with-join-fields a-join fields))++(mu/defn join-fieldable-columns :- ::lib.metadata.calculation/visible-columns+ "Returns the list of column metadata for the columns which are *visible* on the RHS of `a-joinable`, such as a table,+ card or join clause.++ These columns are exactly those which can correctly be passed to [[with-join-fields]]. If `a-joinable` is properly a+ join clause, the columns will be marked with `:selected true`.++ Note that this ignores any [[join-fields]] setting - this is about the visible columns from the RHS, not those which+ are selected to be returned.++ **Code Health:** Healthy. This is a core API."+ ([a-query a-joinable] (join-fieldable-columns a-query -1 a-joinable))+ ([a-query :- ::lib.schema/query+ stage-number :- :int+ a-joinable :- ::lib.join/join-or-joinable]+ (lib.join/joinable-columns a-query stage-number a-joinable)))++;;; ### Display names and aliases++(mu/defn join-lhs-display-name :- ::lib.schema.common/non-blank-string+ "Get the display name to use for the **LHS** of `a-joinable`.++ The RHS gets its display name from the table, card, etc. being joined. But we render the LHS in the UI with a display+ name based on *where the LHS column of the first join condition came from*, if we can determine that safely.++ If we can't determine a good display name for the LHS, this function returns \"Previous results\".++ **Code Health:** Healthy, Single Use. This exists to support UIs, but it's well-defined and safe to call."+ ([a-query a-joinable]+ (join-lhs-display-name a-query a-joinable nil))+ ([a-query a-joinable condition-lhs-expression-or-nil]+ (join-lhs-display-name a-query -1 a-joinable condition-lhs-expression-or-nil))+ ([a-query :- ::lib.schema/query+ stage-number :- :int+ a-joinable :- [:maybe ::lib.join/join-or-joinable]+ condition-lhs-expression-or-nil :- [:maybe [:or ::lib.schema.metadata/column :mbql.clause/field]]]+ (lib.join/join-lhs-display-name a-query stage-number a-joinable condition-lhs-expression-or-nil)))++(mu/defn current-join-alias :- [:maybe ::lib.schema.join/alias]+ "Get the current join alias associated with a `column-or-join`, if it has one.++ **Code Health:** Leak. Join aliases are an internal detail and should not be exported. They're arbitrary and opaque+ on join clauses, and columns should come from lib already linked to their join. Don't roll your own column from+ elsewhere and then set its join alias."+ [field-or-join :- [:or+ ::lib.schema.metadata/column+ ::lib.join.util/partial-join+ [:ref :mbql.clause/field]]]+ (lib.join.util/current-join-alias field-or-join))++(mu/defn with-join-alias :- [:or+ ::lib.schema.metadata/column+ ::lib.join.util/partial-join+ [:ref :mbql.clause/field]]+ "Add **or remove** a specific `join-alias` to `field-or-join`, which must be column metadata, a column ref, or a join+ clause.++ This works on columns and clauses, not on queries. In particular, this won't change any references to a join's columns+ elsewhere in any query. If you want to update a join clause on a query *correctly*, making sure all its columns are+ still referenced correctly, use this function to update the join's alias, then use [[replace-clause]] to correctly+ update the query.++ **Code Health:** Leak. Join aliases should be treated as opaque, unique strings, so there should be no need to set+ them to any particular value on a join clause. For columns, the alias matters, but that should be internal to the lib.+ Users of lib should be getting columns from [[filterable-columns]] et al, not manually setting join aliases on column+ metadata or refs."+ {:style/indent [:form]}+ [field-or-join :- [:or+ ::lib.schema.metadata/column+ ::lib.join.util/partial-join+ [:ref :mbql.clause/field]]+ join-alias :- [:maybe ::lib.schema.common/non-blank-string]]+ (lib.join/with-join-alias field-or-join join-alias))++;;; **Code Health:** Leak. These helpers are only used from tests and the QP, and should be unexported.+(shared.ns/import-fns+ [lib.join+ join-fields-to-add-to-parent-stage ;; TODO: Unexport this; it's only used from tests and QP.+ raw-join-strategy]) ;; TODO: Unexport this; it's only used from tests.+;;; # Working with Expressions as an AST;;; Several parts of the FE want to work with clauses in a "white box" way, so it can render the details of the;;; expression in a structured way, or convert the AST of the expression parser into an expression, aggregation or@@ -853,29 +1237,6 @@update-lat-lon-filterupdate-numeric-filterupdate-temporal-filter]- [lib.join- available-join-strategies- join- join-clause- join-condition-lhs-columns- join-condition-operators- join-condition-rhs-columns- join-condition-update-temporal-bucketing- join-conditions- join-fields- join-fields-to-add-to-parent-stage- join-lhs-display-name- join-strategy- joinable-columns- joins- raw-join-strategy- suggested-join-conditions- with-join-alias- with-join-fields- with-join-strategy- with-join-conditions]- [metabase.lib.join.util- current-join-alias][lib.metricavailable-metrics][lib.limitdiff --git a/src/metabase/lib/join.cljc b/src/metabase/lib/join.cljcindex feb00c847ef..47d8573e3b0 100644--- a/src/metabase/lib/join.cljc+++ b/src/metabase/lib/join.cljc@@ -35,18 +35,19 @@[metabase.util.i18n :as i18n][metabase.util.log :as log][metabase.util.malli :as mu]+ [metabase.util.malli.registry :as mr][metabase.util.performance :refer [mapv run! some empty? not-empty get-in #?(:clj for)]]))(defn- join? [x](= (lib.dispatch/dispatch-value x) :mbql/join))-(def ^:private Joinable+(mr/def ::joinable[:or ::lib.schema.metadata/table ::lib.schema.metadata/card])-(def ^:private JoinOrJoinable+(mr/def ::join-or-joinable[:or[:ref ::lib.schema.join/join]- Joinable])+ ::joinable])(declare with-join-alias)@@ -757,7 +758,7 @@([query :- ::lib.schema/querystage-number :- :int- a-join :- [:or ::lib.join.util/partial-join Joinable]]+ a-join :- [:or ::lib.join.util/partial-join ::joinable]](let [a-join (join-clause a-join)suggested-conditions (when (empty? (join-conditions a-join))(suggested-join-conditions query stage-number (joined-thing query a-join)))@@ -770,7 +771,7 @@(lib.util/update-query-stage query stage-number update :joins (fn [existing-joins](conj (vec existing-joins) a-join))))))-(mu/defn joined-thing :- [:maybe Joinable]+(mu/defn joined-thing :- [:maybe ::joinable]"Return metadata about the origin of `a-join` using `metadata-providerable` as the source of information."[metadata-providerable :- ::lib.schema.metadata/metadata-providerablea-join :- ::lib.join.util/partial-join]@@ -839,7 +840,7 @@If you are changing the LHS of a condition for an existing join, pass in that existing join as `join-or-joinable` sowe can filter out the columns added by it (it doesn't make sense to present the columns added by a join as optionsfor its own LHS) or added by later joins (joins can only depend on things from previous joins). Otherwise you can- either pass in `nil` or the [[Joinable]] (Table or Card metadata) we're joining against when building a new+ either pass in `nil` or the [[::joinable]] (Table or Card metadata) we're joining against when building a newjoin. (Things other than joins are ignored, but this argument is flexible for consistency with the signatureof [[join-condition-rhs-columns]].) See #32005 for more info.@@ -857,7 +858,7 @@([query :- ::lib.schema/querystage-number :- :int- join-or-joinable :- [:maybe JoinOrJoinable]+ join-or-joinable :- [:maybe ::join-or-joinable]lhs-expression-or-nil :- [:maybe ::lib.schema.expression/expression];; not yet used, hopefully we will use in the future when present for filtering incompatible columns out._rhs-expression-or-nil :- [:maybe ::lib.schema.expression/expression]]@@ -904,7 +905,7 @@([query :- ::lib.schema/querystage-number :- :int- join-or-joinable :- JoinOrJoinable+ join-or-joinable :- ::join-or-joinable;; not yet used, hopefully we will use in the future when present for filtering incompatible columns out._lhs-expression-or-nil :- [:maybe ::lib.schema.expression/expression]rhs-expression-or-nil :- [:maybe ::lib.schema.expression/expression]]@@ -951,16 +952,16 @@[::target ::lib.schema.metadata/column]]]]]"Find FK columns in `source` pointing at a column in `target`. Includes the target column under the `::target` key.- `source` and `target` are `::current-stage` and a [[Joinable]], in either order; `::current-stage` means use the+ `source` and `target` are `::current-stage` and a [[::joinable]], in either order; `::current-stage` means use thestage in `query` at `stage-number`."[query :- ::lib.schema/querystage-number :- :intsource :- [:or[:= ::current-stage]- Joinable]+ ::joinable]target :- [:or[:= ::current-stage]- Joinable]]+ ::joinable]](let [current-stage-cols (fn [](let [opts {:include-implicitly-joinable? false:include-implicitly-joinable-for-source-card? false}]@@ -1053,11 +1054,11 @@;;; with [[metabase.lib.field/fieldable-columns]] and be less confusing(mu/defn joinable-columns :- ::lib.metadata.calculation/visible-columns"Return information about the fields that you can pass to [[with-join-fields]] when constructing a join against- something [[Joinable]] (i.e., a Table or Card) or manipulating an existing join. When passing in a join, currently+ something [[::joinable]] (i.e., a Table or Card) or manipulating an existing join. When passing in a join, currentlyselected columns (those in the join's `:fields`) will include `:selected true` information."[query :- ::lib.schema/querystage-number :- :int- join-or-joinable :- JoinOrJoinable]+ join-or-joinable :- ::join-or-joinable](let [a-join (when (join? join-or-joinable)join-or-joinable)source (if a-join@@ -1148,7 +1149,7 @@3. Otherwise use `Previous results`.This function needs to be usable while we are in the process of constructing a join in the context of a given stage,- but also needs to work for rendering existing joins. Pass a join in for existing joins, or something [[Joinable]]+ but also needs to work for rendering existing joins. Pass a join in for existing joins, or something [[::joinable]]for ones we are currently building."([query join-or-joinable](join-lhs-display-name query join-or-joinable nil))@@ -1158,7 +1159,7 @@([query :- ::lib.schema/querystage-number :- :int- join-or-joinable :- [:maybe JoinOrJoinable]+ join-or-joinable :- [:maybe ::join-or-joinable]condition-lhs-expression-or-nil :- [:maybe [:or ::lib.schema.metadata/column :mbql.clause/field]]](or(join-lhs-display-name-from-condition-lhs query stage-number join-or-joinable condition-lhs-expression-or-nil)diff --git a/src/metabase/lib/js.cljs b/src/metabase/lib/js.cljsindex fd84f1cdaa2..63387cc26ca 100644--- a/src/metabase/lib/js.cljs+++ b/src/metabase/lib/js.cljs@@ -2155,6 +2155,8 @@;; TODO: Move all the join logic into one block - it's scattered all through the lower half of this namespace.+;; TODO: (bshepherdson, 2026-03-25) The name of this function was changed in lib.core and this should probably change+;; to match it.(defn ^:export joinable-columns"Returns a JS array of columns that are available when joining `join-or-joinable` into `a-query`.@@ -2172,7 +2174,7 @@[a-query stage-number join-or-joinable];; TODO: It's not practical to cache this currently. We need to be able to key off the query and the joinable, which;; is not supported by the lib.cache system.- (to-array (lib.core/joinable-columns a-query stage-number join-or-joinable)))+ (to-array (lib.core/join-fieldable-columns a-query stage-number join-or-joinable)));; TODO: table-or-card-metadata is too specific and leaks details of how sources are stored. We need a higher-level API;; for the sources of queries, especially with Metrics v2.diff --git a/test/metabase/lib/join_test.cljc b/test/metabase/lib/join_test.cljcindex ed8856b2c06..fa1f352f08f 100644--- a/test/metabase/lib/join_test.cljc+++ b/test/metabase/lib/join_test.cljc@@ -1263,7 +1263,7 @@{:lib/type :metadata/column, :name "LATITUDE"}{:lib/type :metadata/column, :name "LONGITUDE"}{:lib/type :metadata/column, :name "PRICE"}]- (lib/joinable-columns (lib.tu/venues-query) -1 table-or-card))+ (lib/join-fieldable-columns (lib.tu/venues-query) -1 table-or-card))(meta/table-metadata :venues)(:venues (lib.tu/mock-cards))))@@ -1291,7 +1291,7 @@;; FIXME -- joins replacement broken -- #32026;; query (lib/replace-clause query original-join join)query (assoc-in query [:stages 0 :joins] [join])- cols (lib/joinable-columns query -1 join)]+ cols (lib/join-fieldable-columns query -1 join)](is (=? [{:name "ID":lib/join-alias "Cat":lib/source :source/joinsdiff --git a/test/metabase/query_processor/implicit_joins_test.clj b/test/metabase/query_processor/implicit_joins_test.cljindex f23c9493786..3143a248d59 100644--- a/test/metabase/query_processor/implicit_joins_test.clj+++ b/test/metabase/query_processor/implicit_joins_test.clj@@ -270,7 +270,7 @@(mt/rows (qp/process-query query))))))(testing "Explicit join with long column name should use desired alias as source alias"(let [table-2 (lib.metadata/table mp (mt/id :long_col_name_2))- join-cols (lib/joinable-columns query -1 table-2)+ join-cols (lib/join-fieldable-columns query -1 table-2)fk-col (lib.metadata/field mp (mt/id :long_col_name :fk))id-col (m/find-first #(str/starts-with? (u/lower-case-en (:name %)) "foo") join-cols)join-clause (-> (lib/join-clause table-2)