Table of contents
TOC
Collapse the table of content
Expand the table of content

List functions

Owen Duncan|Last Updated: 10/5/2018
|
1 Contributor

The Power Query Formula Language (informally known as "M") is a powerful mashup query language optimized for building queries that mashup data. It is a functional, case sensitive language similar to F#, which can be used with Power Query in Excel and Power BI Desktop . To learn more, see the Power Query Formula Language (informally known as "M").

Information

FunctionDescription
List.CountReturns the number of items in a list.
List.NonNullCountReturns the number of items in a list excluding null values
List.IsEmptyReturns whether a list is empty.

Selection

FunctionDescription
List.AlternateReturns a list with the items alternated from the original list based on a count, optional repeatInterval, and an optional offset.
List.BufferBuffers the list in memory. The result of this call is a stable list, which means it will have a determinimic count, and order of items.
List.DistinctFilters a list down by removing duplicates. An optional equation criteria value can be specified to control equality comparison. The first value from each equality group is chosen.
List.FindTextSearches a list of values, including record fields, for a text value.
List.FirstReturns the first value of the list or the specified default if empty. Returns the first item in the list, or the optional default value, if the list is empty. If the list is empty and a default value is not specified, the function returns.
List.FirstNReturns the first set of items in the list by specifying how many items to return or a qualifying condition provided by countOrCondition.
List.InsertRangeInserts items from values at the given index in the input list.
List.IsDistinctReturns whether a list is distinct.
List.LastReturns the last set of items in the list by specifying how many items to return or a qualifying condition provided by countOrCondition.
List.LastNReturns the last set of items in a list by specifying how many items to return or a qualifying condition.
List.MatchesAllReturns true if all items in a list meet a condition.
List.MatchesAnyReturns true if any item in a list meets a condition.
List.PositionsReturns a list of positions for an input list.
List.RangeReturns a count items starting at an offset.
List.SelectSelects the items that match a condition.
List.SingleReturns the single item of the list or throws an Expression.Error if the list has more than one item.
List.SingleOrDefaultReturns a single item from a list.
List.SkipSkips the first item of the list. Given an empty list, it returns an empty list. This function takes an optional parameter countOrCondition to support skipping multiple values.

Transformation functions

FunctionDescription
List.AccumulateAccumulates a result from the list. Starting from the initial value seed this function applies the accumulator function and returns the final result.
List.CombineMerges a list of lists into single list.
List.RemoveRangeReturns a list that removes count items starting at offset. The default count is 1.
List.RemoveFirstNReturns a list with the specified number of elements removed from the list starting at the first element. The number of elements removed depends on the optional countOrCondition parameter.
List.RemoveItemsRemoves items from list1 that are present in list2, and returns a new list.
List.RemoveLastNReturns a list with the specified number of elements removed from the list starting at the last element. The number of elements removed depends on the optional countOrCondition parameter.
List.RepeatReturns a list that repeats the contents of an input list count times.
List.ReplaceRangeReturns a list that replaces count values in a list with a replaceWith list starting at an index.
List.RemoveMatchingItemsRemoves all occurrences of the given values in the list.
List.RemoveNullsRemoves null values from a list.
List.ReplaceMatchingItemsReplaces occurrences of existing values in the list with new values using the provided equationCriteria. Old and new values are provided by the replacements parameters. An optional equation criteria value can be specified to control equality comparisons. For details of replacement operations and equation criteria, see Parameter Values.
List.ReplaceValueSearches a list of values for the value and replaces each occurrence with the replacement value.
List.ReverseReturns a list that reverses the items in a list.
List.SplitSplits the specified list into a list of lists using the specified page size.
List.TransformPerforms the function on each item in the list and returns the new list.
List.TransformManyReturns a list whose elements are projected from the input list.

Membership functions

Since all values can be tested for equality, these functions can operate over heterogeneous lists.

FunctionDescription
List.AllTrueReturns true if all expressions in a list are true
List.AnyTrueReturns true if any expression in a list in true
List.ContainsReturns true if a value is found in a list.
List.ContainsAllReturns true if all items in values are found in a list.
List.ContainsAnyReturns true if any item in values is found in a list.
List.PositionOfFinds the first occurrence of a value in a list and returns its position.
List.PositionOfAnyFinds the first occurrence of any value in values and returns its position.

