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 breakouts functions (#71034)
Braden Shepherdson6b6ea19ab7b0
diff --git a/src/metabase/lib/core.cljc b/src/metabase/lib/core.cljcindex 8dbc48ed635..eac7738baa7 100644--- a/src/metabase/lib/core.cljc+++ b/src/metabase/lib/core.cljc@@ -105,6 +105,7 @@[metabase.lib.schema.expression :as lib.schema.expression][metabase.lib.schema.id :as lib.schema.id][metabase.lib.schema.metadata :as lib.schema.metadata]+ [metabase.lib.schema.ref :as lib.schema.ref][metabase.lib.schema.util][metabase.lib.segment :as lib.segment][metabase.lib.serialize]@@ -550,22 +551,96 @@aggregation-clauseaggregations-metadata])+;;; ## Breakouts+;;; Breakouts (equivalent to SQL `GROUP BY`) divide the rows into 1 or more subsets of rows, where each set has the+;;; same values for all the breakouts.+;;;+;;; Each breakout implicitly adds an Order By (ascending), in the same order as the breakouts. However, if the user+;;; explicitly adds an Order By for the breakout column(s), then the order and direction (asc/desc) is preserved.+;;;+;;; Breakouts must be unique within the stage. That means there can be at most 1 breakout per input column, with one+;;; exception: a temporal column can have multiple breakouts with different units.+;;;+;;; Finally, note that it's legal (though unusual) to create a query with breakouts but no aggregations. The results+;;; are equivalent to `SELECT DISTINCT breakouts... FROM ... ORDER BY breakouts...`, ie. sorting and de-duplicating+;;; by the breakouts.++(mu/defn breakout :- ::lib.schema/query+ "Add a breakout on the provided column to the target stage of `a-query`.++ Silently does nothing if the requested breakout already exists. Multiple breakouts of a temporal column are allowed+ provided they all set different `:temporal-unit`s.++ **Code Health:** Healthy. This is a core API."+ ([a-query expr] (breakout a-query -1 expr))+ ([a-query :- ::lib.schema/query+ stage-number :- :int+ expr :- some?]+ (lib.breakout/breakout a-query stage-number expr)))++(mu/defn breakouts :- [:maybe [:sequential ::lib.schema.expression/expression]]+ "Returns the list of breakouts on the target stage of `a-query`, or nil if there are none.++ **Code Health:** Healthy. This is a core API."+ ([a-query] (breakouts a-query -1))+ ([a-query :- ::lib.schema/query+ stage-number :- :int]+ (lib.breakout/breakouts a-query stage-number)))++(mu/defn breakout-column :- ::lib.schema.metadata/column+ "Given `a-query` and a breakout `clause` as returned by [[breakouts]], returns the column metadata for this+ breakout column.++ Strictly speaking a breakout column should be distinct from its input column; in practice their metadata is identical+ except that the breakout column has the `:temporal-unit` or `:binning` specified from the breakout clause.++ **Code Health:** Healthy."+ ([a-query breakout-clause] (breakout-column a-query -1 breakout-clause))+ ([a-query :- ::lib.schema/query+ stage-number :- :int+ breakout-clause :- ::lib.schema.ref/ref]+ (lib.breakout/breakout-column a-query stage-number breakout-clause)))++(mu/defn breakoutable-columns :- [:maybe [:sequential ::lib.schema.metadata/column]]+ "Returns column metadata for all the columns on the target stage of `a-query` which could be used for a breakout.++ The columns can be used for a breakout are, in this order:++ 1. Columns from the *source* - a table, card or previous stage.+ 2. *Expressions* in this stage of the query are allowed.+ 3. Columns from explicit joins on this stage.+ 4. All columns which are *implicitly joinable* via any FKs in the above.++ **Code Health:** Healthy. This is a core API."+ ([a-query :- ::lib.schema/query] (breakoutable-columns a-query -1))+ ([a-query :- ::lib.schema/query+ stage-number :- :int]+ (lib.breakout/breakoutable-columns a-query stage-number)))++(mu/defn remove-all-breakouts :- ::lib.schema/query+ "Removes all breakouts (if any) from the target stage of `a-query`.++ The removal is done properly per [[remove-clause]], so any references to the deleted breakouts will also be deleted.++ **Code Health:** Healthy."+ ([a-query] (remove-all-breakouts a-query -1))+ ([a-query :- ::lib.schema/query+ stage-number :- :int]+ (lib.breakout/remove-all-breakouts a-query stage-number)))++;;; **Code Health:** Leak. These functions are only used in friends and tests, and should be avoided. To be unexported.+(shared.ns/import-fns+ [lib.breakout+ breakouts-metadata])+;;; # IGNORE ME!;;; <img src="https://i.redd.it/1b9z1mv805e61.jpg" />;;; *These are the leftovers which are not properly wrapped in user documentation yet.*(shared.ns/import-fns-[lib.binningavailable-binning-strategiesbinningwith-binning]- [lib.breakout- breakout- breakout-column- breakoutable-columns- breakouts- breakouts-metadata- remove-all-breakouts][metabase.lib.cardcard->underlying-querymodel-preserved-keys]