Merge pull request #116409 from timsander1/master

add string equals system function

Author: PMEds28

articles/cosmos-db/TOC.yml

@@ -373,6 +373,9 @@
             - name: STARTSWITH
               displayName: STARTSWITH, starts with, built-in functions
               href: sql-query-startswith.md
+            - name: STRINGEQUALS
+              displayName: STRINGEQUALS, equals, case-insensitive
+              href: sql-query-stringequals.md
             - name: StringToArray
               displayName: StringToArray, string to array, built-in functions
               href: sql-query-stringtoarray.md

articles/cosmos-db/index-overview.md

@@ -1,11 +1,11 @@
 ---
 title: Indexing in Azure Cosmos DB 
 description: Understand how indexing works in Azure Cosmos DB, different kinds of indexes such as Range, Spatial, composite indexes supported. 
-author: ThomasWeiss
+author: timsander1
 ms.service: cosmos-db
 ms.topic: conceptual
-ms.date: 04/13/2020
-ms.author: thweiss
+ms.date: 05/21/2020
+ms.author: tisande
 ---
 
 # Indexing in Azure Cosmos DB - Overview
@@ -100,7 +100,7 @@ Azure Cosmos DB currently supports three kinds of indexes.
    ```
 
    ```sql
-   SELECT * FROM c WHERE STARTSWITH(c.property, "value")
+   SELECT * FROM c WHERE STRINGEQUALS(c.property, "value")
    ```
 
 - `ORDER BY` queries:

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

@@ -1,5 +1,5 @@
 ---
-title: CONTAINS in Azure Cosmos DB query language
+title: Contains in Azure Cosmos DB query language
 description: Learn about how the CONTAINS SQL system function in Azure Cosmos DB returns a Boolean indicating whether the first string expression contains the second
 author: ginamr
 ms.service: cosmos-db
@@ -35,22 +35,42 @@ CONTAINS(<str_expr1>, <str_expr2> [, <bool_expr>])
 
 ## Examples
 
-  The following example checks if "abc" contains "ab" and if "abc" contains "d".  
+  The following example checks if "abc" contains "ab" and if "abc" contains "A".  
 
 ```sql
-SELECT CONTAINS("abc", "ab") AS c1, CONTAINS("abc", "d") AS c2
+SELECT CONTAINS("abc", "ab", false) AS c1, CONTAINS("abc", "A", false) AS c2, CONTAINS("abc", "A", true) AS c3
 ```  
 
  Here is the result set.  
 
 ```json
-[{"c1": true, "c2": false}]  
+[
+    {
+        "c1": true,
+        "c2": false,
+        "c3": true
+    }
+]
 ```  
 
 ## Remarks
 
 This system function will benefit from a [range index](index-policy.md#includeexclude-strategy).
 
+The RU consumption of Contains will increase as the cardinality of the property in the system function increases. In other words, if you are checking whether a property value contains a certain string, the query RU charge will depend on the number of possible values for that property.
+
+For example, consider two properties: town and country. The cardinality of town is 5,000 and the cardinality of country is 200. Here are two example queries:
+
+```sql
+    SELECT * FROM c WHERE CONTAINS(c.town, "Red", false)
+```
+
+```sql
+    SELECT * FROM c WHERE CONTAINS(c.country, "States", false)
+```
+
+The first query will likely use more RUs than the second query because the cardinality of town is higher than country.
+
 ## Next steps
 
 - [String functions Azure Cosmos DB](sql-query-string-functions.md)

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

@@ -1,5 +1,5 @@
 ---
-title: ENDSWITH in Azure Cosmos DB query language
+title: EndsWith in Azure Cosmos DB query language
 description: Learn about the ENDSWITH SQL system function in Azure Cosmos DB to return a Boolean indicating whether the first string expression ends with the second
 author: ginamr
 ms.service: cosmos-db
@@ -35,22 +35,42 @@ ENDSWITH(<str_expr1>, <str_expr2> [, <bool_expr>])
 
 ## Examples
 
-  The following example returns the "abc" ends with "b" and "bc".  
+The following example checks if the string "abc" ends with "b" and "bC".  
 
 ```sql
