From 9532e7dc51c5b1d323f66c8a7c1c0e2876121c69 Mon Sep 17 00:00:00 2001
From: Morgan Tocker <tocker@gmail.com>
Date: Sun, 7 Oct 2018 18:09:22 +0000
Subject: [PATCH 01/18] [WIP] reorganized json functions

---
 README.md                                     |  2 +-
 ...nerated-column.md => generated-columns.md} |  6 +-
 sql/json-functions.md                         | 58 ++++++++++++++++++-
 3 files changed, 60 insertions(+), 6 deletions(-)
 rename sql/{json-functions-generated-column.md => generated-columns.md} (97%)

diff --git a/README.md b/README.md
index a94bd5fadf39b..8b9a98118540d 100644
--- a/README.md
+++ b/README.md
@@ -68,7 +68,7 @@
     - [Prepared SQL Statement Syntax](sql/prepare.md)
     - [Utility Statements](sql/util.md)
     - [TiDB SQL Syntax Diagram](https://pingcap.github.io/sqlgram/)
-  - [JSON Functions and Generated Column](sql/json-functions-generated-column.md)
+  - [Generated Columns](sql/generated-columns.md)
   - [Connectors and APIs](sql/connection-and-APIs.md)
   - [TiDB Transaction Isolation Levels](sql/transaction-isolation.md)
   - [Error Codes and Troubleshooting](sql/error.md)
diff --git a/sql/json-functions-generated-column.md b/sql/generated-columns.md
similarity index 97%
rename from sql/json-functions-generated-column.md
rename to sql/generated-columns.md
index 0fa72c7569789..ae82b614d1dc4 100644
--- a/sql/json-functions-generated-column.md
+++ b/sql/generated-columns.md
@@ -1,10 +1,10 @@
 ---
-title: JSON Functions and Generated Column
-summary: Learn how to use JSON functions and generated column to handle scenarios with uncertain schema.
+title: Generated Columns
+summary: Learn how to use generated columns
 category: user guide
 ---
 
-# JSON Functions and Generated Column
+# Generated Columns
 
 ## About
 
diff --git a/sql/json-functions.md b/sql/json-functions.md
index ee52706900a77..3d8d62feef62d 100644
--- a/sql/json-functions.md
+++ b/sql/json-functions.md
@@ -6,11 +6,65 @@ category: user guide
 
 # JSON Functions
 
+## Functions that create JSON values
+
+| Function Name and Syntactic Sugar | Description |
+| --------------------------------- | ----------- |
+| JSON_ARRAY | desc |
+| JSON_OBJECT | desc |
+
+## Functions that search JSON values
+
+| Function Name and Syntactic Sugar | Description |
+| --------------------------------- | ----------- |
+| JSON_CONTAINS | desc |
+| JSON_CONTAINS_PATH | desc |
+| JSON_EXTRACT | desc |
+| -> | desc |
+| ->> | desc |
+
+## Functions that modify JSON values
+
+| Function Name and Syntactic Sugar | Description |
+| --------------------------------- | ----------- |
+| JSON_INSERT | desc |
+| JSON_MERGE | desc |
+| JSON_REMOVE | desc |
+| JSON_REPLACE | desc |
+| JSON_SET | desc |
+| JSON_UNQUOTE | desc |
+
+## Functions that return JSON value attributes
+
+| Function Name and Syntactic Sugar | Description |
+| --------------------------------- | ----------- |
+| JSON_LENGTH | desc |
+| JSON_TYPE | desc |
+
+
+## Unsupported JSON Functions
+
+The following JSON functions are currently unsupported in TiDB.  You can track our progress in adding them in [TIDB #7546](https://github.com/pingcap/tidb/issues/7546):
+
+* `JSON_QUOTE`
+* `JSON_APPEND` and its alias `JSON_ARRAY_APPEND`
+* `JSON_ARRAY_INSERT`
+* `JSON_MERGE_PATCH`
+* `JSON_MERGE_PRESERVE`, use the alias `JSON_MERGE` instead
+* `JSON_VALID`
+* `JSON_PRETTY`
+* `JSON_SEARCH`
+* `JSON_STORAGE_SIZE`
+* `JSON_DEPTH`
+* `JSON_KEYS`
+* `JSON_ARRAYAGG`
+* `JSON_OBJECTAGG`
+
 | Function Name and Syntactic Sugar  | Description  |
 | ---------- | ------------------ |
 | [JSON_EXTRACT(json_doc, path[, path] ...)][json_extract]| Return data from a JSON document, selected from the parts of the document matched by the `path` arguments |
-| [JSON_UNQUOTE(json_val)][json_unquote] |  Unquote JSON value and return the result as a `utf8mb4` string |
-| [JSON_TYPE(json_val)][json_type] | Return a `utf8mb4` string indicating the type of a JSON value |
+| [JSON_UNQUOTE(json_val)][json_unquote] |  Unquote JSON value and return the result as a string |
+| [JSON_TYPE(json_val)][json_type] | Return a string indicating the type of a JSON value |
 | [JSON_SET(json_doc, path, val[, path, val] ...)][json_set]  | Insert or update data in a JSON document and return the result |
 | [JSON_INSERT(json_doc, path, val[, path, val] ...)][json_insert] | Insert data into a JSON document and return the result |
 | [JSON_REPLACE(json_doc, path, val[, path, val] ...)][json_replace] | Replace existing values in a JSON document and return the result |

From ac0b6b06f2f7f9268e3e5c8b82f7c6f482885451 Mon Sep 17 00:00:00 2001
From: Morgan Tocker <tocker@gmail.com>
Date: Sun, 7 Oct 2018 11:14:26 -0700
Subject: [PATCH 02/18] Update json-functions.md

---
 sql/json-functions.md | 40 ++++++++++++----------------------------
 1 file changed, 12 insertions(+), 28 deletions(-)

diff --git a/sql/json-functions.md b/sql/json-functions.md
index 3d8d62feef62d..c875e8913c8bc 100644
--- a/sql/json-functions.md
+++ b/sql/json-functions.md
@@ -10,8 +10,8 @@ category: user guide
 
 | Function Name and Syntactic Sugar | Description |
 | --------------------------------- | ----------- |
-| JSON_ARRAY | desc |
-| JSON_OBJECT | desc |
+| [JSON_ARRAY([val[, val] ...])][json_array]  | Evaluate a (possibly empty) list of values and return a JSON array containing those values |
+| [JSON_OBJECT(key, val[, key, val] ...)][json_object]   | Evaluate a (possibly empty) list of key-value pairs and return a JSON object containing those pairs  |
 
 ## Functions that search JSON values
 
@@ -19,28 +19,27 @@ category: user guide
 | --------------------------------- | ----------- |
 | JSON_CONTAINS | desc |
 | JSON_CONTAINS_PATH | desc |
-| JSON_EXTRACT | desc |
-| -> | desc |
-| ->> | desc |
+| [JSON_EXTRACT(json_doc, path[, path] ...)][json_extract]| Return data from a JSON document, selected from the parts of the document matched by the `path` arguments |
+| ->  | Return value from JSON column after evaluating path; the syntactic sugar of `JSON_EXTRACT(doc, path_literal)`   |
+| ->>  | Return value from JSON column after evaluating path and unquoting the result; the syntactic sugar of `JSON_UNQUOTE(JSONJSON_EXTRACT(doc, path_literal))` |
 
 ## Functions that modify JSON values
 
 | Function Name and Syntactic Sugar | Description |
 | --------------------------------- | ----------- |
-| JSON_INSERT | desc |
-| JSON_MERGE | desc |
-| JSON_REMOVE | desc |
-| JSON_REPLACE | desc |
-| JSON_SET | desc |
-| JSON_UNQUOTE | desc |
+| [JSON_INSERT(json_doc, path, val[, path, val] ...)][json_insert] | Insert data into a JSON document and return the result |
+| [JSON_MERGE(json_doc, json_doc[, json_doc] ...)][json_merge]  | Merge two or more JSON documents and return the merged result |
+| [JSON_REMOVE(json_doc, path[, path] ...)][json_remove]    | Remove data from a JSON document and return the result |
+| [JSON_REPLACE(json_doc, path, val[, path, val] ...)][json_replace] | Replace existing values in a JSON document and return the result |
+| [JSON_SET(json_doc, path, val[, path, val] ...)][json_set]  | Insert or update data in a JSON document and return the result |
+| [JSON_UNQUOTE(json_val)][json_unquote] |  Unquote JSON value and return the result as a string |
 
 ## Functions that return JSON value attributes
 
 | Function Name and Syntactic Sugar | Description |
 | --------------------------------- | ----------- |
 | JSON_LENGTH | desc |
-| JSON_TYPE | desc |
-
+| [JSON_TYPE(json_val)][json_type] | Return a string indicating the type of a JSON value |
 
 ## Unsupported JSON Functions
 
@@ -60,21 +59,6 @@ The following JSON functions are currently unsupported in TiDB.  You can track o
 * `JSON_ARRAYAGG`
 * `JSON_OBJECTAGG`
 
-| Function Name and Syntactic Sugar  | Description  |
-| ---------- | ------------------ |
-| [JSON_EXTRACT(json_doc, path[, path] ...)][json_extract]| Return data from a JSON document, selected from the parts of the document matched by the `path` arguments |
-| [JSON_UNQUOTE(json_val)][json_unquote] |  Unquote JSON value and return the result as a string |
-| [JSON_TYPE(json_val)][json_type] | Return a string indicating the type of a JSON value |
-| [JSON_SET(json_doc, path, val[, path, val] ...)][json_set]  | Insert or update data in a JSON document and return the result |
-| [JSON_INSERT(json_doc, path, val[, path, val] ...)][json_insert] | Insert data into a JSON document and return the result |
-| [JSON_REPLACE(json_doc, path, val[, path, val] ...)][json_replace] | Replace existing values in a JSON document and return the result |
-| [JSON_REMOVE(json_doc, path[, path] ...)][json_remove]    | Remove data from a JSON document and return the result |
-| [JSON_MERGE(json_doc, json_doc[, json_doc] ...)][json_merge]  | Merge two or more JSON documents and return the merged result |
-| [JSON_OBJECT(key, val[, key, val] ...)][json_object]   | Evaluate a (possibly empty) list of key-value pairs and return a JSON object containing those pairs  |
-| [JSON_ARRAY([val[, val] ...])][json_array]  | Evaluate a (possibly empty) list of values and return a JSON array containing those values |
-| ->  | Return value from JSON column after evaluating path; the syntactic sugar of `JSON_EXTRACT(doc, path_literal)`   |
-| ->>  | Return value from JSON column after evaluating path and unquoting the result; the syntactic sugar of `JSON_UNQUOTE(JSONJSON_EXTRACT(doc, path_literal))` |
-
 [json_extract]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-extract
 [json_unquote]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-unquote
 [json_type]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-type

From a33572a59e1a1cd3f6401af60720b0db6ad625fb Mon Sep 17 00:00:00 2001
From: Morgan Tocker <tocker@gmail.com>
Date: Sun, 7 Oct 2018 11:20:44 -0700
Subject: [PATCH 03/18] Update json-functions.md

---
 sql/json-functions.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/sql/json-functions.md b/sql/json-functions.md
index c875e8913c8bc..e3e33c2bc76e6 100644
--- a/sql/json-functions.md
+++ b/sql/json-functions.md
@@ -6,6 +6,8 @@ category: user guide
 
 # JSON Functions
 
+TiDB supports most of the JSON functions that shipped with the GA release of MySQL 5.7.  Additional JSON functions were added to MySQL 5.7 after its release, and not all are available in TiDB (see Unsupported JSON Functions).
+
 ## Functions that create JSON values
 
 | Function Name and Syntactic Sugar | Description |

From a1687b9540352c91dec4156e9212d3fd3ad3fb4b Mon Sep 17 00:00:00 2001
From: Morgan Tocker <tocker@gmail.com>
Date: Sun, 7 Oct 2018 11:25:54 -0700
Subject: [PATCH 04/18] Update generated-columns.md

---
 sql/generated-columns.md | 67 +---------------------------------------
 1 file changed, 1 insertion(+), 66 deletions(-)

diff --git a/sql/generated-columns.md b/sql/generated-columns.md
index ae82b614d1dc4..280b385bf6ada 100644
--- a/sql/generated-columns.md
+++ b/sql/generated-columns.md
@@ -8,72 +8,7 @@ category: user guide
 
 ## About
 
-To be compatible with MySQL 5.7 or later and better support the document store, TiDB supports JSON in the latest version. In TiDB, a document is a set of Key-Value pairs, encoded as a JSON object. You can use the JSON datatype in a TiDB table and create indexes for the JSON document fields using generated columns. In this way, you can flexibly deal with the business scenarios with uncertain schema and are no longer limited by the read performance and the lack of support for transactions in traditional document databases.
-
-## JSON functions
-
-The support for JSON in TiDB mainly refers to the user interface of MySQL 5.7. For example, you can create a table that includes a JSON field to store complex information:
-
-```sql
-CREATE TABLE person (
-    id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
-    name VARCHAR(255) NOT NULL,
-    address_info JSON
-);
-```
-
-When you insert data into a table, you can deal with those data with uncertain schema like this:
-
-```sql
-INSERT INTO person (name, address_info) VALUES ("John", '{"city": "Beijing"}');
-```
-
-You can insert JSON data into the table by inserting a legal JSON string into the column corresponding to the JSON field. TiDB will then parse the text and save it in a more compact and easy-to-access binary form.
-
-You can also convert other data type into JSON using CAST:
-
-```sql
-INSERT INTO person (name, address_info) VALUES ("John", CAST('{"city": "Beijing"}' AS JSON));
-INSERT INTO person (name, address_info) VALUES ("John", CAST('123' AS JSON));
-INSERT INTO person (name, address_info) VALUES ("John", CAST(123 AS JSON));
-```
-
-Now, if you want to query all the users living in Beijing from the table, you can simply use the following SQL statement:
-
-```sql
-SELECT id, name FROM person WHERE JSON_EXTRACT(address_info, '$.city') = 'Beijing';
-```
-
-TiDB supports the `JSON_EXTRACT` function which is exactly the same as in MySQL. The function is to extract the `city` field from the `address_info` document. The second argument is a "path expression" and is used to specify which field to extract. See the following few examples to help you understand the "path expression":
-
-```sql
-SET @person = '{"name":"John","friends":[{"name":"Forest","age":16},{"name":"Zhang San","gender":"male"}]}';
-
-SELECT JSON_EXTRACT(@person,  '$.name'); -- gets "John"
-SELECT JSON_EXTRACT(@person,  '$.friends[0].age'); -- gets 16
-SELECT JSON_EXTRACT(@person,  '$.friends[1].gender'); -- gets "male"
-SELECT JSON_EXTRACT(@person,  '$.friends[2].name'); -- gets NULL
-``` 
-
-In addition to inserting and querying data, TiDB also supports editing JSON. In general, TiDB currently supports the following JSON functions in MySQL 5.7:
-
-- [JSON_EXTRACT](https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-extract)
-- [JSON_ARRAY](https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-array)
-- [JSON_OBJECT](https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-object)
-- [JSON_SET](https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-set)
-- [JSON_REPLACE](https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-replace)
-- [JSON_INSERT](https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-insert)
-- [JSON_REMOVE](https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-remove)
-- [JSON_TYPE](https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-type)
-- [JSON_UNQUOTE](https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-unquote)
-- [JSON_MERGE](https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-merge)
-- [JSON_CONTAINS](https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains)
-- [JSON_CONTAINS_PATH](https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains-path)
-- [JSON_LENGTH](https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-length)
-
-You can get the general use of these functions directly from the function name. These functions in TiDB behave the same as in MySQL 5.7. For more information, see the [JSON Functions document of MySQL 5.7](https://dev.mysql.com/doc/refman/5.7/en/json-functions.html). If you are a user of MySQL 5.7, you can migrate to TiDB seamlessly.
-
-Currently TiDB does not support all the JSON functions in MySQL 5.7. You can track our progress in adding this functionality in [TiDB #7546](https://github.com/pingcap/tidb/issues/7546).
+TiDB supports generated columns as part of MySQL 5.7 compatibility.  One of the primary use cases for generated columns is to extract data out of a JSON data type and enable it to be indexed.
 
 ## Index JSON using generated column
 

From 727757800fe377a3ff525f69d09998057b2d16cd Mon Sep 17 00:00:00 2001
From: Morgan Tocker <tocker@gmail.com>
Date: Mon, 8 Oct 2018 15:55:58 +0000
Subject: [PATCH 05/18] WIP

---
 sql/json-functions.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/sql/json-functions.md b/sql/json-functions.md
index e3e33c2bc76e6..e1cecca32ec86 100644
--- a/sql/json-functions.md
+++ b/sql/json-functions.md
@@ -6,7 +6,7 @@ category: user guide
 
 # JSON Functions
 
-TiDB supports most of the JSON functions that shipped with the GA release of MySQL 5.7.  Additional JSON functions were added to MySQL 5.7 after its release, and not all are available in TiDB (see Unsupported JSON Functions).
+TiDB supports most of the JSON functions that shipped with the GA release of MySQL 5.7.  Additional JSON functions were added to MySQL 5.7 after its release, and not all are available in TiDB (see [unsupported functions](#Unsupported-functions)).
 
 ## Functions that create JSON values
 
@@ -14,16 +14,18 @@ TiDB supports most of the JSON functions that shipped with the GA release of MyS
 | --------------------------------- | ----------- |
 | [JSON_ARRAY([val[, val] ...])][json_array]  | Evaluate a (possibly empty) list of values and return a JSON array containing those values |
 | [JSON_OBJECT(key, val[, key, val] ...)][json_object]   | Evaluate a (possibly empty) list of key-value pairs and return a JSON object containing those pairs  |
+| [JSON_QUOTE][json_quote] | desc |
 
 ## Functions that search JSON values
 
 | Function Name and Syntactic Sugar | Description |
 | --------------------------------- | ----------- |
-| JSON_CONTAINS | desc |
-| JSON_CONTAINS_PATH | desc |
+| [JSON_CONTAINS][json_contains] | desc |
+| [JSON_CONTAINS_PATH][json_contains_path] | desc |
 | [JSON_EXTRACT(json_doc, path[, path] ...)][json_extract]| Return data from a JSON document, selected from the parts of the document matched by the `path` arguments |
 | ->  | Return value from JSON column after evaluating path; the syntactic sugar of `JSON_EXTRACT(doc, path_literal)`   |
 | ->>  | Return value from JSON column after evaluating path and unquoting the result; the syntactic sugar of `JSON_UNQUOTE(JSONJSON_EXTRACT(doc, path_literal))` |
+| [JSON_KEYS][json_keys] | desc |
 
 ## Functions that modify JSON values
 
@@ -40,24 +42,22 @@ TiDB supports most of the JSON functions that shipped with the GA release of MyS
 
 | Function Name and Syntactic Sugar | Description |
 | --------------------------------- | ----------- |
-| JSON_LENGTH | desc |
+| [JSON_LENGTH][json_length] | desc |
 | [JSON_TYPE(json_val)][json_type] | Return a string indicating the type of a JSON value |
+| [JSON_VALID][json_valid] | desc |
 
-## Unsupported JSON Functions
+## Unsupported functions
 
-The following JSON functions are currently unsupported in TiDB.  You can track our progress in adding them in [TIDB #7546](https://github.com/pingcap/tidb/issues/7546):
+The following JSON functions are unsupported in TiDB.  You can track our progress in adding them in [TIDB #7546](https://github.com/pingcap/tidb/issues/7546):
 
-* `JSON_QUOTE`
 * `JSON_APPEND` and its alias `JSON_ARRAY_APPEND`
 * `JSON_ARRAY_INSERT`
 * `JSON_MERGE_PATCH`
 * `JSON_MERGE_PRESERVE`, use the alias `JSON_MERGE` instead
-* `JSON_VALID`
 * `JSON_PRETTY`
 * `JSON_SEARCH`
 * `JSON_STORAGE_SIZE`
 * `JSON_DEPTH`
-* `JSON_KEYS`
 * `JSON_ARRAYAGG`
 * `JSON_OBJECTAGG`
 

From 3eeb1cb50842c6784a118f77157252920397e863 Mon Sep 17 00:00:00 2001
From: Morgan Tocker <tocker@gmail.com>
Date: Mon, 8 Oct 2018 09:06:53 -0700
Subject: [PATCH 06/18] Update json-functions.md

---
 sql/json-functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sql/json-functions.md b/sql/json-functions.md
index e1cecca32ec86..976784ed8394a 100644
--- a/sql/json-functions.md
+++ b/sql/json-functions.md
@@ -6,7 +6,7 @@ category: user guide
 
 # JSON Functions
 
-TiDB supports most of the JSON functions that shipped with the GA release of MySQL 5.7.  Additional JSON functions were added to MySQL 5.7 after its release, and not all are available in TiDB (see [unsupported functions](#Unsupported-functions)).
+TiDB supports most of the JSON functions that shipped with the GA release of MySQL 5.7.  Additional JSON functions were added to MySQL 5.7 after its release, and not all are available in TiDB (see [unsupported functions](#unsupported-functions)).
 
 ## Functions that create JSON values
 

From 4180f7642060d4ac9b7ce9a490568ad78906a2ac Mon Sep 17 00:00:00 2001
From: Morgan Tocker <tocker@gmail.com>
Date: Mon, 8 Oct 2018 09:14:14 -0700
Subject: [PATCH 07/18] Update json-functions.md

---
 sql/json-functions.md | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/sql/json-functions.md b/sql/json-functions.md
index 976784ed8394a..fb55947b490b6 100644
--- a/sql/json-functions.md
+++ b/sql/json-functions.md
@@ -23,8 +23,8 @@ TiDB supports most of the JSON functions that shipped with the GA release of MyS
 | [JSON_CONTAINS][json_contains] | desc |
 | [JSON_CONTAINS_PATH][json_contains_path] | desc |
 | [JSON_EXTRACT(json_doc, path[, path] ...)][json_extract]| Return data from a JSON document, selected from the parts of the document matched by the `path` arguments |
-| ->  | Return value from JSON column after evaluating path; the syntactic sugar of `JSON_EXTRACT(doc, path_literal)`   |
-| ->>  | Return value from JSON column after evaluating path and unquoting the result; the syntactic sugar of `JSON_UNQUOTE(JSONJSON_EXTRACT(doc, path_literal))` |
+| [->][json_short_extract]  | Return value from JSON column after evaluating path; the syntactic sugar of `JSON_EXTRACT(doc, path_literal)`   |
+| [->>][json_short_extract_unquote]  | Return value from JSON column after evaluating path and unquoting the result; the syntactic sugar of `JSON_UNQUOTE(JSONJSON_EXTRACT(doc, path_literal))` |
 | [JSON_KEYS][json_keys] | desc |
 
 ## Functions that modify JSON values
@@ -62,6 +62,8 @@ The following JSON functions are unsupported in TiDB.  You can track our progres
 * `JSON_OBJECTAGG`
 
 [json_extract]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-extract
+[json_short_extract]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#operator_json-column-path
+[json_short_extract_unquote]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#operator_json-inline-path
 [json_unquote]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-unquote
 [json_type]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-type
 [json_set]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-set
@@ -71,3 +73,6 @@ The following JSON functions are unsupported in TiDB.  You can track our progres
 [json_merge]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-merge
 [json_object]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-object
 [json_array]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-array
+[json_keys]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-keys
+[json_length]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-length
+[json_valid]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-valid

From 8663e6348dcf270fae4a3d164b1977e1cb98d6dd Mon Sep 17 00:00:00 2001
From: Morgan Tocker <tocker@gmail.com>
Date: Mon, 8 Oct 2018 09:15:51 -0700
Subject: [PATCH 08/18] Update json-functions.md

---
 sql/json-functions.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/sql/json-functions.md b/sql/json-functions.md
index fb55947b490b6..aac76d77aab48 100644
--- a/sql/json-functions.md
+++ b/sql/json-functions.md
@@ -76,3 +76,6 @@ The following JSON functions are unsupported in TiDB.  You can track our progres
 [json_keys]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-keys
 [json_length]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-length
 [json_valid]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-valid
+[json_quote]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-quote
+[json_contains]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains
+[json_contains_path]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains-path

From 7405c5914559776250aecb6cbffa29d9bee06658 Mon Sep 17 00:00:00 2001
From: Morgan Tocker <tocker@gmail.com>
Date: Mon, 8 Oct 2018 09:23:49 -0700
Subject: [PATCH 09/18] Update json-functions.md

---
 sql/json-functions.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/sql/json-functions.md b/sql/json-functions.md
index aac76d77aab48..8ff315ae1e02e 100644
--- a/sql/json-functions.md
+++ b/sql/json-functions.md
@@ -14,18 +14,18 @@ TiDB supports most of the JSON functions that shipped with the GA release of MyS
 | --------------------------------- | ----------- |
 | [JSON_ARRAY([val[, val] ...])][json_array]  | Evaluate a (possibly empty) list of values and return a JSON array containing those values |
 | [JSON_OBJECT(key, val[, key, val] ...)][json_object]   | Evaluate a (possibly empty) list of key-value pairs and return a JSON object containing those pairs  |
-| [JSON_QUOTE][json_quote] | desc |
+| [JSON_QUOTE(string)][json_quote] | Escapes a string for use in JSON, and returns it with enclosing quotes |
 
 ## Functions that search JSON values
 
 | Function Name and Syntactic Sugar | Description |
 | --------------------------------- | ----------- |
-| [JSON_CONTAINS][json_contains] | desc |
-| [JSON_CONTAINS_PATH][json_contains_path] | desc |
+| [JSON_CONTAINS(target, candidate[, path])][json_contains] | Indicates by returning 1 or 0 whether a given candidate JSON document is contained within a target JSON document |
+| [JSON_CONTAINS_PATH(json_doc, one_or_all, path[, path] ...)][json_contains_path] | Returns 0 or 1 to indicate whether a JSON document contains data at a given path or paths |
 | [JSON_EXTRACT(json_doc, path[, path] ...)][json_extract]| Return data from a JSON document, selected from the parts of the document matched by the `path` arguments |
 | [->][json_short_extract]  | Return value from JSON column after evaluating path; the syntactic sugar of `JSON_EXTRACT(doc, path_literal)`   |
 | [->>][json_short_extract_unquote]  | Return value from JSON column after evaluating path and unquoting the result; the syntactic sugar of `JSON_UNQUOTE(JSONJSON_EXTRACT(doc, path_literal))` |
-| [JSON_KEYS][json_keys] | desc |
+| [JSON_KEYS(json_doc[, path])][json_keys] | Returns the keys from the top-level value of a JSON object as a JSON array, or, if a path argument is given, the top-level keys from the selected path |
 
 ## Functions that modify JSON values
 
@@ -42,9 +42,9 @@ TiDB supports most of the JSON functions that shipped with the GA release of MyS
 
 | Function Name and Syntactic Sugar | Description |
 | --------------------------------- | ----------- |
-| [JSON_LENGTH][json_length] | desc |
+| [JSON_LENGTH(json_doc[, path])][json_length] | Returns the length of a JSON document, or, if a path argument is given, the length of the value within the path |
 | [JSON_TYPE(json_val)][json_type] | Return a string indicating the type of a JSON value |
-| [JSON_VALID][json_valid] | desc |
+| [JSON_VALID(val)][json_valid] | Returns 1 if a value is valid JSON, or 0 if it is not |
 
 ## Unsupported functions
 

From 37081a7c1e7956c6cb14061974dc1eec8104ff76 Mon Sep 17 00:00:00 2001
From: Morgan Tocker <tocker@gmail.com>
Date: Mon, 8 Oct 2018 09:25:59 -0700
Subject: [PATCH 10/18] Update json-functions.md

---
 sql/json-functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sql/json-functions.md b/sql/json-functions.md
index 8ff315ae1e02e..304e5d3a18f07 100644
--- a/sql/json-functions.md
+++ b/sql/json-functions.md
@@ -24,7 +24,7 @@ TiDB supports most of the JSON functions that shipped with the GA release of MyS
 | [JSON_CONTAINS_PATH(json_doc, one_or_all, path[, path] ...)][json_contains_path] | Returns 0 or 1 to indicate whether a JSON document contains data at a given path or paths |
 | [JSON_EXTRACT(json_doc, path[, path] ...)][json_extract]| Return data from a JSON document, selected from the parts of the document matched by the `path` arguments |
 | [->][json_short_extract]  | Return value from JSON column after evaluating path; the syntactic sugar of `JSON_EXTRACT(doc, path_literal)`   |
-| [->>][json_short_extract_unquote]  | Return value from JSON column after evaluating path and unquoting the result; the syntactic sugar of `JSON_UNQUOTE(JSONJSON_EXTRACT(doc, path_literal))` |
+| [->>][json_short_extract_unquote]  | Return value from JSON column after evaluating path and unquoting the result; the syntactic sugar of `JSON_UNQUOTE(JSON_EXTRACT(doc, path_literal))` |
 | [JSON_KEYS(json_doc[, path])][json_keys] | Returns the keys from the top-level value of a JSON object as a JSON array, or, if a path argument is given, the top-level keys from the selected path |
 
 ## Functions that modify JSON values

From 0cac986add5debe8c8ea441e9a5adfa8087517dd Mon Sep 17 00:00:00 2001
From: Morgan Tocker <tocker@gmail.com>
Date: Mon, 8 Oct 2018 09:30:51 -0700
Subject: [PATCH 11/18] Update json-functions.md

---
 sql/json-functions.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/sql/json-functions.md b/sql/json-functions.md
index 304e5d3a18f07..68333cd212ac3 100644
--- a/sql/json-functions.md
+++ b/sql/json-functions.md
@@ -46,6 +46,12 @@ TiDB supports most of the JSON functions that shipped with the GA release of MyS
 | [JSON_TYPE(json_val)][json_type] | Return a string indicating the type of a JSON value |
 | [JSON_VALID(val)][json_valid] | Returns 1 if a value is valid JSON, or 0 if it is not |
 
+## Aggregate functions
+
+| Function Name and Syntactic Sugar | Description |
+| --------------------------------- | ----------- |
+| [JSON_ARRAYAGG(col or expr)][json_arrayagg] | Aggregates a result set as a single JSON array whose elements consist of the rows |
+
 ## Unsupported functions
 
 The following JSON functions are unsupported in TiDB.  You can track our progress in adding them in [TIDB #7546](https://github.com/pingcap/tidb/issues/7546):
@@ -58,7 +64,6 @@ The following JSON functions are unsupported in TiDB.  You can track our progres
 * `JSON_SEARCH`
 * `JSON_STORAGE_SIZE`
 * `JSON_DEPTH`
-* `JSON_ARRAYAGG`
 * `JSON_OBJECTAGG`
 
 [json_extract]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-extract
@@ -79,3 +84,4 @@ The following JSON functions are unsupported in TiDB.  You can track our progres
 [json_quote]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-quote
 [json_contains]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains
 [json_contains_path]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains-path
+[json_arrayagg]: https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_json-arrayagg

From 1ecdff3aa3884e4926d09cfb4b071a04efaa27ba Mon Sep 17 00:00:00 2001
From: Morgan Tocker <tocker@gmail.com>
Date: Mon, 8 Oct 2018 09:55:05 -0700
Subject: [PATCH 12/18] Improved readability

---
 sql/generated-columns.md | 34 ++++++++++++++++++++++++----------
 1 file changed, 24 insertions(+), 10 deletions(-)

diff --git a/sql/generated-columns.md b/sql/generated-columns.md
index 280b385bf6ada..0e8faf7bfe356 100644
--- a/sql/generated-columns.md
+++ b/sql/generated-columns.md
@@ -8,13 +8,11 @@ category: user guide
 
 ## About
 
-TiDB supports generated columns as part of MySQL 5.7 compatibility.  One of the primary use cases for generated columns is to extract data out of a JSON data type and enable it to be indexed.
+TiDB supports generated columns as part of MySQL 5.7 compatibility. One of the primary use cases for generated columns is to extract data out of a JSON data type and enable it to be indexed.
 
 ## Index JSON using generated column
 
-The full table scan is executed when you query a JSON field. When you run the `EXPLAIN` statement in TiDB, the results show that it is full table scan. Then, can you index the JSON field?
-
-First, this type of index is wrong:
+In both MySQL 5.7 and TiDB, columns of type JSON can not be indexed directly. i.e. The following table structure is _not supported_:
 
 ```sql
 CREATE TABLE person (
@@ -25,7 +23,7 @@ CREATE TABLE person (
 );
 ```
 
-This is not because of technical impossibility but because the direct comparison of JSON itself is meaningless. Although we can agree on some comparison rules, such as `ARRAY` is bigger than all `OBJECT`, it is useless. Therefore, as what is done in MySQL 5.7, TiDB prohibits the direct creation of index on JSON field, but you can index the fields in the JSON document in the form of generated column:
+In order to index a JSON column, you must first extract it as a generated column. Using the `city` generated column as an example, we are then able to add an index:
 
 ```sql
 CREATE TABLE person (
@@ -37,15 +35,32 @@ CREATE TABLE person (
 );
 ```
 
-In this table, the `city` column is a **generated column**. As the name implies, the column is generated by other columns in the table, and cannot be assigned a value when inserted or updated. For generating a column, you can specify it as `VIRTUAL` to prevent it from being explicitly saved in the record, but by other columns when needed. This is particularly useful when the column is wide and you need to save storage space. With this generated column, you can create an index on it, and it looks the same with other regular columns. In query, you can run the following statements:  
+In this table, the `city` column is a **generated column**. As the name implies, the column is generated from other columns in the table, and cannot be assigned a value when inserted or updated. The column is also _virtual_ in that it does not require any storage or memory, and is generated on demand. The index on `city` however is _stored_ and uses the same structure as other indexes of the type `varchar(64)`.
+
+You can use the index on the generated column in order to speed up the following statement:
 
 ```sql
 SELECT name, id FROM person WHERE city = 'Beijing';
 ```
 
-In this way, you can create an index. 
+If no data exists at path `$.city`, `JSON_EXTRACT` will return `NULL`. The definition of the city virtual column permits `NULL` values. If you want to enforce a constraint that `city` must be `NOT NULL`, you can define the virtual column as follows:
 
-> **Note**: In the JSON document, if the field in the specified path does not exist, the result of `JSON_EXTRACT` will be `NULL`. The value of the generated column with index is also `NULL`. If this is not what you want to see, you can add a `NOT NULL` constraint on the generated column. In this way, when the value of the `city` field is `NULL` after you insert data, it can be detected.
+```sql
+CREATE TABLE person (
+    id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
+    name VARCHAR(255) NOT NULL,
+    address_info JSON,
+    city VARCHAR(64) AS (JSON_UNQUOTE(JSON_EXTRACT(address_info, '$.city'))) VIRTUAL NOT NULL,
+    KEY (city)
+);
+```
+
+Both `INSERT` and `UPDATE` statements check virtual column definitions. Rows that do not pass validation will return errors:
+
+```sql
+MySQL [test]> INSERT INTO person (name, address_info) VALUES ('Morgan', JSON_OBJECT('Country', 'Canada'));
+ERROR 1048 (23000): Column 'city' cannot be null
+```
 
 ## Limitations
 
@@ -53,5 +68,4 @@ The current limitations of JSON and generated column are as follows:
 
 - You cannot add the generated column in the storage type of `STORED` through `ALTER TABLE`.
 - You cannot create an index on the generated column through `ALTER TABLE`. 
-
-The above functions and some other JSON functions are under development.
+- Not all [JSON functions](json-functions.md) are supported.

From 92613135d2cf2282442ade2200c56f50500b9315 Mon Sep 17 00:00:00 2001
From: Morgan Tocker <tocker@gmail.com>
Date: Mon, 8 Oct 2018 09:55:32 -0700
Subject: [PATCH 13/18] Update generated-columns.md

---
 sql/generated-columns.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sql/generated-columns.md b/sql/generated-columns.md
index 0e8faf7bfe356..f3bd179dc7801 100644
--- a/sql/generated-columns.md
+++ b/sql/generated-columns.md
@@ -58,7 +58,7 @@ CREATE TABLE person (
 Both `INSERT` and `UPDATE` statements check virtual column definitions. Rows that do not pass validation will return errors:
 
 ```sql
-MySQL [test]> INSERT INTO person (name, address_info) VALUES ('Morgan', JSON_OBJECT('Country', 'Canada'));
+mysql> INSERT INTO person (name, address_info) VALUES ('Morgan', JSON_OBJECT('Country', 'Canada'));
 ERROR 1048 (23000): Column 'city' cannot be null
 ```
 

From 745836f2e2e57d068d00e2f1000e3a20bfc7a461 Mon Sep 17 00:00:00 2001
From: Morgan Tocker <tocker@gmail.com>
Date: Mon, 8 Oct 2018 09:56:30 -0700
Subject: [PATCH 14/18] Update generated-columns.md

---
 sql/generated-columns.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sql/generated-columns.md b/sql/generated-columns.md
index f3bd179dc7801..e8dfc2a5834f3 100644
--- a/sql/generated-columns.md
+++ b/sql/generated-columns.md
@@ -43,7 +43,7 @@ You can use the index on the generated column in order to speed up the following
 SELECT name, id FROM person WHERE city = 'Beijing';
 ```
 
-If no data exists at path `$.city`, `JSON_EXTRACT` will return `NULL`. The definition of the city virtual column permits `NULL` values. If you want to enforce a constraint that `city` must be `NOT NULL`, you can define the virtual column as follows:
+If no data exists at path `$.city`, `JSON_EXTRACT` will return `NULL`. If you want to enforce a constraint that `city` must be `NOT NULL`, you can define the virtual column as follows:
 
 ```sql
 CREATE TABLE person (

From bc51473277dd1ee077e6cd430f9f1eb83ce39dc4 Mon Sep 17 00:00:00 2001
From: Morgan Tocker <tocker@gmail.com>
Date: Mon, 8 Oct 2018 09:57:26 -0700
Subject: [PATCH 15/18] Update generated-columns.md

---
 sql/generated-columns.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sql/generated-columns.md b/sql/generated-columns.md
index e8dfc2a5834f3..c2c6bb0129ee0 100644
--- a/sql/generated-columns.md
+++ b/sql/generated-columns.md
@@ -12,7 +12,7 @@ TiDB supports generated columns as part of MySQL 5.7 compatibility. One of the p
 
 ## Index JSON using generated column
 
-In both MySQL 5.7 and TiDB, columns of type JSON can not be indexed directly. i.e. The following table structure is _not supported_:
+In both MySQL 5.7 and TiDB, columns of type JSON can not be indexed directly. i.e. The following table structure is **not supported**:
 
 ```sql
 CREATE TABLE person (

From 77d83bf6efd14c959d5c7e2cd0c4f585a78a54b3 Mon Sep 17 00:00:00 2001
From: Morgan Tocker <tocker@gmail.com>
Date: Sun, 14 Oct 2018 12:28:38 -0400
Subject: [PATCH 16/18] Moved unmerged functions to unsupported

---
 sql/json-functions.md | 15 +++++----------
 1 file changed, 5 insertions(+), 10 deletions(-)

diff --git a/sql/json-functions.md b/sql/json-functions.md
index 68333cd212ac3..cfbfcabac255e 100644
--- a/sql/json-functions.md
+++ b/sql/json-functions.md
@@ -14,7 +14,6 @@ TiDB supports most of the JSON functions that shipped with the GA release of MyS
 | --------------------------------- | ----------- |
 | [JSON_ARRAY([val[, val] ...])][json_array]  | Evaluate a (possibly empty) list of values and return a JSON array containing those values |
 | [JSON_OBJECT(key, val[, key, val] ...)][json_object]   | Evaluate a (possibly empty) list of key-value pairs and return a JSON object containing those pairs  |
-| [JSON_QUOTE(string)][json_quote] | Escapes a string for use in JSON, and returns it with enclosing quotes |
 
 ## Functions that search JSON values
 
@@ -25,7 +24,6 @@ TiDB supports most of the JSON functions that shipped with the GA release of MyS
 | [JSON_EXTRACT(json_doc, path[, path] ...)][json_extract]| Return data from a JSON document, selected from the parts of the document matched by the `path` arguments |
 | [->][json_short_extract]  | Return value from JSON column after evaluating path; the syntactic sugar of `JSON_EXTRACT(doc, path_literal)`   |
 | [->>][json_short_extract_unquote]  | Return value from JSON column after evaluating path and unquoting the result; the syntactic sugar of `JSON_UNQUOTE(JSON_EXTRACT(doc, path_literal))` |
-| [JSON_KEYS(json_doc[, path])][json_keys] | Returns the keys from the top-level value of a JSON object as a JSON array, or, if a path argument is given, the top-level keys from the selected path |
 
 ## Functions that modify JSON values
 
@@ -44,13 +42,6 @@ TiDB supports most of the JSON functions that shipped with the GA release of MyS
 | --------------------------------- | ----------- |
 | [JSON_LENGTH(json_doc[, path])][json_length] | Returns the length of a JSON document, or, if a path argument is given, the length of the value within the path |
 | [JSON_TYPE(json_val)][json_type] | Return a string indicating the type of a JSON value |
-| [JSON_VALID(val)][json_valid] | Returns 1 if a value is valid JSON, or 0 if it is not |
-
-## Aggregate functions
-
-| Function Name and Syntactic Sugar | Description |
-| --------------------------------- | ----------- |
-| [JSON_ARRAYAGG(col or expr)][json_arrayagg] | Aggregates a result set as a single JSON array whose elements consist of the rows |
 
 ## Unsupported functions
 
@@ -58,12 +49,16 @@ The following JSON functions are unsupported in TiDB.  You can track our progres
 
 * `JSON_APPEND` and its alias `JSON_ARRAY_APPEND`
 * `JSON_ARRAY_INSERT`
+* `JSON_DEPTH`
+* `JSON_KEYS`
 * `JSON_MERGE_PATCH`
 * `JSON_MERGE_PRESERVE`, use the alias `JSON_MERGE` instead
 * `JSON_PRETTY`
+* `JSON_QUOTE`
 * `JSON_SEARCH`
 * `JSON_STORAGE_SIZE`
-* `JSON_DEPTH`
+* `JSON_VALID`
+* `JSON_ARRAYAGG`
 * `JSON_OBJECTAGG`
 
 [json_extract]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-extract

From feac987d1f442cc76a02afb841ba25ec8193d89e Mon Sep 17 00:00:00 2001
From: Morgan Tocker <tocker@gmail.com>
Date: Mon, 15 Oct 2018 08:44:50 -0400
Subject: [PATCH 17/18] Update generated-columns.md

---
 sql/generated-columns.md | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/sql/generated-columns.md b/sql/generated-columns.md
index c2c6bb0129ee0..3d30525e93637 100644
--- a/sql/generated-columns.md
+++ b/sql/generated-columns.md
@@ -6,8 +6,6 @@ category: user guide
 
 # Generated Columns
 
-## About
-
 TiDB supports generated columns as part of MySQL 5.7 compatibility. One of the primary use cases for generated columns is to extract data out of a JSON data type and enable it to be indexed.
 
 ## Index JSON using generated column
@@ -23,7 +21,7 @@ CREATE TABLE person (
 );
 ```
 
-In order to index a JSON column, you must first extract it as a generated column. Using the `city` generated column as an example, we are then able to add an index:
+In order to index a JSON column, you must first extract it as a generated column. Using the `city` generated column as an example, you are then able to add an index:
 
 ```sql
 CREATE TABLE person (
@@ -43,7 +41,7 @@ You can use the index on the generated column in order to speed up the following
 SELECT name, id FROM person WHERE city = 'Beijing';
 ```
 
-If no data exists at path `$.city`, `JSON_EXTRACT` will return `NULL`. If you want to enforce a constraint that `city` must be `NOT NULL`, you can define the virtual column as follows:
+If no data exists at path `$.city`, `JSON_EXTRACT` returns `NULL`. If you want to enforce a constraint that `city` must be `NOT NULL`, you can define the virtual column as follows:
 
 ```sql
 CREATE TABLE person (
@@ -55,7 +53,7 @@ CREATE TABLE person (
 );
 ```
 
-Both `INSERT` and `UPDATE` statements check virtual column definitions. Rows that do not pass validation will return errors:
+Both `INSERT` and `UPDATE` statements check virtual column definitions. Rows that do not pass validation return errors:
 
 ```sql
 mysql> INSERT INTO person (name, address_info) VALUES ('Morgan', JSON_OBJECT('Country', 'Canada'));
@@ -64,7 +62,7 @@ ERROR 1048 (23000): Column 'city' cannot be null
 
 ## Limitations
 
-The current limitations of JSON and generated column are as follows:
+The current limitations of JSON and generated columns are as follows:
 
 - You cannot add the generated column in the storage type of `STORED` through `ALTER TABLE`.
 - You cannot create an index on the generated column through `ALTER TABLE`. 

From 9476bbea0e88810a8d8df852fb3b24ee5a55d693 Mon Sep 17 00:00:00 2001
From: Morgan Tocker <tocker@gmail.com>
Date: Mon, 15 Oct 2018 08:51:35 -0400
Subject: [PATCH 18/18] addressed pr feedback

---
 sql/json-functions.md | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/sql/json-functions.md b/sql/json-functions.md
index cfbfcabac255e..b9ae307a4bab6 100644
--- a/sql/json-functions.md
+++ b/sql/json-functions.md
@@ -6,14 +6,14 @@ category: user guide
 
 # JSON Functions
 
-TiDB supports most of the JSON functions that shipped with the GA release of MySQL 5.7.  Additional JSON functions were added to MySQL 5.7 after its release, and not all are available in TiDB (see [unsupported functions](#unsupported-functions)).
+TiDB supports most of the JSON functions that shipped with the GA release of MySQL 5.7. Additional JSON functions were added to MySQL 5.7 after its release, and not all are available in TiDB (see [unsupported functions](#unsupported-functions)).
 
 ## Functions that create JSON values
 
 | Function Name and Syntactic Sugar | Description |
 | --------------------------------- | ----------- |
-| [JSON_ARRAY([val[, val] ...])][json_array]  | Evaluate a (possibly empty) list of values and return a JSON array containing those values |
-| [JSON_OBJECT(key, val[, key, val] ...)][json_object]   | Evaluate a (possibly empty) list of key-value pairs and return a JSON object containing those pairs  |
+| [JSON_ARRAY([val[, val] ...])][json_array]  | Evaluates a (possibly empty) list of values and returns a JSON array containing those values |
+| [JSON_OBJECT(key, val[, key, val] ...)][json_object]   | Evaluates a (possibly empty) list of key-value pairs and returns a JSON object containing those pairs  |
 
 ## Functions that search JSON values
 
@@ -21,31 +21,31 @@ TiDB supports most of the JSON functions that shipped with the GA release of MyS
 | --------------------------------- | ----------- |
 | [JSON_CONTAINS(target, candidate[, path])][json_contains] | Indicates by returning 1 or 0 whether a given candidate JSON document is contained within a target JSON document |
 | [JSON_CONTAINS_PATH(json_doc, one_or_all, path[, path] ...)][json_contains_path] | Returns 0 or 1 to indicate whether a JSON document contains data at a given path or paths |
-| [JSON_EXTRACT(json_doc, path[, path] ...)][json_extract]| Return data from a JSON document, selected from the parts of the document matched by the `path` arguments |
-| [->][json_short_extract]  | Return value from JSON column after evaluating path; the syntactic sugar of `JSON_EXTRACT(doc, path_literal)`   |
-| [->>][json_short_extract_unquote]  | Return value from JSON column after evaluating path and unquoting the result; the syntactic sugar of `JSON_UNQUOTE(JSON_EXTRACT(doc, path_literal))` |
+| [JSON_EXTRACT(json_doc, path[, path] ...)][json_extract]| Returns data from a JSON document, selected from the parts of the document matched by the `path` arguments |
+| [->][json_short_extract]  | Returns the value from a JSON column after the evaluating path; the syntactic sugar of `JSON_EXTRACT(doc, path_literal)`   |
+| [->>][json_short_extract_unquote]  | Returns the value from a JSON column after the evaluating path and unquoting the result; the syntactic sugar of `JSON_UNQUOTE(JSON_EXTRACT(doc, path_literal))` |
 
 ## Functions that modify JSON values
 
 | Function Name and Syntactic Sugar | Description |
 | --------------------------------- | ----------- |
-| [JSON_INSERT(json_doc, path, val[, path, val] ...)][json_insert] | Insert data into a JSON document and return the result |
-| [JSON_MERGE(json_doc, json_doc[, json_doc] ...)][json_merge]  | Merge two or more JSON documents and return the merged result |
-| [JSON_REMOVE(json_doc, path[, path] ...)][json_remove]    | Remove data from a JSON document and return the result |
-| [JSON_REPLACE(json_doc, path, val[, path, val] ...)][json_replace] | Replace existing values in a JSON document and return the result |
-| [JSON_SET(json_doc, path, val[, path, val] ...)][json_set]  | Insert or update data in a JSON document and return the result |
-| [JSON_UNQUOTE(json_val)][json_unquote] |  Unquote JSON value and return the result as a string |
+| [JSON_INSERT(json_doc, path, val[, path, val] ...)][json_insert] | Inserts data into a JSON document and returns the result |
+| [JSON_MERGE(json_doc, json_doc[, json_doc] ...)][json_merge]  | Merges two or more JSON documents and returns the merged result |
+| [JSON_REMOVE(json_doc, path[, path] ...)][json_remove]    | Removes data from a JSON document and returns the result |
+| [JSON_REPLACE(json_doc, path, val[, path, val] ...)][json_replace] | Replaces existing values in a JSON document and returns the result |
+| [JSON_SET(json_doc, path, val[, path, val] ...)][json_set]  | Inserts or updates data in a JSON document and returns the result |
+| [JSON_UNQUOTE(json_val)][json_unquote] |  Unquotes a JSON value and returns the result as a string |
 
 ## Functions that return JSON value attributes
 
 | Function Name and Syntactic Sugar | Description |
 | --------------------------------- | ----------- |
 | [JSON_LENGTH(json_doc[, path])][json_length] | Returns the length of a JSON document, or, if a path argument is given, the length of the value within the path |
-| [JSON_TYPE(json_val)][json_type] | Return a string indicating the type of a JSON value |
+| [JSON_TYPE(json_val)][json_type] | Returns a string indicating the type of a JSON value |
 
 ## Unsupported functions
 
-The following JSON functions are unsupported in TiDB.  You can track our progress in adding them in [TIDB #7546](https://github.com/pingcap/tidb/issues/7546):
+The following JSON functions are unsupported in TiDB. You can track the progress in adding them in [TiDB #7546](https://github.com/pingcap/tidb/issues/7546):
 
 * `JSON_APPEND` and its alias `JSON_ARRAY_APPEND`
 * `JSON_ARRAY_INSERT`