List.InsertRange

Updated on
Rick de Groot

List.InsertRange is a Power Query M function that inserts a range of values into a list at a specified index. The function returns a new list with the values inserted at the given index.

Compatible with: Power BI Service Power BI Desktop Excel Microsoft 365

Syntax

List.InsertRange(
   list as list,
   index as number,
   values as list,
) as list
ArgumentAttributeDescription
ListThe list where you aim to insert new values.
IndexThe index position of the original list where values are insert into. This follows the zero-based indexing system, meaning the first position is referred to as 0.
ValuesA list of values you wish to insert into your main list.

Description

The List.InsertRange function is helpful when it comes to inserting values into lists. Executing the List.InsertRange function results in a new list. This list contains the values from the ‘Values’ argument inserted at the specified ‘Index’ within the original ‘List’.

Examples

Let’s see some examples of how to use the List.InsertRange function.

Consider you have the list {0, 1, 2} and you intend to introduce the numbers -1 and -2. To position them at the second position, provide an index of 1 due to the zero-based indexing system.

 // Output:  { 0, -1, -2, 1, 2 }
List.InsertRange( 
  { 0, 1, 2 }, 
  1, 
  { -1, -2 } 
)

This generates a newly-formed list with the values inserted at your chosen index.

A point to note: if you attempt to insert values at a location beyond the existing number of elements in your list, Power Query raises an error: 

 // Output:  { error }
List.InsertRange( 
  { 0, 1, 2 }, 
  5, 
  { -1, -2 } 
)

Learn more about List.InsertRange in the following articles:

Other functions related to List.InsertRange are:

Contribute » | Contributors: Rick de Groot
Microsoft documentation: https://learn.microsoft.com/en-us/powerquery-m/list-insertrange

2023-2024 © BI Gorilla. All rights are reserved. Information from Microsoft docs is property of Microsoft Corp. | Privacy Policy