-SELECT ENDSWITH("abc", "b") AS e1, ENDSWITH("abc", "bc") AS e2 
+SELECT ENDSWITH("abc", "b", false) AS e1, ENDSWITH("abc", "bC", false) AS e2, ENDSWITH("abc", "bC", true) AS e3
 ```  
 
  Here is the result set.  
 
 ```json
-[{"e1": false, "e2": true}]  
+[
+    {
+        "e1": false,
+        "e2": false,
+        "e3": true
+    }
+]
 ```  
 
 ## Remarks
 
 This system function will benefit from a [range index](index-policy.md#includeexclude-strategy).
 
+The RU consumption of EndsWith will increase as the cardinality of the property in the system function increases. In other words, if you are checking whether a property value ends with a certain string, the query RU charge will depend on the number of possible values for that property.
+
+For example, consider two properties: town and country. The cardinality of town is 5,000 and the cardinality of country is 200. Here are two example queries:
+
+```sql
+    SELECT * FROM c WHERE ENDSWITH(c.town, "York", false)
+```
+
+```sql
+    SELECT * FROM c WHERE ENDSWITH(c.country, "States", false)
+```
+
+The first query will likely use more RUs than the second query because the cardinality of town is higher than country.
+
 ## Next steps
 
 - [String functions Azure Cosmos DB](sql-query-string-functions.md)

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

@@ -1,5 +1,5 @@
 ---
-title: STARTSWITH in Azure Cosmos DB query language
+title: StartsWith in Azure Cosmos DB query language
 description: Learn about SQL system function STARTSWITH in Azure Cosmos DB.
 author: ginamr
 ms.service: cosmos-db
@@ -35,16 +35,22 @@ STARTSWITH(<str_expr1>, <str_expr2> [, <bool_expr>])
 
 ## Examples
 
-  The following example checks if the string "abc" begins with "b" and "a".  
+The following example checks if the string "abc" begins with "b" and "A".  
 
 ```sql
-SELECT STARTSWITH("abc", "b") AS s1, STARTSWITH("abc", "a") AS s2  
+SELECT STARTSWITH("abc", "b", false) AS s1, STARTSWITH("abc", "A", false) AS s2, STARTSWITH("abc", "A", true) AS s3
 ```  
 
  Here is the result set.  
 
 ```json
-[{"s1": false, "s2": true}]  
+[
+    {
+        "s1": false,
+        "s2": false,
+        "s3": true
+    }
+]
 ```  
 
 ## Remarks

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

@@ -0,0 +1,64 @@
+---
+title: StringEquals in Azure Cosmos DB query language
+description: Learn about how the StringEquals SQL system function in Azure Cosmos DB returns a Boolean indicating whether the first string expression matches the second
+author: timsander1
+ms.service: cosmos-db
+ms.topic: conceptual
+ms.date: 05/20/2020
+ms.author: tisande
+ms.custom: query-reference
+---
+# STRINGEQUALS (Azure Cosmos DB)
+
+ Returns a Boolean indicating whether the first string expression matches the second.  
+  
+## Syntax
+  
+```sql
+STRINGEQUALS(<str_expr1>, <str_expr2> [, <bool_expr>])  
+```  
+  
+## Arguments
+  
+*str_expr1*  
+   Is the first string expression to compare.  
+  
+*str_expr2*  
+   Is the second string expression to compare.  
+
+*bool_expr*
+    Optional value for ignoring case. When set to true, StringEquals will do a case-insensitive search. When unspecified, this value is false.
+  
+## Return types
+  
+  Returns a Boolean expression.  
+  
+## Examples
+  
+  The following example checks if "abc" matches "abc" and if "abc" matches "ABC".  
+  
+```sql
+SELECT STRINGEQUALS("abc", "abc", false) AS c1, STRINGEQUALS("abc", "ABC", false) AS c2,  STRINGEQUALS("abc", "ABC", true) AS c3
+```  
+  
+ Here is the result set.  
+  
+```json
+[
+    {
+        "c1": true,
+        "c2": false,
+        "c3": true
+    }
+]
+```  
+
+## Remarks
+
+This system function will benefit from a [range index](index-policy.md#includeexclude-strategy).
+
+## Next steps
+
+- [String functions Azure Cosmos DB](sql-query-string-functions.md)
+- [System functions Azure Cosmos DB](sql-query-system-functions.md)
+- [Introduction to Azure Cosmos DB](introduction.md)