Repository: impala Updated Branches: refs/heads/master 5e92d139b -> 6399a65a0
IMPALA-7715: [DOCS] Better descriptions for conditional functions - Updated the descriptions for ISTRUE, ISFALSE, NONULVALUE, NULLVALUE. - Updated several function names to use caps. Change-Id: I5cc90d62645730d2674bcb3af614863aa92b92f6 Reviewed-on: http://gerrit.cloudera.org:8080/11704 Tested-by: Impala Public Jenkins <[email protected]> Reviewed-by: Paul Rogers <[email protected]> Reviewed-by: Alex Rodoni <[email protected]> Project: http://git-wip-us.apache.org/repos/asf/impala/repo Commit: http://git-wip-us.apache.org/repos/asf/impala/commit/a0f351a6 Tree: http://git-wip-us.apache.org/repos/asf/impala/tree/a0f351a6 Diff: http://git-wip-us.apache.org/repos/asf/impala/diff/a0f351a6 Branch: refs/heads/master Commit: a0f351a647b7f48468e6dd3877a16947a746ab9c Parents: 5e92d13 Author: Alex Rodoni <[email protected]> Authored: Tue Oct 16 15:45:49 2018 -0700 Committer: Alex Rodoni <[email protected]> Committed: Wed Oct 17 18:49:55 2018 +0000 ---------------------------------------------------------------------- docs/shared/impala_common.xml | 116 ++++++++++------------ docs/topics/impala_conditional_functions.xml | 98 ++++++++++++------ 2 files changed, 120 insertions(+), 94 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/impala/blob/a0f351a6/docs/shared/impala_common.xml ---------------------------------------------------------------------- diff --git a/docs/shared/impala_common.xml b/docs/shared/impala_common.xml index 847bc9a..cb4be6c 100644 --- a/docs/shared/impala_common.xml +++ b/docs/shared/impala_common.xml @@ -811,59 +811,49 @@ The above raises an error at parse-time. HBase tables. </p> - <p id="boolean_functions_vs_expressions" rev="2.11.0 IMPALA-1767"> - In <keyword keyref="impala211_full"/> and higher, you can use - the operators <codeph>IS [NOT] TRUE</codeph> and - <codeph>IS [NOT] FALSE</codeph> as equivalents for the built-in - functions <codeph>istrue()</codeph>, <codeph>isnottrue()</codeph>, - <codeph>isfalse()</codeph>, and <codeph>isnotfalse()</codeph>. - </p> - - <p id="base64_charset"> - The set of characters that can be generated as output - from <codeph>base64encode()</codeph>, or specified in - the argument string to <codeph>base64decode()</codeph>, - are the ASCII uppercase and lowercase letters (A-Z, a-z), - digits (0-9), and the punctuation characters - <codeph>+</codeph>, <codeph>/</codeph>, and <codeph>=</codeph>. - </p> - - <p id="base64_error_handling"> - If the argument string to <codeph>base64decode()</codeph> does - not represent a valid base64-encoded value, subject to the - constraints of the Impala implementation such as the allowed - character set, the function returns <codeph>NULL</codeph>. - </p> - - <p id="base64_use_cases"> - The functions <codeph>base64encode()</codeph> and - <codeph>base64decode()</codeph> are typically used - in combination, to store in an Impala table string data that is - problematic to store or transmit. For example, you could use - these functions to store string data that uses an encoding - other than UTF-8, or to transform the values in contexts that - require ASCII values, such as for partition key columns. - Keep in mind that base64-encoded values produce different results - for string functions such as <codeph>LENGTH()</codeph>, - <codeph>MAX()</codeph>, and <codeph>MIN()</codeph> than when - those functions are called with the unencoded string values. - </p> - - <p id="base64_alignment"> - All return values produced by <codeph>base64encode()</codeph> - are a multiple of 4 bytes in length. All argument values - supplied to <codeph>base64decode()</codeph> must also be a - multiple of 4 bytes in length. If a base64-encoded value - would otherwise have a different length, it can be padded - with trailing <codeph>=</codeph> characters to reach a length - that is a multiple of 4 bytes. - </p> - - <p id="base64_examples"> - The following examples show how to use <codeph>base64encode()</codeph> - and <codeph>base64decode()</codeph> together to store and retrieve - string values: -<codeblock> + <p id="boolean_functions_vs_expressions" rev="2.11.0 IMPALA-1767"> In + <keyword keyref="impala211_full"/> and higher, you can use the + operators <codeph>IS [NOT] TRUE</codeph> and <codeph>IS [NOT] + FALSE</codeph> as equivalents for the built-in functions + <codeph>ISTRUE()</codeph>, <codeph>ISNOTTRUE()</codeph>, + <codeph>ISFALSE()</codeph>, and <codeph>ISNOTFALSE()</codeph>. </p> + + <p id="base64_charset"> The set of characters that can be generated as + output from <codeph>BASE64ENCODE()</codeph>, or specified in the + argument string to <codeph>BASE64DECODE()</codeph>, are the ASCII + uppercase and lowercase letters (A-Z, a-z), digits (0-9), and the + punctuation characters <codeph>+</codeph>, <codeph>/</codeph>, and + <codeph>=</codeph>. </p> + + <p id="base64_error_handling"> If the argument string to + <codeph>BASE64DECODE()</codeph> does not represent a valid + base64-encoded value, subject to the constraints of the Impala + implementation such as the allowed character set, the function returns + <codeph>NULL</codeph>. </p> + + <p id="base64_use_cases"> The functions <codeph>BASE64ENCODE()</codeph> + and <codeph>BASE64DECODE()</codeph> are typically used in combination, + to store in an Impala table string data that is problematic to store or + transmit. For example, you could use these functions to store string + data that uses an encoding other than UTF-8, or to transform the values + in contexts that require ASCII values, such as for partition key + columns. Keep in mind that base64-encoded values produce different + results for string functions such as <codeph>LENGTH()</codeph>, + <codeph>MAX()</codeph>, and <codeph>MIN()</codeph> than when those + functions are called with the unencoded string values. </p> + + <p id="base64_alignment"> All return values produced by + <codeph>BASE64ENCODE()</codeph> are a multiple of 4 bytes in length. + All argument values supplied to <codeph>BASE64DECODE()</codeph> must + also be a multiple of 4 bytes in length. If a base64-encoded value would + otherwise have a different length, it can be padded with trailing + <codeph>=</codeph> characters to reach a length that is a multiple of + 4 bytes. </p> + + <p id="base64_examples"> The following examples show how to use + <codeph>BASE64ENCODE()</codeph> and <codeph>BASE64DECODE()</codeph> + together to store and retrieve string values: + <codeblock> -- An arbitrary string can be encoded in base 64. -- The length of the output is a multiple of 4 bytes, -- padded with trailing = characters if necessary. @@ -884,11 +874,9 @@ select base64decode('aGVsbG8gd29ybGQ=') as decoded; | hello world | +-------------+ </codeblock> - - These examples demonstrate incorrect encoded values that - produce <codeph>NULL</codeph> return values when decoded: - -<codeblock> + These examples demonstrate incorrect encoded values that produce + <codeph>NULL</codeph> return values when decoded: + <codeblock> -- The input value to base64decode() must be a multiple of 4 bytes. -- In this case, leaving off the trailing = padding character -- produces a NULL return value. @@ -911,13 +899,11 @@ select base64decode('abc$'); +----------------------+ WARNINGS: UDF WARNING: Could not base64 decode input in space 4; actual output length 0 </codeblock> - - These examples demonstrate <q>round-tripping</q> of an original string to an - encoded string, and back again. This technique is applicable if the original - source is in an unknown encoding, or if some intermediate processing stage - might cause national characters to be misrepresented: - -<codeblock> + These examples demonstrate <q>round-tripping</q> of an original string + to an encoded string, and back again. This technique is applicable if + the original source is in an unknown encoding, or if some intermediate + processing stage might cause national characters to be misrepresented: + <codeblock> select 'circumflex accents: â, ê, î, ô, û' as original, base64encode('circumflex accents: â, ê, î, ô, û') as encoded; +-----------------------------------+------------------------------------------------------+ http://git-wip-us.apache.org/repos/asf/impala/blob/a0f351a6/docs/topics/impala_conditional_functions.xml ---------------------------------------------------------------------- diff --git a/docs/topics/impala_conditional_functions.xml b/docs/topics/impala_conditional_functions.xml index 106c518..ddb824e 100644 --- a/docs/topics/impala_conditional_functions.xml +++ b/docs/topics/impala_conditional_functions.xml @@ -171,8 +171,9 @@ under the License. </dt> <dd> - <b>Purpose:</b> Tests whether any of a sequence of expressions is true, and returns a - corresponding result for the first true expression. + <b>Purpose:</b> Tests whether any of a sequence of expressions is + <codeph>TRUE</codeph>, and returns a corresponding result for the first true + expression. <p conref="../shared/impala_common.xml#common/return_same_type"/> @@ -308,7 +309,8 @@ under the License. <dd> <b>Purpose:</b> Tests an expression and returns a corresponding result depending on - whether the result is true, false, or <codeph>NULL</codeph>. + whether the result is <codeph>TRUE</codeph>, <codeph>FALSE</codeph>, or + <codeph>NULL</codeph>. <p> <b>Return type:</b> Same as the <codeph>ifTrue</codeph> argument value </p> @@ -337,12 +339,18 @@ under the License. </dt> <dd> - <b>Purpose:</b> Tests if a Boolean expression is <codeph>false</codeph> or not. - Returns <codeph>true</codeph> if so. If the argument is <codeph>NULL</codeph>, returns - <codeph>false</codeph>. Similar to <codeph>ISNOTTRUE()</codeph>, except it returns the - opposite value for a <codeph>NULL</codeph> argument. - <p - conref="../shared/impala_common.xml#common/return_type_boolean"/> + <b>Purpose:</b> Returns <codeph>TRUE</codeph> if the expression is + <codeph>FALSE</codeph>. Returns <codeph>FALSE</codeph> if the expression is + <codeph>TRUE</codeph> or <codeph>NULL</codeph>. + <p> + Same as the <codeph>IS FALSE</codeph> operator. + </p> + <p> + Similar to <codeph>ISNOTTRUE()</codeph>, except it returns the opposite value for a + <codeph>NULL</codeph> argument. + </p> + + <p conref="../shared/impala_common.xml#common/return_type_boolean"/> <p conref="../shared/impala_common.xml#common/added_in_220"/> @@ -362,11 +370,16 @@ under the License. </dt> <dd> - <b>Purpose:</b> Tests if a Boolean expression is not <codeph>false</codeph> (that is, - either <codeph>true</codeph> or <codeph>NULL</codeph>). Returns <codeph>true</codeph> - if so. If the argument is <codeph>NULL</codeph>, returns <codeph>true</codeph>. - Similar to <codeph>ISTRUE()</codeph>, except it returns the opposite value for a - <codeph>NULL</codeph> argument. + <b>Purpose:</b> Tests if a Boolean expression is not <codeph>FALSE</codeph> (that is, + either <codeph>TRUE</codeph> or <codeph>NULL</codeph>). Returns <codeph>TRUE</codeph> + if so. If the argument is <codeph>NULL</codeph>, returns <codeph>TRUE</codeph>. + <p> + Same as the <codeph>IS NOT FALSE</codeph> operator. + </p> + <p> + Similar to <codeph>ISTRUE()</codeph>, except it returns the opposite value for a + <codeph>NULL</codeph> argument. + </p> <p conref="../shared/impala_common.xml#common/return_type_boolean"/> @@ -390,11 +403,16 @@ under the License. </dt> <dd> - <b>Purpose:</b> Tests if a Boolean expression is not <codeph>true</codeph> (that is, - either <codeph>false</codeph> or <codeph>NULL</codeph>). Returns <codeph>true</codeph> - if so. If the argument is <codeph>NULL</codeph>, returns <codeph>true</codeph>. - Similar to <codeph>ISFALSE()</codeph>, except it returns the opposite value for a - <codeph>NULL</codeph> argument. + <b>Purpose:</b> Tests if a Boolean expression is not <codeph>TRUE</codeph> (that is, + either <codeph>FALSE</codeph> or <codeph>NULL</codeph>). Returns <codeph>TRUE</codeph> + if so. If the argument is <codeph>NULL</codeph>, returns <codeph>TRUE</codeph>. + <p> + Same as the <codeph>IS NOT TRUE</codeph> operator. + </p> + <p> + Similar to <codeph>ISFALSE()</codeph>, except it returns the opposite value for a + <codeph>NULL</codeph> argument. + </p> <p conref="../shared/impala_common.xml#common/return_type_boolean"/> @@ -439,12 +457,18 @@ under the License. </dt> <dd> - <b>Purpose:</b> Tests if a Boolean expression is <codeph>true</codeph> or not. Returns - <codeph>true</codeph> if so. If the argument is <codeph>NULL</codeph>, returns - <codeph>false</codeph>. Similar to <codeph>ISNOTFALSE()</codeph>, except it returns - the opposite value for a <codeph>NULL</codeph> argument. - <p - conref="../shared/impala_common.xml#common/return_type_boolean"/> + <b>Purpose:</b> Returns <codeph>TRUE</codeph> if the expression is + <codeph>TRUE</codeph>. Returns <codeph>FALSE</codeph> if the expression is + <codeph>FALSE</codeph> or <codeph>NULL</codeph>. + <p> + Same as the <codeph>IS TRUE</codeph> operator. + </p> + <p> + Similar to <codeph>ISNOTFALSE()</codeph>, except it returns the opposite value for a + <codeph>NULL</codeph> argument. + </p> + + <p conref="../shared/impala_common.xml#common/return_type_boolean"/> <p conref="../shared/impala_common.xml#common/for_compatibility_only"/> @@ -466,8 +490,16 @@ under the License. </dt> <dd> - <b>Purpose:</b> Tests if an expression (of any type) is <codeph>NULL</codeph> or not. - Returns <codeph>false</codeph> if so. The converse of <codeph>NULLVALUE()</codeph>. + <b>Purpose:</b> Returns <codeph>TRUE</codeph> if the expression is non-null and + returns <codeph>FALSE</codeph> if the expression is <codeph>NULL</codeph>. + <p> + Same as the <codeph>IS NOT NULL</codeph> operator. + </p> + + <p> + The converse of <codeph>NULLVALUE()</codeph>. + </p> + <p conref="../shared/impala_common.xml#common/return_type_boolean"/> @@ -549,8 +581,16 @@ END</codeblock> </dt> <dd> - <b>Purpose:</b> Tests if an expression (of any type) is <codeph>NULL</codeph> or not. - Returns <codeph>true</codeph> if so. The converse of <codeph>NONNULLVALUE()</codeph>. + <b>Purpose:</b> Returns <codeph>TRUE</codeph> if the expression is + <codeph>NULL</codeph>, and returns <codeph>FALSE</codeph> otherwise. + <p> + Same as the <codeph>IS NULL</codeph> operator. + </p> + + <p> + The converse of <codeph>NONNULLVALUE()</codeph>. + </p> + <p conref="../shared/impala_common.xml#common/return_type_boolean"/>
