List.FirstN
ListReturns the first N items from a list, or items from the start of the list while a condition is true.
Syntax
List.FirstN(list as list, countOrCondition as any) as anyParameters
| Name | Type | Required | Description |
|---|---|---|---|
list | list | Yes | The source list. |
countOrCondition | any | Yes | A number specifying how many items to return, or a function (condition) that returns true while items should be included. |
Return Value
any — A list of the first N items, or a list of items from the start while the condition holds true.
Remarks
List.FirstN is the flexible counterpart to List.First. While List.First returns a single scalar value, List.FirstN always returns a list. It accepts either a number or a condition function as its second argument.
When passed a number N, it returns a list of the first N items. If N exceeds the list length, the entire list is returned. If N is 0, an empty list is returned.
When passed a condition function, items are collected from the start of the list while the function returns true. Collection stops permanently at the first item that fails — remaining items are excluded even if they would have satisfied the condition. This makes the condition mode useful for collecting a leading run (e.g., values below a threshold, or dates before a cutoff), but not for general filtering. Use List.Select for non-contiguous filtering based on a predicate.
Examples
Example 2: Return items while value is less than 40
List.FirstN({10, 20, 30, 40, 50}, each _ < 40)Result | |
|---|---|
| 1 | {10, 20, 30} |
Example 3: Take top N sorted values
let
Prices = {75, 120, 25, 200, 50},
Sorted = List.Sort(Prices, Order.Descending),
TopThree = List.FirstN(Sorted, 3)
in
TopThreeThe final output — takes the first 3 items from the sorted descending list, yielding the 3 highest prices.
Result | |
|---|---|
| 1 | {200, 120, 75} |