Merge pull request #114589 from timsander1/master

add doc for working with JSON

Author: megvanhuygen

articles/cosmos-db/TOC.yml

@@ -166,15 +166,15 @@
         - name: OFFSET LIMIT
           displayName: offset limit
           href: sql-query-offset-limit.md
+      - name: Working with JSON
+        displayName: alias, JSON, projection
+        href: sql-query-working-with-json.md
       - name: Subquery
         displayName: subquery, exists
         href: sql-query-subquery.md
       - name: Joins
         displayName: join
         href: sql-query-join.md
-      - name: Aliasing
-        displayName: alias, aliasing
-        href: sql-query-aliasing.md
       - name: Arrays and objects
         displayName: object and array creation, object and array
         href: sql-query-object-array.md

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

@@ -4,17 +4,17 @@ description: Learn about the SQL syntax, and example for FROM clause for Azure C
 author: timsander1
 ms.service: cosmos-db
 ms.topic: conceptual
-ms.date: 12/02/2019
+ms.date: 05/08/2020
 ms.author: tisande
 
 ---
 # FROM clause in Azure Cosmos DB
 
 The FROM (`FROM <from_specification>`) clause is optional, unless the source is filtered or projected later in the query. A query like `SELECT * FROM Families` enumerates over the entire `Families` container. You can also use the special identifier ROOT for the container instead of using the container name.
 
-The FROM clause enforces the following rules per query:
+The `FROM` clause enforces the following rules per query:
 
