diff --git a/docs/en/sql-reference/functions/comparison-functions.md b/docs/en/sql-reference/functions/comparison-functions.md index f03dc04a21a370b3790cf3bee1cce9d194bddcd8..0b6d8b6e36e0d888ebf475ccd5587442afab7dcd 100644 --- a/docs/en/sql-reference/functions/comparison-functions.md +++ b/docs/en/sql-reference/functions/comparison-functions.md @@ -22,7 +22,7 @@ Strings are compared by bytes. A shorter string is smaller than all strings that ## equals, a = b and a == b operator {#function-equals} -## notEquals, a ! operator= b and a \<\> b {#function-notequals} +## notEquals, a != b and a \<\> b operator {#function-notequals} ## less, \< operator {#function-less} diff --git a/docs/zh/sql-reference/data-types/lowcardinality.md b/docs/zh/sql-reference/data-types/lowcardinality.md new file mode 100644 index 0000000000000000000000000000000000000000..b8985691f0f0a270f2b0c9ca4e75c4a2c4472946 --- /dev/null +++ b/docs/zh/sql-reference/data-types/lowcardinality.md @@ -0,0 +1,59 @@ +--- +toc_priority: 51 +toc_title: 低基数类型 +--- + +# 低基数类型 {#lowcardinality-data-type} + +把其它数据类型转变为字典编码类型。 + +## 语法 {#lowcardinality-syntax} + +```sql +LowCardinality(data_type) +``` + +**参数** + +- `data_type` — [String](string.md), [FixedString](fixedstring.md), [Date](date.md), [DateTime](datetime.md),包括数字类型,但是[Decimal](decimal.md)除外。对一些数据类型来说,`LowCardinality` 并不高效,详查[allow_suspicious_low_cardinality_types](../../operations/settings/settings.md#allow_suspicious_low_cardinality_types)设置描述。 + +## 描述 {#lowcardinality-dscr} + +`LowCardinality` 是一种改变数据存储和数据处理方法的概念。 ClickHouse会把 `LowCardinality` 所在的列进行[dictionary coding](https://en.wikipedia.org/wiki/Dictionary_coder)。对很多应用来说,处理字典编码的数据可以显著的增加[SELECT](../statements/select/index.md)查询速度。 + +使用 `LowCarditality` 数据类型的效率依赖于数据的多样性。如果一个字典包含少于10000个不同的值,那么ClickHouse可以进行更高效的数据存储和处理。反之如果字典多于10000,效率会表现的更差。 + +当使用字符类型的时候,可以考虑使用 `LowCardinality` 代替[Enum](enum.md)。 `LowCardinality` 通常更加灵活和高效。 + +## 例子 + +创建一个 `LowCardinality` 类型的列: + +```sql +CREATE TABLE lc_t +( + `id` UInt16, + `strings` LowCardinality(String) +) +ENGINE = MergeTree() +ORDER BY id +``` + +## 相关的设置和函数 + +设置: + +- [low_cardinality_max_dictionary_size](../../operations/settings/settings.md#low_cardinality_max_dictionary_size) +- [low_cardinality_use_single_dictionary_for_part](../../operations/settings/settings.md#low_cardinality_use_single_dictionary_for_part) +- [low_cardinality_allow_in_native_format](../../operations/settings/settings.md#low_cardinality_allow_in_native_format) +- [allow_suspicious_low_cardinality_types](../../operations/settings/settings.md#allow_suspicious_low_cardinality_types) + +函数: + +- [toLowCardinality](../functions/type-conversion-functions.md#tolowcardinality) + +## 参考 + +- [高效低基数类型](https://www.altinity.com/blog/2019/3/27/low-cardinality). +- [使用低基数类型减少ClickHouse的存储成本 – 来自Instana工程师的分享](https://www.instana.com/blog/reducing-clickhouse-storage-cost-with-the-low-cardinality-type-lessons-from-an-instana-engineer/). +- [字符优化 (俄语视频分享)](https://youtu.be/rqf-ILRgBdY?list=PL0Z2YDlm0b3iwXCpEFiOOYmwXzVmjJfEt). [英语分享](https://github.com/yandex/clickhouse-presentations/raw/master/meetup19/string_optimization.pdf). \ No newline at end of file diff --git a/docs/zh/sql-reference/functions/arithmetic-functions.md b/docs/zh/sql-reference/functions/arithmetic-functions.md index 1c2ed3fccfc7793856e68f5ee1b7803aca7817a8..b7cfa87ef94d51ef49c92b33546695e34a647c03 100644 --- a/docs/zh/sql-reference/functions/arithmetic-functions.md +++ b/docs/zh/sql-reference/functions/arithmetic-functions.md @@ -1,3 +1,8 @@ +--- +toc_priority: 35 +toc_title: 算术函数 +--- + # 算术函数 {#suan-zhu-han-shu} 对于所有算术函数,结果类型为结果适合的最小数字类型(如果存在这样的类型)。最小数字类型是根据数字的位数,是否有符号以及是否是浮点类型而同时进行的。如果没有足够的位,则采用最高位类型。 diff --git a/docs/zh/sql-reference/functions/comparison-functions.md b/docs/zh/sql-reference/functions/comparison-functions.md index a3da3a3047a7885ded4724fb284ce8f552052e3c..8b5d72e64c2a07e7b82be84a170e669238edaceb 100644 --- a/docs/zh/sql-reference/functions/comparison-functions.md +++ b/docs/zh/sql-reference/functions/comparison-functions.md @@ -1,3 +1,8 @@ +--- +toc_priority: 36 +toc_title: 比较函数 +--- + # 比较函数 {#bi-jiao-han-shu} 比较函数始终返回0或1(UInt8)。 @@ -15,18 +20,16 @@ 字符串按字节进行比较。较短的字符串小于以其开头并且至少包含一个字符的所有字符串。 -注意。直到1.1.54134版本,有符号和无符号数字的比较方式与C++相同。换句话说,在SELECT 9223372036854775807 &gt; -1 等情况下,您可能会得到错误的结果。 此行为在版本1.1.54134中已更改,现在在数学上是正确的。 - -## 等于,a=b和a==b运算符 {#equals-a-b-and-a-b-operator} +## 等于,a=b和a==b 运算符 {#equals-a-b-and-a-b-operator} -## notEquals,a! 运算符=b和a `<>` b {#notequals-a-operator-b-and-a-b} +## 不等于,a!=b和a<>b 运算符 {#notequals-a-operator-b-and-a-b} -## 少, `< operator` {#less-operator} +## 少, < 运算符 {#less-operator} -## 更大, `> operator` {#greater-operator} +## 大于, > 运算符 {#greater-operator} -## 出租等级, `<= operator` {#lessorequals-operator} +## 小于等于, <= 运算符 {#lessorequals-operator} -## 伟大的等级, `>= operator` {#greaterorequals-operator} +## 大于等于, >= 运算符 {#greaterorequals-operator} [来源文章](https://clickhouse.tech/docs/en/query_language/functions/comparison_functions/) diff --git a/docs/zh/sql-reference/functions/index.md b/docs/zh/sql-reference/functions/index.md index 8d178592e92f8ef9d6190f045f2ac30fd2c25d28..52954c95cffb748b989c0bc0b7d494df1e22d634 100644 --- a/docs/zh/sql-reference/functions/index.md +++ b/docs/zh/sql-reference/functions/index.md @@ -1,3 +1,9 @@ +--- +toc_folder_title: 函数 +toc_priority: 32 +toc_title: 简介 +--- + # 函数 {#han-shu} ClickHouse中至少存在两种类型的函数 - 常规函数(它们称之为«函数»)和聚合函数。 常规函数的工作就像分别为每一行执行一次函数计算一样(对于每一行,函数的结果不依赖于其他行)。 聚合函数则从各行累积一组值(即函数的结果以来整个结果集)。 diff --git a/docs/zh/sql-reference/functions/logical-functions.md b/docs/zh/sql-reference/functions/logical-functions.md index b14f1bb5d37279a1a51b3e2f00fcfdff3cfd0a2f..cc168dbb1ed407d07c933c1d51768a649c65b424 100644 --- a/docs/zh/sql-reference/functions/logical-functions.md +++ b/docs/zh/sql-reference/functions/logical-functions.md @@ -1,15 +1,20 @@ +--- +toc_priority: 37 +toc_title: 逻辑函数 +--- + # 逻辑函数 {#luo-ji-han-shu} 逻辑函数可以接受任何数字类型的参数,并返回UInt8类型的0或1。 当向函数传递零时,函数将判定为«false»,否则,任何其他非零的值都将被判定为«true»。 -## 和,和运营商 {#and-and-operator} +## 和,`AND` 运算符 {#and-and-operator} -## 或,或运营商 {#or-or-operator} +## 或,`OR` 运算符 {#or-or-operator} -## 不是,不是运营商 {#not-not-operator} +## 非,`NOT` 运算符 {#not-not-operator} -## 异或 {#xor} +## 异或,`XOR` 运算符 {#xor} [来源文章](https://clickhouse.tech/docs/en/query_language/functions/logical_functions/) diff --git a/docs/zh/sql-reference/functions/type-conversion-functions.md b/docs/zh/sql-reference/functions/type-conversion-functions.md index 011b2951e74cbfab448619a8f11e753138c1503e..6e3ed9afb782714b8d5eacd94c3eadbad2130cb7 100644 --- a/docs/zh/sql-reference/functions/type-conversion-functions.md +++ b/docs/zh/sql-reference/functions/type-conversion-functions.md @@ -1,16 +1,230 @@ +--- +toc_priority: 38 +toc_title: 类型转换函数 +--- + # 类型转换函数 {#lei-xing-zhuan-huan-han-shu} -## toUInt8,toUInt16,toUInt32,toUInt64 {#touint8-touint16-touint32-touint64} +## 数值类型转换常见的问题 {#numeric-conversion-issues} + +当你把一个值从一个类型转换为另外一个类型的时候,你需要注意的是这是一个不安全的操作,可能导致数据的丢失。数据丢失一般发生在你将一个大的数据类型转换为小的数据类型的时候,或者你把两个不同的数据类型相互转换的时候。 + +ClickHouse和[C++](https://en.cppreference.com/w/cpp/language/implicit_conversion)有相同的类型转换行为。 + +## toInt(8\|16\|32\|64) {#touint8-touint16-touint32-touint64} + +转换一个输入值为[Int](../../sql-reference/data-types/int-uint.md)类型。这个函数包括: + +- `toInt8(expr)` — 结果为`Int8`数据类型。 +- `toInt16(expr)` — 结果为`Int16`数据类型。 +- `toInt32(expr)` — 结果为`Int32`数据类型。 +- `toInt64(expr)` — 结果为`Int64`数据类型。 + +**参数** + +- `expr` — [表达式](../syntax.md#syntax-expressions)返回一个数字或者代表数值类型的字符串。不支持二进制、八进制、十六进制的数字形式,有效数字之前的0也会被忽略。 + +**返回值** + +整形在`Int8`, `Int16`, `Int32`,或者 `Int64` 的数据类型。 + +函数使用[rounding towards zero](https://en.wikipedia.org/wiki/Rounding#Rounding_towards_zero)原则,这意味着会截断丢弃小数部分的数值。 + +[NaN and Inf](../../sql-reference/data-types/float.md#data_type-float-nan-inf)转换是不确定的。具体使用的时候,请参考[数值类型转换常见的问题](#numeric-conversion-issues)。 + +**例子** + +``` sql +SELECT toInt64(nan), toInt32(32), toInt16('16'), toInt8(8.8) +``` + +``` text +┌─────────toInt64(nan)─┬─toInt32(32)─┬─toInt16('16')─┬─toInt8(8.8)─┐ +│ -9223372036854775808 │ 32 │ 16 │ 8 │ +└──────────────────────┴─────────────┴───────────────┴─────────────┘ +``` + +## toInt(8\|16\|32\|64)OrZero {#toint8163264orzero} + +这个函数需要一个字符类型的入参,然后尝试把它转为`Int (8 | 16 | 32 | 64)`,如果转换失败直接返回0。 + +**例子** + +``` sql +select toInt64OrZero('123123'), toInt8OrZero('123qwe123') +``` + +``` text +┌─toInt64OrZero('123123')─┬─toInt8OrZero('123qwe123')─┐ +│ 123123 │ 0 │ +└─────────────────────────┴───────────────────────────┘ +``` +## toInt(8\|16\|32\|64)OrNull {#toint8163264ornull} + +这个函数需要一个字符类型的入参,然后尝试把它转为`Int (8 | 16 | 32 | 64)`,如果转换失败直接返回`NULL`。 + +**例子** + +``` sql +select toInt64OrNull('123123'), toInt8OrNull('123qwe123') +``` + +``` text +┌─toInt64OrNull('123123')─┬─toInt8OrNull('123qwe123')─┐ +│ 123123 │ ᴺᵁᴸᴸ │ +└─────────────────────────┴───────────────────────────┘ +``` + +## toUInt(8\|16\|32\|64) {#touint8163264} + +转换一个输入值到[UInt](../../sql-reference/data-types/int-uint.md)类型。 这个函数包括: + +- `toUInt8(expr)` — 结果为`UInt8`数据类型。 +- `toUInt16(expr)` — 结果为`UInt16`数据类型。 +- `toUInt32(expr)` — 结果为`UInt32`数据类型。 +- `toUInt64(expr)` — 结果为`UInt64`数据类型。 + +**参数** + +- `expr` — [表达式](../syntax.md#syntax-expressions)返回一个数字或者代表数值类型的字符串。不支持二进制、八进制、十六进制的数字形式,有效数字之前的0也会被忽略。 + +**返回值** + +整形在`UInt8`, `UInt16`, `UInt32`,或者 `UInt64` 的数据类型。 + +函数使用[rounding towards zero](https://en.wikipedia.org/wiki/Rounding#Rounding_towards_zero)原则,这意味着会截断丢弃小数部分的数值。 + +对于负数和[NaN and Inf](../../sql-reference/data-types/float.md#data_type-float-nan-inf)来说转换的结果是不确定的。如果你传入一个负数,比如:`'-32'`,ClickHouse会抛出异常。具体使用的时候,请参考[数值类型转换常见的问题](#numeric-conversion-issues)。 + +**例子** + +``` sql +SELECT toUInt64(nan), toUInt32(-32), toUInt16('16'), toUInt8(8.8) +``` + +``` text +┌───────toUInt64(nan)─┬─toUInt32(-32)─┬─toUInt16('16')─┬─toUInt8(8.8)─┐ +│ 9223372036854775808 │ 4294967264 │ 16 │ 8 │ +└─────────────────────┴───────────────┴────────────────┴──────────────┘ +``` + +## toUInt(8\|16\|32\|64)OrZero {#touint8163264orzero} + +## toUInt(8\|16\|32\|64)OrNull {#touint8163264ornull} + +## toFloat(32\|64) {#tofloat3264} + +## toFloat(32\|64)OrZero {#tofloat3264orzero} + +## toFloat(32\|64)OrNull {#tofloat3264ornull} + +## toDate {#todate} + +## toDateOrZero {#todateorzero} + +## toDateOrNull {#todateornull} -## toInt8,toInt16,toInt32,toInt64 {#toint8-toint16-toint32-toint64} +## toDateTime {#todatetime} -## toFloat32,toFloat64 {#tofloat32-tofloat64} +## toDateTimeOrZero {#todatetimeorzero} -## 今天,今天 {#todate-todatetime} +## toDateTimeOrNull {#todatetimeornull} -## toUInt8OrZero,toUInt16OrZero,toUInt32OrZero,toUInt64OrZero,toInt8OrZero,toInt16OrZero,toInt32OrZero,toInt64OrZero,toFloat32OrZero,toFloat64OrZero,toDateOrZero,toDateTimeOrZero {#touint8orzero-touint16orzero-touint32orzero-touint64orzero-toint8orzero-toint16orzero-toint32orzero-toint64orzero-tofloat32orzero-tofloat64orzero-todateorzero-todatetimeorzero} +## toDecimal(32\|64\|128) {#todecimal3264128} + +转换 `value` 到[Decimal](../../sql-reference/data-types/decimal.md)类型的值,其中精度为`S`。`value`可以是一个数字或者一个字符串。`S` 指定小数位的精度。 + +- `toDecimal32(value, S)` +- `toDecimal64(value, S)` +- `toDecimal128(value, S)` + +## toDecimal(32\|64\|128)OrNull {#todecimal3264128ornull} + +转换一个输入的字符到[Nullable(Decimal(P,S))](../../sql-reference/data-types/decimal.md)类型的数据。这个函数包括: + +- `toDecimal32OrNull(expr, S)` — 结果为`Nullable(Decimal32(S))`数据类型。 +- `toDecimal64OrNull(expr, S)` — 结果为`Nullable(Decimal64(S))`数据类型。 +- `toDecimal128OrNull(expr, S)` — 结果为`Nullable(Decimal128(S))`数据类型。 + +如果在解析输入值发生错误的时候你希望得到一个`NULL`值而不是抛出异常,你可以使用该函数。 + +**参数** + +- `expr` — [表达式](../syntax.md#syntax-expressions)返回一个[String](../../sql-reference/data-types/string.md)类型的数据。 ClickHouse倾向于文本类型的表示带小数类型的数值,比如`'1.111'`。 +- `S` — 小数位的精度。 + +**返回值** + +`Nullable(Decimal(P,S))`类型的数据,包括: + +- 如果有的话,小数位`S`。 +- 如果解析错误或者输入的数字的小数位多于`S`,那结果为`NULL`。 + +**例子** + +``` sql +SELECT toDecimal32OrNull(toString(-1.111), 5) AS val, toTypeName(val) +``` + +``` text +┌──────val─┬─toTypeName(toDecimal32OrNull(toString(-1.111), 5))─┐ +│ -1.11100 │ Nullable(Decimal(9, 5)) │ +└──────────┴────────────────────────────────────────────────────┘ +``` + +``` sql +SELECT toDecimal32OrNull(toString(-1.111), 2) AS val, toTypeName(val) +``` + +``` text +┌──val─┬─toTypeName(toDecimal32OrNull(toString(-1.111), 2))─┐ +│ ᴺᵁᴸᴸ │ Nullable(Decimal(9, 2)) │ +└──────┴────────────────────────────────────────────────────┘ +``` + +## toDecimal(32\|64\|128)OrZero {#todecimal3264128orzero} + +转换输入值为[Decimal(P,S)](../../sql-reference/data-types/decimal.md)类型数据。这个函数包括: + +- `toDecimal32OrZero( expr, S)` — 结果为`Decimal32(S)` 数据类型。 +- `toDecimal64OrZero( expr, S)` — 结果为`Decimal64(S)` 数据类型。 +- `toDecimal128OrZero( expr, S)` — 结果为`Decimal128(S)` 数据类型。 + +当解析错误的时候,你不需要抛出异常而希望得到`0`值,你可以使用该函数。 + +**参数** + +- `expr` — [表达式](../syntax.md#syntax-expressions)返回一个[String](../../sql-reference/data-types/string.md)类型的数据。 ClickHouse倾向于文本类型的表示带小数类型的数值,比如`'1.111'`。 +- `S` — 小数位的精度。 + +**返回值** + +A value in the `Nullable(Decimal(P,S))` data type. The value contains: + +- 如果有的话,小数位`S`。 +- 如果解析错误或者输入的数字的小数位多于`S`,那结果为小数位精度为`S`的`0`。 +**例子** + +``` sql +SELECT toDecimal32OrZero(toString(-1.111), 5) AS val, toTypeName(val) +``` + +``` text +┌──────val─┬─toTypeName(toDecimal32OrZero(toString(-1.111), 5))─┐ +│ -1.11100 │ Decimal(9, 5) │ +└──────────┴────────────────────────────────────────────────────┘ +``` + +``` sql +SELECT toDecimal32OrZero(toString(-1.111), 2) AS val, toTypeName(val) +``` + +``` text +┌──val─┬─toTypeName(toDecimal32OrZero(toString(-1.111), 2))─┐ +│ 0.00 │ Decimal(9, 2) │ +└──────┴────────────────────────────────────────────────────┘ +``` -## toUInt8OrNull,toUInt16OrNull,toUInt32OrNull,toUInt64OrNull,toInt8OrNull,toInt16OrNull,toInt32OrNull,toInt64OrNull,toFloat32OrNull,toFloat64OrNull,toDateOrNull,toDateTimeOrNull {#touint8ornull-touint16ornull-touint32ornull-touint64ornull-toint8ornull-toint16ornull-toint32ornull-toint64ornull-tofloat32ornull-tofloat64ornull-todateornull-todatetimeornull} ## toString {#tostring} @@ -47,10 +261,6 @@ SELECT 另请参阅`toUnixTimestamp`函数。 -## toDecimal32(value,S),toDecimal64(value,S),toDecimal128(value,S) {#todecimal32value-s-todecimal64value-s-todecimal128value-s} - -将`value`转换为精度为`S`的[十进制](../../sql-reference/functions/type-conversion-functions.md)。`value`可以是数字或字符串。`S`参数为指定的小数位数。 - ## toFixedString(s,N) {#tofixedstrings-n} 将String类型的参数转换为FixedString(N)类型的值(具有固定长度N的字符串)。N必须是一个常量。 @@ -78,17 +288,19 @@ SELECT toFixedString('foo\0bar', 8) AS s, toStringCutToZero(s) AS s_cut │ foo\0bar\0 │ foo │ └────────────┴───────┘ -## reinterpretAsUInt8,reinterpretAsUInt16,reinterpretAsUInt32,reinterpretAsUInt64 {#reinterpretasuint8-reinterpretasuint16-reinterpretasuint32-reinterpretasuint64} +## reinterpretAsUInt(8\|16\|32\|64) {#reinterpretasuint8163264} + +## reinterpretAsInt(8\|16\|32\|64) {#reinterpretasint8163264} -## reinterpretAsInt8,reinterpretAsInt16,reinterpretAsInt32,reinterpretAsInt64 {#reinterpretasint8-reinterpretasint16-reinterpretasint32-reinterpretasint64} +## reinterpretAsFloat(32\|64) {#reinterpretasfloat3264} -## reinterpretAsFloat32,reinterpretAsFloat64 {#reinterpretasfloat32-reinterpretasfloat64} +## reinterpretAsDate {#reinterpretasdate} -## 重新解释日期,重新解释日期时间 {#reinterpretasdate-reinterpretasdatetime} +## reinterpretAsDateTime {#reinterpretasdatetime} 这些函数接受一个字符串,并将放在字符串开头的字节解释为主机顺序中的数字(little endian)。如果字符串不够长,则函数就像使用必要数量的空字节填充字符串一样。如果字符串比需要的长,则忽略额外的字节。Date被解释为Unix时间戳的天数,DateTime被解释为Unix时间戳。 -## 重新解释字符串 {#reinterpretasstring} +## reinterpretAsString {#reinterpretasstring} 此函数接受数字、Date或DateTime,并返回一个字符串,其中包含表示主机顺序(小端)的相应值的字节。从末尾删除空字节。例如,UInt32类型值255是一个字节长的字符串。 @@ -96,7 +308,7 @@ SELECT toFixedString('foo\0bar', 8) AS s, toStringCutToZero(s) AS s_cut 此函数接受数字、Date或DateTime,并返回包含表示主机顺序(小端)的相应值的字节的FixedString。从末尾删除空字节。例如,UInt32类型值255是一个长度为一个字节的FixedString。 -## 演员(x,t) {#type_conversion_function-cast} +## CAST(x, T) {#type_conversion_function-cast} 将’x’转换为’t’数据类型。还支持语法CAST(x AS t) @@ -133,10 +345,32 @@ SELECT │ Nullable(UInt16) │ └─────────────────────────────────────────┘ -## 每天每天每天每天每天每天每天每天每天每天每天每天每天每天每天每天每天每天每天每天每天每天每天每天每天每天每天每天每天每天每天每 {#function-tointerval} +## toInterval(Year\|Quarter\|Month\|Week\|Day\|Hour\|Minute\|Second) {#function-tointerval} -将数字类型参数转换为Interval类型(时间区间)。 -Interval类型实际上是非常有用的,您可以使用此类型的数据直接与Date或DateTime执行算术运算。同时,ClickHouse为Interval类型数据的声明提供了更方便的语法。例如: +把一个数值类型的值转换为[Interval](../../sql-reference/data-types/special-data-types/interval.md)类型的数据。 + +**语法** + +``` sql +toIntervalSecond(number) +toIntervalMinute(number) +toIntervalHour(number) +toIntervalDay(number) +toIntervalWeek(number) +toIntervalMonth(number) +toIntervalQuarter(number) +toIntervalYear(number) +``` + +**参数** + +- `number` — 正整数,持续的时间。 + +**返回值** + +- 时间的`Interval`值。 + +**例子** ``` sql WITH @@ -148,22 +382,257 @@ SELECT date + interval_to_week ``` - ┌─plus(date, interval_week)─┬─plus(date, interval_to_week)─┐ - │ 2019-01-08 │ 2019-01-08 │ - └───────────────────────────┴──────────────────────────────┘ +``` text +┌─plus(date, interval_week)─┬─plus(date, interval_to_week)─┐ +│ 2019-01-08 │ 2019-01-08 │ +└───────────────────────────┴──────────────────────────────┘ +``` -## parsedatetimebestefort {#type_conversion_functions-parsedatetimebesteffort} +## parseDateTimeBestEffort {#parsedatetimebesteffort} -将数字类型参数解析为Date或DateTime类型。 -与toDate和toDateTime不同,parseDateTimeBestEffort可以进行更复杂的日期格式。 -有关详细信息,请参阅链接:[复杂日期格式](https://xkcd.com/1179/)。 +把[String](../../sql-reference/data-types/string.md)类型的时间日期转换为[DateTime](../../sql-reference/data-types/datetime.md#data_type-datetime)数据类型。 -## parsedatetimebestefortornull {#parsedatetimebesteffortornull} +该函数可以解析[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601),[RFC 1123 - 5.2.14 RFC-822 Date and Time Specification](https://tools.ietf.org/html/rfc1123#page-55)或者ClickHouse的一些别的时间日期格式。 -与[parsedatetimebestefort](#type_conversion_functions-parsedatetimebesteffort)相同,但它遇到无法处理的日期格式时返回null。 +**语法** -## parsedatetimebestefortorzero {#parsedatetimebesteffortorzero} +``` sql +parseDateTimeBestEffort(time_string [, time_zone]); +``` + +**参数** + +- `time_string` — 字符类型的时间和日期。 +- `time_zone` — 字符类型的时区。 + +**非标准格式的支持** + +- 9位或者10位的数字时间,[unix timestamp](https://en.wikipedia.org/wiki/Unix_time). +- 时间和日期组成的字符串: `YYYYMMDDhhmmss`, `DD/MM/YYYY hh:mm:ss`, `DD-MM-YY hh:mm`, `YYYY-MM-DD hh:mm:ss`等。 +- 只有日期的字符串: `YYYY`, `YYYYMM`, `YYYY*MM`, `DD/MM/YYYY`, `DD-MM-YY` 等。 +- 只有天和时间: `DD`, `DD hh`, `DD hh:mm`。这种情况下 `YYYY-MM` 默认为 `2000-01`。 +- 包含时间日期以及时区信息: `YYYY-MM-DD hh:mm:ss ±h:mm`等。例如: `2020-12-12 17:36:00 -5:00`。 + +对于所有的格式来说,这个函数通过全称或者第一个三个字符的月份名称来解析月份,比如:`24/DEC/18`, `24-Dec-18`, `01-September-2018`。 + +**返回值** + +- `DateTime`类型数据。 + +**例子** + +查询: + +``` sql +SELECT parseDateTimeBestEffort('12/12/2020 12:12:57') +AS parseDateTimeBestEffort; +``` + +结果: + +``` text +┌─parseDateTimeBestEffort─┐ +│ 2020-12-12 12:12:57 │ +└─────────────────────────┘ +``` + +查询: + +``` sql +SELECT parseDateTimeBestEffort('Sat, 18 Aug 2018 07:22:16 GMT', 'Europe/Moscow') +AS parseDateTimeBestEffort +``` + +结果: + +``` text +┌─parseDateTimeBestEffort─┐ +│ 2018-08-18 10:22:16 │ +└─────────────────────────┘ +``` + +查询: + +``` sql +SELECT parseDateTimeBestEffort('1284101485') +AS parseDateTimeBestEffort +``` + +结果: + +``` text +┌─parseDateTimeBestEffort─┐ +│ 2015-07-07 12:04:41 │ +└─────────────────────────┘ +``` + +查询: + +``` sql +SELECT parseDateTimeBestEffort('2018-12-12 10:12:12') +AS parseDateTimeBestEffort +``` + +结果: + +``` text +┌─parseDateTimeBestEffort─┐ +│ 2018-12-12 10:12:12 │ +└─────────────────────────┘ +``` + +查询: + +``` sql +SELECT parseDateTimeBestEffort('10 20:19') +``` + +结果: + +``` text +┌─parseDateTimeBestEffort('10 20:19')─┐ +│ 2000-01-10 20:19:00 │ +└─────────────────────────────────────┘ +``` + +**除此之外** + +- [ISO 8601 announcement by @xkcd](https://xkcd.com/1179/) +- [RFC 1123](https://tools.ietf.org/html/rfc1123) +- [toDate](#todate) +- [toDateTime](#todatetime) + +## parseDateTimeBestEffortOrNull {#parsedatetimebesteffortornull} + +这个函数和[parseDateTimeBestEffort](#parsedatetimebesteffort)基本一致,除了无法解析返回结果为`NULL`。 + +## parseDateTimeBestEffortOrZero {#parsedatetimebesteffortorzero} + +这个函数和[parseDateTimeBestEffort](#parsedatetimebesteffort)基本一致,除了无法解析返回结果为`0`。 + +## toLowCardinality {#tolowcardinality} + +把输入值转换为[LowCardianlity](../data-types/lowcardinality.md)的相同类型的数据。 + +如果要把`LowCardinality`类型的数据转换为其他类型,使用[CAST](#type_conversion_function-cast)函数。比如:`CAST(x as String)`。 + +**语法** + +```sql +toLowCardinality(expr) +``` + +**参数** + +- `expr` — [表达式](../syntax.md#syntax-expressions)为[支持的数据类型](../data-types/index.md#data_types)的一种。 + + +**返回值** + +- `expr`的结果。 + +类型: `LowCardinality(expr_result_type)` + +**例子** + +查询: + +```sql +SELECT toLowCardinality('1') +``` + +结果: + +```text +┌─toLowCardinality('1')─┐ +│ 1 │ +└───────────────────────┘ +``` -与[parsedatetimebestefort](#type_conversion_functions-parsedatetimebesteffort)相同,但它遇到无法处理的日期格式时返回零Date或零DateTime。 + +## toUnixTimestamp64Milli +## toUnixTimestamp64Micro +## toUnixTimestamp64Nano + +把一个`DateTime64`类型的数据转换为`Int64`类型的数据,结果包含固定亚秒的精度。输入的值是变大还是变低依赖于输入的精度。需要注意的是输出的值是一个UTC的时间戳, 不是同一个时区的`DateTime64`值。 + +**语法** + +``` sql +toUnixTimestamp64Milli(value) +``` + +**参数** + +- `value` — 任何精度的DateTime64类型的数据。 + +**返回值** + +- `value` `Int64`类型数据。 + +**例子** + +查询: + +``` sql +WITH toDateTime64('2019-09-16 19:20:12.345678910', 6) AS dt64 +SELECT toUnixTimestamp64Milli(dt64) +``` + +结果: + +``` text +┌─toUnixTimestamp64Milli(dt64)─┐ +│ 1568650812345 │ +└──────────────────────────────┘ +``` + +``` sql +WITH toDateTime64('2019-09-16 19:20:12.345678910', 6) AS dt64 +SELECT toUnixTimestamp64Nano(dt64) +``` + +结果: + +``` text +┌─toUnixTimestamp64Nano(dt64)─┐ +│ 1568650812345678000 │ +└─────────────────────────────┘ +``` + +## fromUnixTimestamp64Milli +## fromUnixTimestamp64Micro +## fromUnixTimestamp64Nano + +把`Int64`类型的数据转换为`DateTime64`类型的数据,结果包含固定的亚秒精度和可选的时区。 输入的值是变大还是变低依赖于输入的精度。需要注意的是输入的值是一个UTC的时间戳, 不是一个包含时区的时间戳。 + + +**语法** + +``` sql +fromUnixTimestamp64Milli(value [, ti]) +``` + +**参数** + +- `value` — `Int64`类型的数据,可以是任意精度。 +- `timezone` — `String`类型的时区 + +**返回值** + +- `value` DateTime64`类型的数据。 + +**例子** + +``` sql +WITH CAST(1234567891011, 'Int64') AS i64 +SELECT fromUnixTimestamp64Milli(i64, 'UTC') +``` + +``` text +┌─fromUnixTimestamp64Milli(i64, 'UTC')─┐ +│ 2009-02-13 23:31:31.011 │ +└──────────────────────────────────────┘ +``` [来源文章](https://clickhouse.tech/docs/en/query_language/functions/type_conversion_functions/)