update UDF guidance

Author: timsander1

articles/cosmos-db/sql-query-udfs.md

@@ -4,21 +4,31 @@ description: Learn about User-defined functions in Azure Cosmos DB.
 author: markjbrown
 ms.service: cosmos-db
 ms.topic: conceptual
-ms.date: 05/31/2019
+ms.date: 04/09/2020
 ms.author: mjbrown
-
 ---
 
 # User-defined functions (UDFs) in Azure Cosmos DB
 
 The SQL API provides support for user-defined functions (UDFs). With scalar UDFs, you can pass in zero or many arguments and return a single argument result. The API checks each argument for being legal JSON values.  
 
-The API extends the SQL syntax to support custom application logic using UDFs. You can register UDFs with the SQL API, and reference them in SQL queries. In fact, the UDFs are exquisitely designed to call from queries. As a corollary, UDFs do not have access to the context object like other JavaScript types, such as stored procedures and triggers. Queries are read-only, and can run either on primary or secondary replicas. UDFs, unlike other JavaScript types, are designed to run on secondary replicas.
+## UDF use cases
 
-The following example registers a UDF under an item container in the Cosmos database. The example creates a UDF whose name is `REGEX_MATCH`. It accepts two JSON string values, `input` and `pattern`, and checks if the first matches the pattern specified in the second using JavaScript's `string.match()` function.
+The API extends the SQL syntax to support custom application logic using UDFs. You can register UDFs with the SQL API, and reference them in SQL queries. Unlike stored procedures and triggers, UDFs are read-only.
+
+Using UDFs, you can extend Azure Cosmos DB's query language. UDFs are a great way to express complex business logic in a query's projection.
+
+However, we recommending avoiding UDFs when:
+
+- An equivalent [system function](sql-query-system-functions.md) already exists in Azure Cosmos DB. System functions will always use fewer RU's than the equivalent UDF.
+- The UDF is in the `WHERE` clause of your query. UDF's do not utilize the index so evaluating the UDF will require loading documents.
+
+If you must use the same UDF multiple times in a query, you should reference the UDF in a [subquery](sql-query-subquery.md#evaluate-once-and-reference-many-times), allowing you to use a JOIN expression to evaluate the UDF once but reference it many times.
 
 ## Examples
 
+The following example registers a UDF under an item container in the Cosmos database. The example creates a UDF whose name is `REGEX_MATCH`. It accepts two JSON string values, `input` and `pattern`, and checks if the first matches the pattern specified in the second using JavaScript's `string.match()` function.
+
 ```javascript
        UserDefinedFunction regexMatchUdf = new UserDefinedFunction
        {