-* The container can be aliased, such as `SELECT f.id FROM Families AS f` or simply `SELECT f.id FROM Families f`. Here `f` is the alias for `Families`. AS is an optional keyword to [alias](sql-query-aliasing.md) the identifier.  
+* The container can be aliased, such as `SELECT f.id FROM Families AS f` or simply `SELECT f.id FROM Families f`. Here `f` is the alias for `Families`. AS is an optional keyword to [alias](sql-query-working-with-json.md#aliasing) the identifier.  
 
 * Once aliased, the original source name cannot be bound. For example, `SELECT Families.id FROM Families f` is syntactically invalid because the identifier `Families` has been aliased and can't be resolved anymore.  
 
@@ -25,15 +25,15 @@ The FROM clause enforces the following rules per query:
 ```sql  
 FROM <from_specification>  
 
-<from_specification> ::=   
+<from_specification> ::=
         <from_source> {[ JOIN <from_source>][,...n]}  
 
-<from_source> ::=   
+<from_source> ::=
           <container_expression> [[AS] input_alias]  
         | input_alias IN <container_expression>  
 
-<container_expression> ::=   
-        ROOT   
+<container_expression> ::=
+        ROOT
      | container_name  
      | input_alias  
      | <container_expression> '.' property_name  
@@ -46,9 +46,9 @@ FROM <from_specification>
 
   Specifies a data source, with or without an alias. If alias is not specified, it will be inferred from the `<container_expression>` using following rules:  
 
-  -  If the expression is a container_name, then container_name will be used as an alias.  
+-  If the expression is a container_name, then container_name will be used as an alias.  
 
-  -  If the expression is `<container_expression>`, then property_name, then property_name will be used as an alias. If the expression is a container_name, then container_name will be used as an alias.  
+-  If the expression is `<container_expression>`, then property_name, then property_name will be used as an alias. If the expression is a container_name, then container_name will be used as an alias.  
 
 - AS `input_alias`  
 
@@ -94,9 +94,9 @@ If a container expression accesses properties or array elements and that value d
 
 A container expression may be container-scoped or document-scoped:  
 
--   An expression is container-scoped, if the underlying source of the container expression is either ROOT or `container_name`. Such an expression represents a set of documents retrieved from the container directly, and is not dependent on the processing of other container expressions.  
+- An expression is container-scoped, if the underlying source of the container expression is either ROOT or `container_name`. Such an expression represents a set of documents retrieved from the container directly, and is not dependent on the processing of other container expressions.  
 
--   An expression is document-scoped, if the underlying source of the container expression is `input_alias` introduced earlier in the query. Such an expression represents a set of documents obtained by evaluating the container expression in the scope of each document belonging to the set associated with the aliased container.  The resulting set will be a union of sets obtained by evaluating the container expression for each of the documents in the underlying set. 
+- An expression is document-scoped, if the underlying source of the container expression is `input_alias` introduced earlier in the query. Such an expression represents a set of documents obtained by evaluating the container expression in the scope of each document belonging to the set associated with the aliased container. The resulting set will be a union of sets obtained by evaluating the container expression for each of the documents in the underlying set.
 
 ## Examples
 
@@ -142,7 +142,7 @@ The results are:
     ]
 ```
 
-The preceding query used an array as the source, but you can also use an object as the source. The query considers any valid, defined JSON value in the source for inclusion in the result. The following example would exclude `Families` that don’t have an `address.state` value.
+The preceding query used an array as the source, but you can also use an object as the source. The query considers any valid, defined JSON value in the source for inclusion in the result. The following example would exclude `Families` that don't have an `address.state` value.
 
 ```sql
     SELECT *

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

@@ -1,30 +1,29 @@
 ---
 title: SELECT clause in Azure Cosmos DB
 description: Learn about SQL SELECT clause for Azure Cosmos DB. Use SQL as an Azure Cosmos DB JSON query language.
-author: ginarobinson
+author: timsander1
 ms.service: cosmos-db
 ms.topic: conceptual
-ms.date: 06/10/2019
-ms.author: girobins
+ms.date: 05/08/2020
+ms.author: tisande
 ---
 
 # SELECT clause in Azure Cosmos DB
 
-Every query consists of a SELECT clause and optional [FROM](sql-query-from.md) and [WHERE](sql-query-where.md) clauses, per ANSI SQL standards. Typically, the source in the FROM clause is enumerated, and the WHERE clause applies a filter on the source to retrieve a subset of JSON items. The SELECT clause then projects the requested JSON values in the select list.
+Every query consists of a `SELECT` clause and optional [FROM](sql-query-from.md) and [WHERE](sql-query-where.md) clauses, per ANSI SQL standards. Typically, the source in the `FROM` clause is enumerated, and the `WHERE` clause applies a filter on the source to retrieve a subset of JSON items. The `SELECT` clause then projects the requested JSON values in the select list.
 
 ## Syntax
 
 ```sql
 SELECT <select_specification>  
 
-<select_specification> ::=   
-      '*'   
-      | [DISTINCT] <object_property_list>   
+<select_specification> ::=
+      '*'
+      | [DISTINCT] <object_property_list>
       | [DISTINCT] VALUE <scalar_expression> [[ AS ] value_alias]  
 
-<object_property_list> ::=   
+<object_property_list> ::=
 { <scalar_expression> [ [ AS ] property_alias ] } [ ,...n ]  
-  
 ```  
 
 ## Arguments
@@ -44,7 +43,7 @@ SELECT <select_specification>
 - `VALUE`  
 
   Specifies that the JSON value should be retrieved instead of the complete JSON object. This, unlike `<property_list>` does not wrap the projected value in an object.  
- 
+
 - `DISTINCT`
 
   Specifies that duplicates of projected properties should be removed.  
@@ -93,122 +92,6 @@ The results are:
     }]
 ```
 
-### Quoted property accessor
-You can access properties using the quoted property operator []. For example, `SELECT c.grade` and `SELECT c["grade"]` are equivalent. This syntax is useful to escape a property that contains spaces, special characters, or has the same name as a SQL keyword or reserved word.
-
-```sql
-    SELECT f["lastName"]
-    FROM Families f
-    WHERE f["id"] = "AndersenFamily"
-```
-
-### Nested properties
-
-The following example projects two nested properties, `f.address.state` and `f.address.city`.
-
-```sql
-    SELECT f.address.state, f.address.city
-    FROM Families f
-    WHERE f.id = "AndersenFamily"
-```
-
-The results are:
-
-```json
-    [{
-      "state": "WA",
-      "city": "Seattle"
-    }]
-```
-### JSON expressions
-
-Projection also supports JSON expressions, as shown in the following example:
-
-```sql
-    SELECT { "state": f.address.state, "city": f.address.city, "name": f.id }
-    FROM Families f
-    WHERE f.id = "AndersenFamily"
-```
-
-The results are:
-
-```json
-    [{
-      "$1": {
-        "state": "WA",
-        "city": "Seattle",
-        "name": "AndersenFamily"
-      }
-    }]
-```
-
-In the preceding example, the SELECT clause needs to create a JSON object, and since the sample provides no key, the clause uses the implicit argument variable name `$1`. The following query returns two implicit argument variables: `$1` and `$2`.
-
-```sql
-    SELECT { "state": f.address.state, "city": f.address.city },
-           { "name": f.id }
-    FROM Families f
-    WHERE f.id = "AndersenFamily"
-```
-
-The results are:
-
-```json
-    [{
-      "$1": {
-        "state": "WA",
-        "city": "Seattle"
-      }, 
-      "$2": {
-        "name": "AndersenFamily"
-      }
-    }]
-```
-## Reserved keywords and special characters
-
-If your data contains properties with the same names as reserved keywords such as "order" or "Group" then the queries against these documents will result in syntax errors. You should explicitly include the property in `[]` character to run the query successfully.
-
-For example, here's a document with a property named `order` and a property `price($)` that contains special characters:
-
-```json
-{
-  "id": "AndersenFamily",
-  "order": [
-     {
-         "orderId": "12345",
-         "productId": "A17849",
-         "price($)": 59.33
-     }
-  ],
-  "creationDate": 1431620472,
-  "isRegistered": true
-}
-```
-
-If you run a queries that includes the `order` property or `price($)` property, you will receive a syntax error.
-
-```sql
-SELECT * FROM c where c.order.orderid = "12345"
-```
-```sql
-SELECT * FROM c where c.order.price($) > 50
-```
-The result is:
-
-`
-Syntax error, incorrect syntax near 'order'
-`
-
-You should rewrite the same queries as below:
-
-```sql
-SELECT * FROM c WHERE c["order"].orderId = "12345"
-```
-
-```sql
-SELECT * FROM c WHERE c["order"]["price($)"] > 50
-```
-
 ## Next steps
 
 - [Getting started](sql-query-getting-started.md)