From df47da1f8e469fdc5751e2d3c5fd7c58acb6f5be Mon Sep 17 00:00:00 2001 From: Martin Atkins Date: Tue, 17 Nov 2020 16:05:55 -0800 Subject: [PATCH] website: "coalesce" function unifies its argument types In order to be able to predict a result type even if arguments are not yet known, coalesce requires all of its arguments to be of the same type. Our usual automatic conversion rules mean that in some cases the result is a silent type conversion rather than an explicit error, so we'll at least document that so that folks who encounter it can understand what is causing the likely-surprising behavior. If we were building this function over again today I expect we'd make it always return an error under type mismatch, but to do so now would be a breaking change and the potential cost of that seems too high for something that doesn't seem to arise incredibly often in practice. --- .../configuration/functions/coalesce.html.md | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/website/docs/configuration/functions/coalesce.html.md b/website/docs/configuration/functions/coalesce.html.md index 13c970f726..d4b409d3c1 100644 --- a/website/docs/configuration/functions/coalesce.html.md +++ b/website/docs/configuration/functions/coalesce.html.md @@ -16,6 +16,11 @@ earlier, see `coalesce` takes any number of arguments and returns the first one that isn't null or an empty string. +All of the arguments must be of the same type. Terraform will try to +convert mismatched arguments to the most general of the types that all +arguments can convert to, or return an error if the types are incompatible. +The result type is the same as the type of all of the arguments. + ## Examples ``` @@ -35,6 +40,22 @@ symbol to expand the list as arguments: b ``` +Terraform attempts to select a result type that all of the arguments can +convert to, so mixing argument types may produce surprising results due to +Terraform's automatic type conversion rules: + +``` +> coalesce(1, "hello") +"1" +> coalesce(true, "hello") +"true" +> coalesce({}, "hello") + +Error: Error in function call + +Call to function "coalesce" failed: all arguments must have the same type. +``` + ## Related Functions * [`coalescelist`](./coalescelist.html) performs a similar operation with