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] User docs for aggregation functions (#70515)
Braden Shepherdson90042b1f0212
diff --git a/src/metabase/lib/aggregation.cljc b/src/metabase/lib/aggregation.cljcindex 86e97111711..d7c246998f1 100644--- a/src/metabase/lib/aggregation.cljc+++ b/src/metabase/lib/aggregation.cljc@@ -373,7 +373,7 @@(assoc :lib/source :source/aggregations:lib/source-uuid (lib.options/uuid aggregation))))))))))-(def ^:private OperatorWithColumns+(mr/def ::operator-with-columns[:merge::lib.schema.aggregation/operator[:map@@ -392,10 +392,10 @@(mu/defn aggregation-operator-columns :- [:maybe [:sequential ::lib.schema.metadata/column]]"Returns the columns for which `aggregation-operator` is applicable."- [aggregation-operator :- OperatorWithColumns]+ [aggregation-operator :- ::operator-with-columns](:columns aggregation-operator))-(mu/defn available-aggregation-operators :- [:maybe [:sequential OperatorWithColumns]]+(mu/defn available-aggregation-operators :- [:maybe [:sequential ::operator-with-columns]]"Returns the available aggregation operators for the stage with `stage-number` of `query`.If `stage-number` is omitted, uses the last stage."([query]@@ -442,16 +442,16 @@column](lib.options/ensure-uuid [(:short aggregation-operator) {} (lib.common/->op-arg column)])))-(def ^:private SelectedOperatorWithColumns+(mr/def ::selected-operator-with-columns[:merge::lib.schema.aggregation/operator[:map[:columns {:optional true} [:sequential ::lib.schema.metadata/column]][:selected? {:optional true} :boolean]]])-(mu/defn selected-aggregation-operators :- [:maybe [:sequential SelectedOperatorWithColumns]]+(mu/defn selected-aggregation-operators :- [:maybe [:sequential ::selected-operator-with-columns]]"Mark the operator and the column (if any) in `agg-operators` selected by `agg-clause`."- [agg-operators :- [:maybe [:sequential OperatorWithColumns]]+ [agg-operators :- [:maybe [:sequential ::operator-with-columns]]agg-clause](when (seq agg-operators)(let [[op _ agg-col] agg-clausediff --git a/src/metabase/lib/core.cljc b/src/metabase/lib/core.cljcindex d7cffc671bd..8dbc48ed635 100644--- a/src/metabase/lib/core.cljc+++ b/src/metabase/lib/core.cljc@@ -100,6 +100,7 @@[metabase.lib.ref :as lib.ref][metabase.lib.remove-replace :as lib.remove-replace][metabase.lib.schema :as lib.schema]+ [metabase.lib.schema.aggregation :as lib.schema.aggregation][metabase.lib.schema.common :as lib.schema.common][metabase.lib.schema.expression :as lib.schema.expression][metabase.lib.schema.id :as lib.schema.id]@@ -386,21 +387,146 @@integerfloat])-;;; # IGNORE ME!-;;; <img src="https://i.redd.it/1b9z1mv805e61.jpg" />-;;; *These are the leftovers which are not properly wrapped in user documentation yet.*+;;; ## Aggregations+;;; Aggregations are either "canned" aggregate functions like `Count`, `Sum` and `Max`, or a custom expression written+;;; by the user in the same expression editor as is used for expressions. The only columns in scope for custom+;;; aggregations are the breakouts and any aggregations to the left.+;;;+;;; Aggregations define new columns, which can be referenced by any custom aggregations to its right, in an Order By, or+;;; in later stages of the query.+;;;+;;; The canned aggregations come in four varieties:+;;;+;;; - No args: `count` and `distinct`+;;; - Single column: `sum`, `avg`, `max`, etc.+;;; - Single filter: `count-where` and `distinct-where`+;;; - Column and filter: `sum-where`+;;;+;;; ### Measures and Metrics+;;; Measures are effectively *saved aggregations*, defined outside of a query. They can be referenced as an aggregation+;;; on a query which has a source compatible with the measure's source.+;;;+;;; Semantically, referencing a measure is identical to pasting its definition into the query.+;;;+;;; The (deprecated?) Metrics v2 can be used similarly, though they allow several things that measures don't, such as+;;; embedding a filter.++(mu/defn aggregate :- ::lib.schema/query+ "Adds the given `aggregable` to the target stage of `a-query` as its rightmost aggregation.++ Valid `aggregable`s are:++ - Canned aggregation clauses like [[count]]+ - A `::lib.schema.common/external-op` AST from the custom aggregation editor+ - A measure+ - A (v2) metric++ **Code Health:** Healthy. This is a core API."+ ([a-query aggregable]+ (aggregate a-query -1 aggregable))+ ([a-query :- ::lib.schema/query+ stage-number :- :int+ aggregable :- ::lib.aggregation/aggregable]+ (lib.aggregation/aggregate a-query stage-number aggregable)))++(mu/defn aggregations :- [:maybe [:sequential ::lib.schema.aggregation/aggregation]]+ "Returns the list of aggregation definitions on the target stage of `a-query`, or nil if there are none."+ ([a-query] (aggregations a-query -1))+ ([a-query :- ::lib.schema/query+ stage-number :- :int]+ (lib.aggregation/aggregations a-query stage-number)))++(mu/defn aggregable-columns :- [:maybe [:sequential ::lib.schema.metadata/column]]+ "Returns the columns which are in scope for a custom aggregation expression.++ Takes `aggregation-position`, which is the index of the \"current\" aggregation while editing an existing aggregation,+ and nil when adding a new one.++ The columns in scope for an aggregation expression are:++ 1. Any breakouts on this stage+ 2. Any aggregations on this stage whose position is less than `aggregation-position`; all of them if it's nil.+ 3. Any pre-aggregation columns (from the source, joins, or expressions)+ - **But** these are only legal when wrapped in an aggregation like `sum([Some Column])`.++ To illustrate, a custom expression can do top-level arithmetic on other aggregations like++ Unit Price = [Sum of Subtotal] / [Sum of Quantity]++ or directly aggregate pre-aggregation columns like++ Unit Price = sum([Subtotal]) / sum([Quantity])++ **Code Health:** Single use. This mainly exists for the custom editor in the UI.+ Prefer [[available-aggregation-operators]] and [[aggregation-operator-columns]] for more \"structured\" usages."+ ([a-query aggregation-position]+ (aggregable-columns a-query -1 aggregation-position))+ ([a-query :- ::lib.schema/query+ stage-number :- :int+ aggregation-position :- [:maybe nat-int?]]+ (lib.aggregation/aggregable-columns a-query stage-number aggregation-position)))++(mu/defn aggregation-operator-columns :- [:maybe [:sequential ::lib.schema.metadata/column]]+ "Given an `aggregation-operator` map from [[available-aggregation-operators]], this returns the metadata of all+ available columns to which that operator can legally be applied.++ For aggregations which don't take an input column, like `:count`, this returns nil.++ **Code Health:** Healthy."+ [aggregation-operator :- ::lib.aggregation/operator-with-columns]+ (lib.aggregation/aggregation-operator-columns aggregation-operator))++(mu/defn available-aggregation-operators :- [:maybe [:sequential ::lib.aggregation/operator-with-columns]]+ "Returns a map for each aggregation operator (`:count`, `:sum`, etc.) which can plausibly be applied to the target+ stage of `a-query`. This takes into account the operators the database engine can support, and omits any operators+ that require an input column when no suitable inputs are available.++ **Code Health:** Healthy. This is the correct way to determine the valid set of aggregation operators."+ ([a-query] (available-aggregation-operators a-query -1))+ ([a-query :- ::lib.schema/query+ stage-number :- :int]+ (lib.aggregation/available-aggregation-operators a-query stage-number)))++(mu/defn remove-all-aggregations :- ::lib.schema/query+ "Removes all aggregations from the target stage of `a-query`.++ **Code Health:** Healthy, though it's an unusual thing to do."+ ([a-query] (remove-all-aggregations a-query -1))+ ([a-query :- ::lib.schema/query+ stage-number :- :int]+ (lib.aggregation/remove-all-aggregations a-query stage-number)))++(mu/defn selected-aggregation-operators :- [:maybe [:sequential ::lib.aggregation/selected-operator-with-columns]]+ "Given the aggregation operator maps from [[available-aggregation-operators]], and a particular `agg-clause`, mark+ both the operator map and the selected column (if applicable) with `:selected? true`.++ This is useful when editing an aggregation to indicate its current settings.++ **Code Health:** Healthy. Mostly exists to support the UI, but it would be legitimate to add new calls."+ [agg-operators :- [:maybe [:sequential ::lib.aggregation/operator-with-columns]]+ agg-clause :- ::lib.schema.aggregation/aggregation]+ (lib.aggregation/selected-aggregation-operators agg-operators agg-clause))++(mu/defn aggregation-ref :- :mbql.clause/aggregation+ "Given the index of an aggregation in the [[aggregations]] of the target stage, return an `:aggregation` reference+ for use **within that stage**.++ This is useful for adding an [[order-by]] clause, since [[aggregations]] returns aggregation *definitions*, but+ [[order-by]] needs aggregation references."+ ([a-query agg-index]+ (aggregation-ref a-query -1 agg-index))+ ([a-query :- ::lib.schema/query+ stage-number :- :int+ agg-index :- nat-int?]+ (lib.aggregation/aggregation-ref a-query stage-number agg-index)))++;;; These functions all directly construct an aggregation clause suitable for passing to [[aggregate]], taking+;;; input column and/or filter clauses as arguments, depending on the operator.+;;;+;;; **Code Health:** Healthy. Mainly used in tests, but any case where a known query is being constructed+;;; programatically is valid. UIs should generally be using [[available-aggregation-operators]] instead.(shared.ns/import-fns[lib.aggregation- aggregable-columns- aggregate- aggregation-clause- aggregation-ref- aggregation-operator-columns- aggregations- aggregations-metadata- available-aggregation-operators- remove-all-aggregations- selected-aggregation-operatorscountavgcount-where@@ -416,7 +542,19 @@sum-wherevarcum-count- cum-sum]+ cum-sum])++;;; **Code Health:** Leak. These helpers are only used in tests and should be avoided. To be unexported soon.+(shared.ns/import-fns+ [lib.aggregation+ aggregation-clause+ aggregations-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-strategiesbinning