Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

[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.cljc
index 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-me
lib.filter/keep-me
lib.join/keep-me
- metabase.lib.join.util/keep-me
+ lib.join.util/keep-me
lib.limit/keep-me
metabase.lib.metadata/keep-me
lib.metadata.calculation/keep-me
@@ -710,6 +712,388 @@
time-interval
segment]) ; 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-filter
update-numeric-filter
update-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.metric
available-metrics]
[lib.limit
diff --git a/src/metabase/lib/join.cljc b/src/metabase/lib/join.cljc
index 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/query
stage-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-providerable
a-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` so
we can filter out the columns added by it (it doesn't make sense to present the columns added by a join as options
for 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 new
join. (Things other than joins are ignored, but this argument is flexible for consistency with the signature
of [[join-condition-rhs-columns]].) See #32005 for more info.
@@ -857,7 +858,7 @@
([query :- ::lib.schema/query
stage-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/query
stage-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 the
stage in `query` at `stage-number`."
[query :- ::lib.schema/query
stage-number :- :int
source :- [: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, currently
selected columns (those in the join's `:fields`) will include `:selected true` information."
[query :- ::lib.schema/query
stage-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/query
stage-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.cljs
index 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.cljc
index 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/joins
diff --git a/test/metabase/query_processor/implicit_joins_test.clj b/test/metabase/query_processor/implicit_joins_test.clj
index 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)