Set operations

FunctionDescription
List.DifferenceReturns the items in list 1 that do not appear in list 2. Duplicate values are supported.
List.IntersectReturns a list from a list of lists and intersects common items in individual lists. Duplicate values are supported.
List.UnionReturns a list from a list of lists and unions the items in the individual lists. The returned list contains all items in any input lists. Duplicate values are matched as part of the Union.
List.ZipReturns a list of lists combining items at the same position.

Ordering

Ordering functions perform comparisons. All values that are compared must be comparable with each other. This means they must all come from the same datatype (or include null, which always compares smallest). Otherwise, an Expression.Error is thrown.

Comparable data types

  • Number

  • Duration

  • DateTime

  • Text

  • Logical

  • Null

FunctionDescription
List.MaxReturns the maximum item in a list, or the optional default value if the list is empty.
List.MaxNReturns the maximum values in the list. After the rows are sorted, optional parameters may be specified to further filter the result
List.MedianReturns the median item from a list.
List.MinReturns the minimum item in a list, or the optional default value if the list is empty.
List.MinNReturns the minimum values in a list.
List.SortReturns a sorted list using comparison criterion.

Averages

These functions operate over homogeneous lists of Numbers, DateTimes, and Durations.

FunctionDescription
List.AverageReturns an average value from a list in the datatype of the values in the list.
List.ModeReturns an item that appears most commonly in a list.
List.ModesReturns all items that appear with the same maximum frequency.
List.StandardDeviationReturns the standard deviation from a list of values. List.StandardDeviation performs a sample based estimate. The result is a number for numbers, and a duration for DateTimes and Durations.

Addition

These functions work over homogeneous lists of Numbers or Durations.

FunctionDescription
List.SumReturns the sum from a list.

Numerics

These functions only work over numbers.

FunctionDescription
List.CovarianceReturns the covariance from two lists as a number.
List.ProductReturns the product from a list of numbers.

Generators

These functions generate list of values.

FunctionDescription
List.DateTimesReturns a list of datetime values from size count, starting at start and adds an increment to every value.
List.DatesReturns a list of date values from size count, starting at start and adds an increment to every value.
List.DateTimeZonesReturns a list of of datetimezone values from size count, starting at start and adds an increment to every value.
List.DurationsReturns a list of durations values from size count, starting at start and adds an increment to every value.
List.GenerateGenerates a list from a value function, a condition function, a next function, and an optional transformation function on the values.
List.NumbersReturns a list of numbers from size count starting at initial, and adds an increment. The increment defaults to 1.
List.RandomReturns a list of count random numbers, with an optional seed parameter.
List.TimesReturns a list of time values of size count, starting at start.

Parameter values

Occurrence specification

  • Occurrence.First = 0;

  • Occurrence.Last = 1;

  • Occurrence.All = 2;

Sort order

  • Order.Ascending = 0;

  • Order.Descending = 1;

Equation criteria

Equation criteria for list values can be specified as either a

  • A function value that is either

    • A key selector that determines the value in the list to apply the equality criteria, or

    • A comparer function that is used to specify the kind of comparison to apply. Built in comparer functions can be specified, see section for Comparer functions.

  • A list value which has

    • Exactly two items

    • The first element is the key selector as specified above

    • The second element is a comparer as specified above.

For more information and examples, see List.Distinct.

Comparison criteria

Comparison criterion can be provided as either of the following values:

  • A number value to specify a sort order. For more inforarmtion, see sort order in Parameter values.

  • To compute a key to be used for sorting, a function of 1 argument can be used.

  • To both select a key and control order, comparison criterion can be a list containing the key and order.

  • To completely control the comparison, a function of 2 arguments can be used that returns -1, 0, or 1 given the relationship between the left and right inputs. Value.Compare is a method that can be used to delegate this logic.

For more information and examples, see List.Sort.

Replacement operations

Replacement operations are specified by a list value, each item of this list must be

  • A list value of exactly two items

  • Fist item is the old value in the list, to be replaced

  • Second item is the new which should replace all occurrences of the old value in the list

© 2018 Microsoft