From 3d30209e9b60ce4a6400ee095bed2eb74cb1b63c Mon Sep 17 00:00:00 2001 From: steadyBoy <35027788+steadyBoy@users.noreply.github.com> Date: Wed, 9 Mar 2022 13:05:13 +0800 Subject: [PATCH] [docs] add document conditional-functions (#8339) Add conditional-functions. --- docs/.vuepress/sidebar/en.js | 11 +++ docs/.vuepress/sidebar/zh-CN.js | 11 +++ .../conditional-functions/case.md | 72 +++++++++++++++++++ .../conditional-functions/coalesce.md | 47 ++++++++++++ .../sql-functions/conditional-functions/if.md | 50 +++++++++++++ .../conditional-functions/ifnull.md | 54 ++++++++++++++ .../conditional-functions/nullif.md | 61 ++++++++++++++++ .../conditional-functions/case.md | 72 +++++++++++++++++++ .../conditional-functions/coalesce.md | 47 ++++++++++++ .../sql-functions/conditional-functions/if.md | 50 +++++++++++++ .../conditional-functions/ifnull.md | 54 ++++++++++++++ .../conditional-functions/nullif.md | 61 ++++++++++++++++ 12 files changed, 590 insertions(+) create mode 100644 docs/en/sql-reference/sql-functions/conditional-functions/case.md create mode 100644 docs/en/sql-reference/sql-functions/conditional-functions/coalesce.md create mode 100644 docs/en/sql-reference/sql-functions/conditional-functions/if.md create mode 100644 docs/en/sql-reference/sql-functions/conditional-functions/ifnull.md create mode 100644 docs/en/sql-reference/sql-functions/conditional-functions/nullif.md create mode 100644 docs/zh-CN/sql-reference/sql-functions/conditional-functions/case.md create mode 100644 docs/zh-CN/sql-reference/sql-functions/conditional-functions/coalesce.md create mode 100644 docs/zh-CN/sql-reference/sql-functions/conditional-functions/if.md create mode 100644 docs/zh-CN/sql-reference/sql-functions/conditional-functions/ifnull.md create mode 100644 docs/zh-CN/sql-reference/sql-functions/conditional-functions/nullif.md diff --git a/docs/.vuepress/sidebar/en.js b/docs/.vuepress/sidebar/en.js index 8c050ca440..9c190bc947 100644 --- a/docs/.vuepress/sidebar/en.js +++ b/docs/.vuepress/sidebar/en.js @@ -483,6 +483,17 @@ module.exports = [ "bitnot" ], }, + { + title: "conditional function", + directoryPath: "conditional-functions/", + children: [ + "case", + "coalesce", + "if", + "ifnull", + "nullif" + ], + }, { title: "json function", directoryPath: "json-functions/", diff --git a/docs/.vuepress/sidebar/zh-CN.js b/docs/.vuepress/sidebar/zh-CN.js index a9154ad9ec..5d2f5a6a97 100644 --- a/docs/.vuepress/sidebar/zh-CN.js +++ b/docs/.vuepress/sidebar/zh-CN.js @@ -485,6 +485,17 @@ module.exports = [ "bitnot" ], }, + { + title: "条件函数", + directoryPath: "conditional-functions/", + children: [ + "case", + "coalesce", + "if", + "ifnull", + "nullif" + ], + }, { title: "json 函数", directoryPath: "json-functions/", diff --git a/docs/en/sql-reference/sql-functions/conditional-functions/case.md b/docs/en/sql-reference/sql-functions/conditional-functions/case.md new file mode 100644 index 0000000000..846140f4ba --- /dev/null +++ b/docs/en/sql-reference/sql-functions/conditional-functions/case.md @@ -0,0 +1,72 @@ +--- +{ + "title": "case", + "language": "en" +} +--- + + + +# case +## description +### Syntax + +``` +CASE expression + WHEN condition1 THEN result1 + [WHEN condition2 THEN result2] + ... + [WHEN conditionN THEN resultN] + [ELSE result] +END +``` +OR +``` +CASE WHEN condition1 THEN result1 + [WHEN condition2 THEN result2] + ... + [WHEN conditionN THEN resultN] + [ELSE result] +END +``` + +Compare the expression with multiple possible values, and return the corresponding results when matching + +## example + +``` +mysql> select user_id, case user_id when 1 then 'user_id = 1' when 2 then 'user_id = 2' else 'user_id not exist' end test_case from test; ++---------+-------------+ +| user_id | test_case | ++---------+-------------+ +| 1 | user_id = 1 | +| 2 | user_id = 2 | ++---------+-------------+ + +mysql> select user_id, case when user_id = 1 then 'user_id = 1' when user_id = 2 then 'user_id = 2' else 'user_id not exist' end test_case from test; ++---------+-------------+ +| user_id | test_case | ++---------+-------------+ +| 1 | user_id = 1 | +| 2 | user_id = 2 | ++---------+-------------+ +``` +## keyword +CASE diff --git a/docs/en/sql-reference/sql-functions/conditional-functions/coalesce.md b/docs/en/sql-reference/sql-functions/conditional-functions/coalesce.md new file mode 100644 index 0000000000..b3073e54eb --- /dev/null +++ b/docs/en/sql-reference/sql-functions/conditional-functions/coalesce.md @@ -0,0 +1,47 @@ +--- +{ + "title": "coalesce", + "language": "en" +} +--- + + + +# coalesce +## description +### Syntax + +`coalesce(expr1, expr2, ...., expr_n)` + + +Returns the first non empty expression in the parameter (from left to right) + +## example + +``` +mysql> select coalesce(NULL, '1111', '0000'); ++--------------------------------+ +| coalesce(NULL, '1111', '0000') | ++--------------------------------+ +| 1111 | ++--------------------------------+ +``` +## keyword +COALESCE diff --git a/docs/en/sql-reference/sql-functions/conditional-functions/if.md b/docs/en/sql-reference/sql-functions/conditional-functions/if.md new file mode 100644 index 0000000000..82b66cfa61 --- /dev/null +++ b/docs/en/sql-reference/sql-functions/conditional-functions/if.md @@ -0,0 +1,50 @@ +--- +{ + "title": "if", + "language": "en" +} +--- + + + +# if +## description +### Syntax + +`if(boolean condition, type valueTrue, type valueFalseOrNull)` + + +Returns valueTrue when condition is true, returns valueFalseOrNull otherwise. + +The return type is the type of the result of the valueTrue/valueFalseOrNull expression + +## example + +``` +mysql> select user_id, if(user_id = 1, "true", "false") test_if from test; ++---------+---------+ +| user_id | test_if | ++---------+---------+ +| 1 | true | +| 2 | false | ++---------+---------+ +``` +## keyword +IF diff --git a/docs/en/sql-reference/sql-functions/conditional-functions/ifnull.md b/docs/en/sql-reference/sql-functions/conditional-functions/ifnull.md new file mode 100644 index 0000000000..7d22efb7f9 --- /dev/null +++ b/docs/en/sql-reference/sql-functions/conditional-functions/ifnull.md @@ -0,0 +1,54 @@ +--- +{ + "title": "ifnull", + "language": "en" +} +--- + + + +# ifnull +## description +### Syntax + +`ifnull(expr1, expr2)` + + +If the value of expr1 is not null, expr1 is returned, otherwise expr2 is returned + +## example + +``` +mysql> select ifnull(1,0); ++--------------+ +| ifnull(1, 0) | ++--------------+ +| 1 | ++--------------+ + +mysql> select ifnull(null,10); ++------------------+ +| ifnull(NULL, 10) | ++------------------+ +| 10 | ++------------------+ +``` +## keyword +IFNULL diff --git a/docs/en/sql-reference/sql-functions/conditional-functions/nullif.md b/docs/en/sql-reference/sql-functions/conditional-functions/nullif.md new file mode 100644 index 0000000000..12c5ce88be --- /dev/null +++ b/docs/en/sql-reference/sql-functions/conditional-functions/nullif.md @@ -0,0 +1,61 @@ +--- +{ + "title": "nullif", + "language": "en" +} +--- + + + +# nullif +## description +### Syntax + +`nullif(expr1, expr2)` + + +If the two parameters are equal, null is returned. Otherwise, the value of the first parameter is returned. It has the same effect as the following `case when` + +``` +CASE + WHEN expr1 = expr2 THEN NULL + ELSE expr1 +END +``` + +## example + +``` +mysql> select nullif(1,1); ++--------------+ +| nullif(1, 1) | ++--------------+ +| NULL | ++--------------+ + +mysql> select nullif(1,0); ++--------------+ +| nullif(1, 0) | ++--------------+ +| 1 | ++--------------+ +``` +## keyword +NULLIF diff --git a/docs/zh-CN/sql-reference/sql-functions/conditional-functions/case.md b/docs/zh-CN/sql-reference/sql-functions/conditional-functions/case.md new file mode 100644 index 0000000000..b1ac6376ae --- /dev/null +++ b/docs/zh-CN/sql-reference/sql-functions/conditional-functions/case.md @@ -0,0 +1,72 @@ +--- +{ + "title": "case", + "language": "zh-CN" +} +--- + + + +# case +## description +### Syntax + +``` +CASE expression + WHEN condition1 THEN result1 + [WHEN condition2 THEN result2] + ... + [WHEN conditionN THEN resultN] + [ELSE result] +END +``` +OR +``` +CASE WHEN condition1 THEN result1 + [WHEN condition2 THEN result2] + ... + [WHEN conditionN THEN resultN] + [ELSE result] +END +``` + +将表达式和多个可能的值进行比较，当匹配时返回相应的结果 + +## example + +``` +mysql> select user_id, case user_id when 1 then 'user_id = 1' when 2 then 'user_id = 2' else 'user_id not exist' end test_case from test; ++---------+-------------+ +| user_id | test_case | ++---------+-------------+ +| 1 | user_id = 1 | +| 2 | user_id = 2 | ++---------+-------------+ + +mysql> select user_id, case when user_id = 1 then 'user_id = 1' when user_id = 2 then 'user_id = 2' else 'user_id not exist' end test_case from test; ++---------+-------------+ +| user_id | test_case | ++---------+-------------+ +| 1 | user_id = 1 | +| 2 | user_id = 2 | ++---------+-------------+ +``` +## keyword +CASE diff --git a/docs/zh-CN/sql-reference/sql-functions/conditional-functions/coalesce.md b/docs/zh-CN/sql-reference/sql-functions/conditional-functions/coalesce.md new file mode 100644 index 0000000000..ebca147a3a --- /dev/null +++ b/docs/zh-CN/sql-reference/sql-functions/conditional-functions/coalesce.md @@ -0,0 +1,47 @@ +--- +{ + "title": "coalesce", + "language": "zh-CN" +} +--- + + + +# coalesce +## description +### Syntax + +`coalesce(expr1, expr2, ...., expr_n))` + + +返回参数中的第一个非空表达式（从左向右） + +## example + +``` +mysql> select coalesce(NULL, '1111', '0000'); ++--------------------------------+ +| coalesce(NULL, '1111', '0000') | ++--------------------------------+ +| 1111 | ++--------------------------------+ +``` +## keyword +COALESCE diff --git a/docs/zh-CN/sql-reference/sql-functions/conditional-functions/if.md b/docs/zh-CN/sql-reference/sql-functions/conditional-functions/if.md new file mode 100644 index 0000000000..2f0aea1011 --- /dev/null +++ b/docs/zh-CN/sql-reference/sql-functions/conditional-functions/if.md @@ -0,0 +1,50 @@ +--- +{ + "title": "if", + "language": "zh-CN" +} +--- + + + +# if +## description +### Syntax + +`if(boolean condition, type valueTrue, type valueFalseOrNull)` + + +如果表达式 condition 成立，返回结果 valueTrue；否则，返回结果 valueFalseOrNull +返回类型： valueTrue 表达式结果的类型 + + +## example + +``` +mysql> select user_id, if(user_id = 1, "true", "false") test_if from test; ++---------+---------+ +| user_id | test_if | ++---------+---------+ +| 1 | true | +| 2 | false | ++---------+---------+ +``` +## keyword +IF diff --git a/docs/zh-CN/sql-reference/sql-functions/conditional-functions/ifnull.md b/docs/zh-CN/sql-reference/sql-functions/conditional-functions/ifnull.md new file mode 100644 index 0000000000..1546d81a55 --- /dev/null +++ b/docs/zh-CN/sql-reference/sql-functions/conditional-functions/ifnull.md @@ -0,0 +1,54 @@ +--- +{ + "title": "ifnull", + "language": "zh-CN" +} +--- + + + +# ifnull +## description +### Syntax + +`ifnull(expr1, expr2)` + + +如果 expr1 的值不为 NULL 则返回 expr1，否则返回 expr2 + +## example + +``` +mysql> select ifnull(1,0); ++--------------+ +| ifnull(1, 0) | ++--------------+ +| 1 | ++--------------+ + +mysql> select ifnull(null,10); ++------------------+ +| ifnull(NULL, 10) | ++------------------+ +| 10 | ++------------------+ +``` +## keyword +IFNULL diff --git a/docs/zh-CN/sql-reference/sql-functions/conditional-functions/nullif.md b/docs/zh-CN/sql-reference/sql-functions/conditional-functions/nullif.md new file mode 100644 index 0000000000..d5d66b658d --- /dev/null +++ b/docs/zh-CN/sql-reference/sql-functions/conditional-functions/nullif.md @@ -0,0 +1,61 @@ +--- +{ + "title": "nullif", + "language": "zh-CN" +} +--- + + + +# nullif +## description +### Syntax + +`nullif(expr1, expr2)` + + +如果两个参数相等，则返回NULL。否则返回第一个参数的值。它和以下的 `CASE WHEN` 效果一样 + +``` +CASE + WHEN expr1 = expr2 THEN NULL + ELSE expr1 +END +``` + +## example + +``` +mysql> select nullif(1,1); ++--------------+ +| nullif(1, 1) | ++--------------+ +| NULL | ++--------------+ + +mysql> select nullif(1,0); ++--------------+ +| nullif(1, 0) | ++--------------+ +| 1 | ++--------------+ +``` +## keyword +NULLIF