Array functions for ARM templates

Resource Manager provides several functions for working with arrays in your Azure Resource Manager template (ARM template):

To get an array of string values delimited by a value, see split.

array

array(convertToArray)

Converts the value to an array.

Parameters

Parameter Required Type Description
convertToArray Yes int, string, array, or object The value to convert to an array.

Return value

An array.

Example

The following example shows how to use the array function with different types.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "intToConvert": {
      "type": "int",
      "defaultValue": 1
    },
    "stringToConvert": {
      "type": "string",
      "defaultValue": "efgh"
    },
    "objectToConvert": {
      "type": "object",
      "defaultValue": {
        "a": "b",
        "c": "d"
      }
    }
  },
  "resources": [
  ],
  "outputs": {
    "intOutput": {
      "type": "array",
      "value": "[array(parameters('intToConvert'))]"
    },
    "stringOutput": {
      "type": "array",
      "value": "[array(parameters('stringToConvert'))]"
    },
    "objectOutput": {
      "type": "array",
      "value": "[array(parameters('objectToConvert'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
intOutput Array [1]
stringOutput Array ["efgh"]
objectOutput Array [{"a": "b", "c": "d"}]

concat

concat(arg1, arg2, arg3, ...)

Combines multiple arrays and returns the concatenated array, or combines multiple string values and returns the concatenated string.

Parameters

Parameter Required Type Description
arg1 Yes array or string The first array or string for concatenation.
more arguments No array or string More arrays or strings in sequential order for concatenation.

This function can take any number of arguments, and can accept either strings or arrays for the parameters. However, you can't provide both arrays and strings for parameters. Arrays are only concatenated with other arrays.

Return value

A string or array of concatenated values.

Example

The following example shows how to combine two arrays.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "firstArray": {
      "type": "array",
      "defaultValue": [
        "1-1",
        "1-2",
        "1-3"
      ]
    },
    "secondArray": {
      "type": "array",
      "defaultValue": [
        "2-1",
        "2-2",
        "2-3"
      ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "return": {
      "type": "array",
      "value": "[concat(parameters('firstArray'), parameters('secondArray'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
return Array ["1-1", "1-2", "1-3", "2-1", "2-2", "2-3"]

The following example shows how to combine two string values and return a concatenated string.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "prefix": {
      "type": "string",
      "defaultValue": "prefix"
    }
  },
  "resources": [],
  "outputs": {
    "concatOutput": {
      "type": "string",
      "value": "[concat(parameters('prefix'), '-', uniqueString(resourceGroup().id))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
concatOutput String prefix-5yj4yjf5mbg72

contains

contains(container, itemToFind)

Checks whether an array contains a value, an object contains a key, or a string contains a substring. The string comparison is case-sensitive. However, when testing if an object contains a key, the comparison is case-insensitive.

Parameters

Parameter Required Type Description
container Yes array, object, or string The value that contains the value to find.
itemToFind Yes string or int The value to find.

Return value

True if the item is found; otherwise, False.

Example

The following example shows how to use contains with different types:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "stringToTest": {
      "type": "string",
      "defaultValue": "OneTwoThree"
    },
    "objectToTest": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "b",
        "three": "c"
      }
    },
    "arrayToTest": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "stringTrue": {
      "type": "bool",
      "value": "[contains(parameters('stringToTest'), 'e')]"
    },
    "stringFalse": {
      "type": "bool",
      "value": "[contains(parameters('stringToTest'), 'z')]"
    },
    "objectTrue": {
      "type": "bool",
      "value": "[contains(parameters('objectToTest'), 'one')]"
    },
    "objectFalse": {
      "type": "bool",
      "value": "[contains(parameters('objectToTest'), 'a')]"
    },
    "arrayTrue": {
      "type": "bool",
      "value": "[contains(parameters('arrayToTest'), 'three')]"
    },
    "arrayFalse": {
      "type": "bool",
      "value": "[contains(parameters('arrayToTest'), 'four')]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
stringTrue Bool True
stringFalse Bool False
objectTrue Bool True
objectFalse Bool False
arrayTrue Bool True
arrayFalse Bool False

createArray

createArray (arg1, arg2, arg3, ...)

Creates an array from the parameters.

Parameters

Parameter Required Type Description
args No String, Integer, Array, or Object The values in the array.

Return value

An array. When no parameters are provided, it returns an empty array.

Example

The following example shows how to use createArray with different types:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "objectToTest": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "b",
        "three": "c"
      }
    },
    "arrayToTest": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "stringArray": {
      "type": "array",
      "value": "[createArray('a', 'b', 'c')]"
    },
    "intArray": {
      "type": "array",
      "value": "[createArray(1, 2, 3)]"
    },
    "objectArray": {
      "type": "array",
      "value": "[createArray(parameters('objectToTest'))]"
    },
    "arrayArray": {
      "type": "array",
      "value": "[createArray(parameters('arrayToTest'))]"
    },
    "emptyArray": {
      "type": "array",
      "value": "[createArray()]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
stringArray Array ["a", "b", "c"]
intArray Array [1, 2, 3]
objectArray Array [{"one": "a", "two": "b", "three": "c"}]
arrayArray Array [["one", "two", "three"]]
emptyArray Array []

empty

empty(itemToTest)

Determines if an array, object, or string is empty.

Parameters

Parameter Required Type Description
itemToTest Yes array, object, or string The value to check if it's empty.

Return value

Returns True if the value is empty; otherwise, False.

Example

The following example checks whether an array, object, and string are empty.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "testArray": {
      "type": "array",
      "defaultValue": []
    },
    "testObject": {
      "type": "object",
      "defaultValue": {}
    },
    "testString": {
      "type": "string",
      "defaultValue": ""
    }
  },
  "resources": [
  ],
  "outputs": {
    "arrayEmpty": {
      "type": "bool",
      "value": "[empty(parameters('testArray'))]"
    },
    "objectEmpty": {
      "type": "bool",
      "value": "[empty(parameters('testObject'))]"
    },
    "stringEmpty": {
      "type": "bool",
      "value": "[empty(parameters('testString'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
arrayEmpty Bool True
objectEmpty Bool True
stringEmpty Bool True

first

first(arg1)

Returns the first element of the array, or first character of the string.

Parameters

Parameter Required Type Description
arg1 Yes array or string The value to retrieve the first element or character.

Return value

The type (string, int, array, or object) of the first element in an array, or the first character of a string.

Example

The following example shows how to use the first function with an array and string.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "arrayToTest": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "arrayOutput": {
      "type": "string",
      "value": "[first(parameters('arrayToTest'))]"
    },
    "stringOutput": {
      "type": "string",
      "value": "[first('One Two Three')]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
arrayOutput String one
stringOutput String O

intersection

intersection(arg1, arg2, arg3, ...)

Returns a single array or object with the common elements from the parameters.

Parameters

Parameter Required Type Description
arg1 Yes array or object The first value to use for finding common elements.
arg2 Yes array or object The second value to use for finding common elements.
more arguments No array or object More values to use for finding common elements.

Return value

An array or object with the common elements.

Example

The following example shows how to use intersection with arrays and objects.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "firstObject": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "b",
        "three": "c"
      }
    },
    "secondObject": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "z",
        "three": "c"
      }
    },
    "firstArray": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    },
    "secondArray": {
      "type": "array",
      "defaultValue": [ "two", "three" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "objectOutput": {
      "type": "object",
      "value": "[intersection(parameters('firstObject'), parameters('secondObject'))]"
    },
    "arrayOutput": {
      "type": "array",
      "value": "[intersection(parameters('firstArray'), parameters('secondArray'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
objectOutput Object {"one": "a", "three": "c"}
arrayOutput Array ["two", "three"]

last

last (arg1)

Returns the last element of the array, or last character of the string.

Parameters

Parameter Required Type Description
arg1 Yes array or string The value to retrieve the last element or character.

Return value

The type (string, int, array, or object) of the last element in an array, or the last character of a string.

Example

The following example shows how to use the last function with an array and string.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "arrayToTest": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "arrayOutput": {
      "type": "string",
      "value": "[last(parameters('arrayToTest'))]"
    },
    "stringOutput": {
      "type": "string",
      "value": "[last('One Two Three')]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
arrayOutput String three
stringOutput String e

length

length(arg1)

Returns the number of elements in an array, characters in a string, or root-level properties in an object.

Parameters

Parameter Required Type Description
arg1 Yes array, string, or object The array to use for getting the number of elements, the string to use for getting the number of characters, or the object to use for getting the number of root-level properties.

Return value

An int.

Example

The following example shows how to use length with an array and string.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "arrayToTest": {
      "type": "array",
      "defaultValue": [
        "one",
        "two",
        "three"
      ]
    },
    "stringToTest": {
      "type": "string",
      "defaultValue": "One Two Three"
    },
    "objectToTest": {
      "type": "object",
      "defaultValue": {
        "propA": "one",
        "propB": "two",
        "propC": "three",
        "propD": {
          "propD-1": "sub",
          "propD-2": "sub"
        }
      }
    }
  },
  "resources": [],
  "outputs": {
    "arrayLength": {
      "type": "int",
      "value": "[length(parameters('arrayToTest'))]"
    },
    "stringLength": {
      "type": "int",
      "value": "[length(parameters('stringToTest'))]"
    },
    "objectLength": {
      "type": "int",
      "value": "[length(parameters('objectToTest'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
arrayLength Int 3
stringLength Int 13
objectLength Int 4

You can use this function with an array to specify the number of iterations when creating resources. In the following example, the parameter siteNames would refer to an array of names to use when creating the web sites.

"copy": {
  "name": "websitescopy",
  "count": "[length(parameters('siteNames'))]"
}

For more information about using this function with an array, see Resource iteration in ARM templates.

max

max(arg1)

Returns the maximum value from an array of integers or a comma-separated list of integers.

Parameters

Parameter Required Type Description
arg1 Yes array of integers, or comma-separated list of integers The collection to get the maximum value.

Return value

An int representing the maximum value.

Example

The following example shows how to use max with an array and a list of integers.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "arrayToTest": {
      "type": "array",
      "defaultValue": [ 0, 3, 2, 5, 4 ]
    }
  },
  "resources": [],
  "outputs": {
    "arrayOutput": {
      "type": "int",
      "value": "[max(parameters('arrayToTest'))]"
    },
    "intOutput": {
      "type": "int",
      "value": "[max(0,3,2,5,4)]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
arrayOutput Int 5
intOutput Int 5

min

min(arg1)

Returns the minimum value from an array of integers or a comma-separated list of integers.

Parameters

Parameter Required Type Description
arg1 Yes array of integers, or comma-separated list of integers The collection to get the minimum value.

Return value

An int representing the minimum value.

Example

The following example shows how to use min with an array and a list of integers.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "arrayToTest": {
      "type": "array",
      "defaultValue": [ 0, 3, 2, 5, 4 ]
    }
  },
  "resources": [],
  "outputs": {
    "arrayOutput": {
      "type": "int",
      "value": "[min(parameters('arrayToTest'))]"
    },
    "intOutput": {
      "type": "int",
      "value": "[min(0,3,2,5,4)]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
arrayOutput Int 0
intOutput Int 0

range

range(startIndex, count)

Creates an array of integers from a starting integer and containing a number of items.

Parameters

Parameter Required Type Description
startIndex Yes int The first integer in the array. The sum of startIndex and count must be no greater than 2147483647.
count Yes int The number of integers in the array. Must be non-negative integer up to 10000.

Return value

An array of integers.

Example

The following example shows how to use the range function.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "startingInt": {
      "type": "int",
      "defaultValue": 5
    },
    "numberOfElements": {
      "type": "int",
      "defaultValue": 3
    }
  },
  "resources": [],
  "outputs": {
    "rangeOutput": {
      "type": "array",
      "value": "[range(parameters('startingInt'),parameters('numberOfElements'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
rangeOutput Array [5, 6, 7]

skip

skip(originalValue, numberToSkip)

Returns an array with all the elements after the specified number in the array, or returns a string with all the characters after the specified number in the string.

Parameters

Parameter Required Type Description
originalValue Yes array or string The array or string to use for skipping.
numberToSkip Yes int The number of elements or characters to skip. If this value is 0 or less, all the elements or characters in the value are returned. If it's larger than the length of the array or string, an empty array or string is returned.

Return value

An array or string.

Example

The following example skips the specified number of elements in the array, and the specified number of characters in a string.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "testArray": {
      "type": "array",
      "defaultValue": [
        "one",
        "two",
        "three"
      ]
    },
    "elementsToSkip": {
      "type": "int",
      "defaultValue": 2
    },
    "testString": {
      "type": "string",
      "defaultValue": "one two three"
    },
    "charactersToSkip": {
      "type": "int",
      "defaultValue": 4
    }
  },
  "resources": [],
  "outputs": {
    "arrayOutput": {
      "type": "array",
      "value": "[skip(parameters('testArray'),parameters('elementsToSkip'))]"
    },
    "stringOutput": {
      "type": "string",
      "value": "[skip(parameters('testString'),parameters('charactersToSkip'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
arrayOutput Array ["three"]
stringOutput String two three

take

take(originalValue, numberToTake)

Returns an array or string. An array has the specified number of elements from the start of the array. A string has the specified number of characters from the start of the string.

Parameters

Parameter Required Type Description
originalValue Yes array or string The array or string to take the elements from.
numberToTake Yes int The number of elements or characters to take. If this value is 0 or less, an empty array or string is returned. If it's larger than the length of the given array or string, all the elements in the array or string are returned.

Return value

An array or string.

Example

The following example takes the specified number of elements from the array, and characters from a string.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "testArray": {
      "type": "array",
      "defaultValue": [
        "one",
        "two",
        "three"
      ]
    },
    "elementsToTake": {
      "type": "int",
      "defaultValue": 2
    },
    "testString": {
      "type": "string",
      "defaultValue": "one two three"
    },
    "charactersToTake": {
      "type": "int",
      "defaultValue": 2
    }
  },
  "resources": [],
  "outputs": {
    "arrayOutput": {
      "type": "array",
      "value": "[take(parameters('testArray'),parameters('elementsToTake'))]"
    },
    "stringOutput": {
      "type": "string",
      "value": "[take(parameters('testString'),parameters('charactersToTake'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
arrayOutput Array ["one", "two"]
stringOutput String on

union

union(arg1, arg2, arg3, ...)

Returns a single array or object with all elements from the parameters. Duplicate values or keys are only included once.

Parameters

Parameter Required Type Description
arg1 Yes array or object The first value to use for joining elements.
arg2 Yes array or object The second value to use for joining elements.
more arguments No array or object More values to use for joining elements.

Return value

An array or object.

Example

The following example shows how to use union with arrays and objects.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "firstObject": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "b",
        "three": "c1"
      }
    },
    "secondObject": {
      "type": "object",
      "defaultValue": {
        "three": "c2",
        "four": "d",
        "five": "e"
      }
    },
    "firstArray": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    },
    "secondArray": {
      "type": "array",
      "defaultValue": [ "three", "four" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "objectOutput": {
      "type": "object",
      "value": "[union(parameters('firstObject'), parameters('secondObject'))]"
    },
    "arrayOutput": {
      "type": "array",
      "value": "[union(parameters('firstArray'), parameters('secondArray'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
objectOutput Object {"one": "a", "two": "b", "three": "c2", "four": "d", "five": "e"}
arrayOutput Array ["one", "two", "three", "four"]

Next steps