List.Single
ListReturns the single element of a list. Throws an error if the list has zero elements or more than one element.
Syntax
List.Single(list as list) as anyParameters
| Name | Type | Required | Description |
|---|---|---|---|
list | list | Yes | The list expected to contain exactly one element. |
Return Value
any — The single item contained in the list.
Remarks
List.Single asserts that a list contains exactly one element and returns it as a scalar value. If the list is empty or contains more than one element, it throws an error. This makes it a strict validation tool — use it when having zero or multiple results indicates a data problem that should be surfaced immediately rather than silently ignored.
The typical use case is extracting a value from a lookup that is expected to match exactly one row. For example, after filtering a table by a unique key and extracting a column as a list, List.Single both validates the match count and returns the value in one step.
- An empty list throws: Expression.Error: There were too few elements in the enumeration.
- More than one element throws: Expression.Error: There were too many elements in the enumeration.
- Use List.SingleOrDefault if an empty list should return null (or a custom default) rather than an error.
- Use List.First if multiple results are acceptable and you only want the first.
Examples
Example 3: Lookup a single matching value
let
Prices = #table({"Product", "Price"}, {{"Widget", 9.99}, {"Gadget", 24.99}}),
WidgetPrice = List.Single(
Table.SelectRows(Prices, each [Product] = "Widget")[Price]
)
in
WidgetPriceThe final output — the scalar price of the Widget product.
Result | |
|---|---|
| 1 | 9.99 |