This is an automated email from the ASF dual-hosted git repository. yiguolei pushed a commit to branch branch-2.1 in repository https://gitbox.apache.org/repos/asf/doris.git
commit cd0ca2b3af0c531cfa28c6e623b169cbbc3f2a6c Author: yangshijie <[email protected]> AuthorDate: Mon Jan 22 13:25:28 2024 +0800 [docs](ip function) add ipv4/v6 datatype and some ip functions' docs (#30194) --- .../ip-functions/ipv4-cidr-to-range.md | 72 ++++++++++++++++++ .../ip-functions/ipv6-cidr-to-range.md | 72 ++++++++++++++++++ .../ip-functions/is-ip-address-in-range.md | 65 +++++++++++++++++ .../sql-functions/ip-functions/is-ipv4-string.md | 80 ++++++++++++++++++++ .../sql-functions/ip-functions/is-ipv6-string.md | 80 ++++++++++++++++++++ .../ip-functions/to-ipv4-or-default.md | 65 +++++++++++++++++ .../sql-functions/ip-functions/to-ipv4-or-null.md | 65 +++++++++++++++++ .../sql-functions/ip-functions/to-ipv4.md | 60 +++++++++++++++ .../ip-functions/to-ipv6-or-default.md | 65 +++++++++++++++++ .../sql-functions/ip-functions/to-ipv6-or-null.md | 65 +++++++++++++++++ .../sql-functions/ip-functions/to-ipv6.md | 60 +++++++++++++++ .../sql-manual/sql-reference/Data-Types/IPV4.md | 85 ++++++++++++++++++++++ .../sql-manual/sql-reference/Data-Types/IPV6.md | 83 +++++++++++++++++++++ .../sql-manual/sql-reference/Data-Types/STRUCT.md | 2 +- docs/sidebars.json | 17 ++++- .../ip-functions/ipv4-cidr-to-range.md | 72 ++++++++++++++++++ .../ip-functions/ipv6-cidr-to-range.md | 72 ++++++++++++++++++ .../ip-functions/is-ip-address-in-range.md | 65 +++++++++++++++++ .../sql-functions/ip-functions/is-ipv4-string.md | 80 ++++++++++++++++++++ .../sql-functions/ip-functions/is-ipv6-string.md | 80 ++++++++++++++++++++ .../ip-functions/to-ipv4-or-default.md | 65 +++++++++++++++++ .../sql-functions/ip-functions/to-ipv4-or-null.md | 65 +++++++++++++++++ .../sql-functions/ip-functions/to-ipv4.md | 60 +++++++++++++++ .../ip-functions/to-ipv6-or-default.md | 65 +++++++++++++++++ .../sql-functions/ip-functions/to-ipv6-or-null.md | 65 +++++++++++++++++ .../sql-functions/ip-functions/to-ipv6.md | 60 +++++++++++++++ .../sql-manual/sql-reference/Data-Types/IPV4.md | 85 ++++++++++++++++++++++ .../sql-manual/sql-reference/Data-Types/IPV6.md | 83 +++++++++++++++++++++ 28 files changed, 1850 insertions(+), 3 deletions(-) diff --git a/docs/en/docs/sql-manual/sql-functions/ip-functions/ipv4-cidr-to-range.md b/docs/en/docs/sql-manual/sql-functions/ip-functions/ipv4-cidr-to-range.md new file mode 100644 index 00000000000..f5367a577f0 --- /dev/null +++ b/docs/en/docs/sql-manual/sql-functions/ip-functions/ipv4-cidr-to-range.md @@ -0,0 +1,72 @@ +--- +{ +"title": "IPV4_CIDR_TO_RANGE", +"language": "en" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## IPV4_CIDR_TO_RANGE + +<version since="dev"> + +IPV4_CIDR_TO_RANGE + +</version> + +### description + +#### Syntax + +`STRUCT<IPV4, IPV4> IPV4_CIDR_TO_RANGE(IPV4 ip_v4, INT16 cidr)` + +Receive an IPv4 and an Int16 value containing CIDR. Returns a struct that contains two IPv4 fields representing the lower range (min) and higher range (max) of the subnet, respectively. + +### notice + +`If the input parameter is NULL, return NULL, indicating invalid input` + +### example + +``` +mysql> SELECT ipv4_cidr_to_range(ipv4_string_to_num('192.168.5.2'), 16); ++-----------------------------------------------------------+ +| ipv4_cidr_to_range(ipv4_string_to_num('192.168.5.2'), 16) | ++-----------------------------------------------------------+ +| {"min": "192.168.0.0", "max": "192.168.255.255"} | ++-----------------------------------------------------------+ + +mysql> SELECT ipv4_cidr_to_range(to_ipv4('192.168.5.2'), 16); ++--------------------------------------------------+ +| ipv4_cidr_to_range(to_ipv4('192.168.5.2'), 16) | ++--------------------------------------------------+ +| {"min": "192.168.0.0", "max": "192.168.255.255"} | ++--------------------------------------------------+ + +mysql> SELECT ipv4_cidr_to_range(NULL, NULL); ++--------------------------------+ +| ipv4_cidr_to_range(NULL, NULL) | ++--------------------------------+ +| NULL | ++--------------------------------+ +``` + +### keywords + +IPV4_CIDR_TO_RANGE, IP diff --git a/docs/en/docs/sql-manual/sql-functions/ip-functions/ipv6-cidr-to-range.md b/docs/en/docs/sql-manual/sql-functions/ip-functions/ipv6-cidr-to-range.md new file mode 100644 index 00000000000..bf5c74c167d --- /dev/null +++ b/docs/en/docs/sql-manual/sql-functions/ip-functions/ipv6-cidr-to-range.md @@ -0,0 +1,72 @@ +--- +{ +"title": "IPV6_CIDR_TO_RANGE", +"language": "en" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## IPV6_CIDR_TO_RANGE + +<version since="dev"> + +IPV6_CIDR_TO_RANGE + +</version> + +### description + +#### Syntax + +`STRUCT<IPV6, IPV6> IPV6_CIDR_TO_RANGE(IPV6 ip_v6, INT16 cidr)` + +Receive an IPv6 and an Int16 value containing CIDR. Returns a struct that contains two IPv6 fields representing the lower range (min) and higher range (max) of the subnet, respectively. + +### notice + +`If the input parameter is NULL, return NULL, indicating invalid input` + +### example + +``` +mysql> SELECT ipv6_cidr_to_range(ipv6_string_to_num('2001:0db8:0000:85a3:0000:0000:ac1f:8001'), 32); ++---------------------------------------------------------------------------------------+ +| ipv6_cidr_to_range(ipv6_string_to_num('2001:0db8:0000:85a3:0000:0000:ac1f:8001'), 32) | ++---------------------------------------------------------------------------------------+ +| {"min": "2001:db8::", "max": "2001:db8:ffff:ffff:ffff:ffff:ffff:ffff"} | ++---------------------------------------------------------------------------------------+ + +mysql> SELECT ipv6_cidr_to_range(to_ipv6('2001:0db8:0000:85a3:0000:0000:ac1f:8001'), 32); ++----------------------------------------------------------------------------+ +| ipv6_cidr_to_range(to_ipv6('2001:0db8:0000:85a3:0000:0000:ac1f:8001'), 32) | ++----------------------------------------------------------------------------+ +| {"min": "2001:db8::", "max": "2001:db8:ffff:ffff:ffff:ffff:ffff:ffff"} | ++----------------------------------------------------------------------------+ + +mysql> SELECT ipv6_cidr_to_range(NULL, NULL); ++--------------------------------+ +| ipv6_cidr_to_range(NULL, NULL) | ++--------------------------------+ +| NULL | ++--------------------------------+ +``` + +### keywords + +IPV6_CIDR_TO_RANGE, IP diff --git a/docs/en/docs/sql-manual/sql-functions/ip-functions/is-ip-address-in-range.md b/docs/en/docs/sql-manual/sql-functions/ip-functions/is-ip-address-in-range.md new file mode 100644 index 00000000000..7a47537f855 --- /dev/null +++ b/docs/en/docs/sql-manual/sql-functions/ip-functions/is-ip-address-in-range.md @@ -0,0 +1,65 @@ +--- +{ +"title": "IS_IP_ADDRESS_IN_RANGE", +"language": "en" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## IS_IP_ADDRESS_IN_RANGE + +<version since="dev"> + +IS_IP_ADDRESS_IN_RANGE + +</version> + +### description + +#### Syntax + +`BOOLEAN IS_IP_ADDRESS_IN_RANGE(STRING ip_str, STRING cidr_prefix)` + +Determine whether the IP (IPv4 or IPv6) address is included in the network represented by CIDR notation. If yes, return true; otherwise, return false. + +### notice + +`ip_str and cidr_prefix both cannot be NULL` + +### example + +``` +mysql> SELECT is_ip_address_in_range('127.0.0.1', '127.0.0.0/8'); ++----------------------------------------------------+ +| is_ip_address_in_range('127.0.0.1', '127.0.0.0/8') | ++----------------------------------------------------+ +| 1 | ++----------------------------------------------------+ + +mysql> SELECT is_ip_address_in_range('::ffff:192.168.0.1', '::ffff:192.168.0.4/128'); ++------------------------------------------------------------------------+ +| is_ip_address_in_range('::ffff:192.168.0.1', '::ffff:192.168.0.4/128') | ++------------------------------------------------------------------------+ +| 0 | ++------------------------------------------------------------------------+ +``` + +### keywords + +IS_IP_ADDRESS_IN_RANGE, IP diff --git a/docs/en/docs/sql-manual/sql-functions/ip-functions/is-ipv4-string.md b/docs/en/docs/sql-manual/sql-functions/ip-functions/is-ipv4-string.md new file mode 100644 index 00000000000..9aca93afc0a --- /dev/null +++ b/docs/en/docs/sql-manual/sql-functions/ip-functions/is-ipv4-string.md @@ -0,0 +1,80 @@ +--- +{ +"title": "IS_IPV4_STRING", +"language": "en" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## IS_IPV4_STRING + +<version since="dev"> + +IS_IPV4_STRING + +</version> + +### description + +#### Syntax + +`BOOLEAN IS_IPV4_STRING(STRING ipv4_str)` + +Receive an IPv4 address in the form of a string as a parameter. If it is a correctly formatted and valid IPv4 address, return true; On the contrary, return false. + +### notice + +`If the input parameter is NULL, return NULL, indicating invalid input` + +### example + +``` +mysql> select is_ipv4_string(NULL); ++----------------------+ +| is_ipv4_string(NULL) | ++----------------------+ +| NULL | ++----------------------+ + +mysql> CREATE TABLE `test_is_ipv4_string` ( + `id` int, + `ip_v4` string + ) ENGINE=OLAP + DISTRIBUTED BY HASH(`id`) BUCKETS 4 + PROPERTIES ( + "replication_allocation" = "tag.location.default: 1" + ); + +mysql> insert into test_is_ipv4_string values(0, NULL), (1, '0.0.0.'), (2, ''), (3, '.'), (4, '255.255.255.255'); + +mysql> select id, is_ipv4_string(ip_v4) from test_is_ipv4_string order by id; ++------+-----------------------+ +| id | is_ipv4_string(ip_v4) | ++------+-----------------------+ +| 0 | NULL | +| 1 | 0 | +| 2 | 0 | +| 3 | 0 | +| 4 | 1 | ++------+-----------------------+ +``` + +### keywords + +IS_IPV4_STRING, IP diff --git a/docs/en/docs/sql-manual/sql-functions/ip-functions/is-ipv6-string.md b/docs/en/docs/sql-manual/sql-functions/ip-functions/is-ipv6-string.md new file mode 100644 index 00000000000..6f3731e2618 --- /dev/null +++ b/docs/en/docs/sql-manual/sql-functions/ip-functions/is-ipv6-string.md @@ -0,0 +1,80 @@ +--- +{ +"title": "IS_IPV6_STRING", +"language": "en" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## IS_IPV6_STRING + +<version since="dev"> + +IS_IPV6_STRING + +</version> + +### description + +#### Syntax + +`BOOLEAN IS_IPV6_STRING(STRING ipv6_str)` + +Receive an IPv6 address in the form of a string as a parameter, and return true if it is a properly formatted and valid IPv6 address; On the contrary, return false. + +### notice + +`If the input parameter is NULL, return NULL, indicating invalid input` + +### example + +``` +mysql> select is_ipv6_string(NULL); ++----------------------+ +| is_ipv6_string(NULL) | ++----------------------+ +| NULL | ++----------------------+ + +mysql> CREATE TABLE `test_is_ipv6_string` ( + `id` int, + `ip_v6` string + ) ENGINE=OLAP + DISTRIBUTED BY HASH(`id`) BUCKETS 4 + PROPERTIES ( + "replication_allocation" = "tag.location.default: 1" + ); + +mysql> insert into test_is_ipv6_string values(0, NULL), (1, '::'), (2, ''), (3, '2001:1b70:a1:610::b102:2'), (4, 'ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffffg'); + +mysql> select id, is_ipv6_string(ip_v6) from test_is_ipv6_string order by id; ++------+-----------------------+ +| id | is_ipv6_string(ip_v6) | ++------+-----------------------+ +| 0 | NULL | +| 1 | 1 | +| 2 | 0 | +| 3 | 1 | +| 4 | 0 | ++------+-----------------------+ +``` + +### keywords + +IS_IPV6_STRING, IP diff --git a/docs/en/docs/sql-manual/sql-functions/ip-functions/to-ipv4-or-default.md b/docs/en/docs/sql-manual/sql-functions/ip-functions/to-ipv4-or-default.md new file mode 100644 index 00000000000..d5770906b88 --- /dev/null +++ b/docs/en/docs/sql-manual/sql-functions/ip-functions/to-ipv4-or-default.md @@ -0,0 +1,65 @@ +--- +{ +"title": "TO_IPV4_OR_DEFAULT", +"language": "en" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## TO_IPV4_OR_DEFAULT + +<version since="dev"> + +TO_IPV4_OR_DEFAULT + +</version> + +### description + +#### Syntax + +`IPV4 TO_IPV4_OR_DEFAULT(STRING ipv4_str)` + +Same as to_ipv4, but if the IPv4 address has an invalid format, it returns 0.0.0.0 (0 as IPv4). + +### notice + +`If input is NULL, return 0.0.0.0 (0 as IPv4).` + +### example + +``` +mysql> select to_ipv4_or_default('.'); ++-------------------------+ +| to_ipv4_or_default('.') | ++-------------------------+ +| 0.0.0.0 | ++-------------------------+ + +mysql> select to_ipv4_or_default(NULL); ++--------------------------+ +| to_ipv4_or_default(NULL) | ++--------------------------+ +| 0.0.0.0 | ++--------------------------+ +``` + +### keywords + +TO_IPV4_OR_DEFAULT, IP diff --git a/docs/en/docs/sql-manual/sql-functions/ip-functions/to-ipv4-or-null.md b/docs/en/docs/sql-manual/sql-functions/ip-functions/to-ipv4-or-null.md new file mode 100644 index 00000000000..35377b233a7 --- /dev/null +++ b/docs/en/docs/sql-manual/sql-functions/ip-functions/to-ipv4-or-null.md @@ -0,0 +1,65 @@ +--- +{ +"title": "TO_IPV4_OR_NULL", +"language": "en" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## TO_IPV4_OR_NULL + +<version since="dev"> + +TO_IPV4_OR_NULL + +</version> + +### description + +#### Syntax + +`IPV4 TO_IPV4_OR_NULL(STRING ipv4_str)` + +Same as to_ipv4, but if the IPv4 address has an invalid format, it returns NULL. + +### notice + +`If input is NULL, return NULL.` + +### example + +``` +mysql> select to_ipv4_or_null('.'); ++----------------------+ +| to_ipv4_or_null('.') | ++----------------------+ +| NULL | ++----------------------+ + +mysql> select to_ipv4_or_null(NULL); ++-----------------------+ +| to_ipv4_or_null(NULL) | ++-----------------------+ +| NULL | ++-----------------------+ +``` + +### keywords + +TO_IPV4_OR_NULL, IP diff --git a/docs/en/docs/sql-manual/sql-functions/ip-functions/to-ipv4.md b/docs/en/docs/sql-manual/sql-functions/ip-functions/to-ipv4.md new file mode 100644 index 00000000000..24747ae0ed0 --- /dev/null +++ b/docs/en/docs/sql-manual/sql-functions/ip-functions/to-ipv4.md @@ -0,0 +1,60 @@ +--- +{ +"title": "TO_IPV4", +"language": "en" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## TO_IPV4 + +<version since="dev"> + +TO_IPV4 + +</version> + +### description + +#### Syntax + +`IPV4 TO_IPV4(STRING ipv4_str)` + +This function like ipv4_string_to_num that takes a string form of IPv4 address and returns value of IPv4 type, +which is binary equal to value returned by ipv4_string_to_num. +If the IPv4 address has an invalid format, throw an exception. + +### notice + +`Input cannot be NULL. If it is NULL, an exception will be thrown.` + +### example + +``` +mysql> select to_ipv4('255.255.255.255'); ++----------------------------+ +| to_ipv4('255.255.255.255') | ++----------------------------+ +| 255.255.255.255 | ++----------------------------+ +``` + +### keywords + +TO_IPV4, IP diff --git a/docs/en/docs/sql-manual/sql-functions/ip-functions/to-ipv6-or-default.md b/docs/en/docs/sql-manual/sql-functions/ip-functions/to-ipv6-or-default.md new file mode 100644 index 00000000000..c0cc118e9bb --- /dev/null +++ b/docs/en/docs/sql-manual/sql-functions/ip-functions/to-ipv6-or-default.md @@ -0,0 +1,65 @@ +--- +{ +"title": "TO_IPV6_OR_DEFAULT", +"language": "en" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## TO_IPV6_OR_DEFAULT + +<version since="dev"> + +TO_IPV6_OR_DEFAULT + +</version> + +### description + +#### Syntax + +`IPV6 TO_IPV6_OR_DEFAULT(STRING ipv6_str)` + +Same as to_ipv6, but if the IPv6 address has an invalid format, it returns :: (0 as IPv6). + +### notice + +`If input is NULL, return :: (0 as IPv6).` + +### example + +``` +mysql> select to_ipv6_or_default('.'); ++-------------------------+ +| to_ipv6_or_default('.') | ++-------------------------+ +| :: | ++-------------------------+ + +mysql> select to_ipv6_or_default(NULL); ++--------------------------+ +| to_ipv6_or_default(NULL) | ++--------------------------+ +| :: | ++--------------------------+ +``` + +### keywords + +TO_IPV6_OR_DEFAULT, IP diff --git a/docs/en/docs/sql-manual/sql-functions/ip-functions/to-ipv6-or-null.md b/docs/en/docs/sql-manual/sql-functions/ip-functions/to-ipv6-or-null.md new file mode 100644 index 00000000000..863cb383973 --- /dev/null +++ b/docs/en/docs/sql-manual/sql-functions/ip-functions/to-ipv6-or-null.md @@ -0,0 +1,65 @@ +--- +{ +"title": "TO_IPV6_OR_NULL", +"language": "en" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## TO_IPV6_OR_NULL + +<version since="dev"> + +TO_IPV6_OR_NULL + +</version> + +### description + +#### Syntax + +`IPV6 TO_IPV6_OR_NULL(STRING ipv6_str)` + +Same as to_ipv6, but if the IPv6 address has an invalid format, it returns NULL. + +### notice + +`If input is NULL, return NULL.` + +### example + +``` +mysql> select to_ipv6_or_null('.'); ++----------------------+ +| to_ipv6_or_null('.') | ++----------------------+ +| NULL | ++----------------------+ + +mysql> select to_ipv6_or_null(NULL); ++-----------------------+ +| to_ipv6_or_null(NULL) | ++-----------------------+ +| NULL | ++-----------------------+ +``` + +### keywords + +TO_IPV6_OR_NULL, IP diff --git a/docs/en/docs/sql-manual/sql-functions/ip-functions/to-ipv6.md b/docs/en/docs/sql-manual/sql-functions/ip-functions/to-ipv6.md new file mode 100644 index 00000000000..aad7d42b94f --- /dev/null +++ b/docs/en/docs/sql-manual/sql-functions/ip-functions/to-ipv6.md @@ -0,0 +1,60 @@ +--- +{ +"title": "TO_IPV6", +"language": "en" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## TO_IPV6 + +<version since="dev"> + +TO_IPV6 + +</version> + +### description + +#### Syntax + +`IPV6 TO_IPV6(STRING ipv6_str)` + +Convert a string form of IPv6 address to IPv6 type. +If the IPv6 address has an invalid format, throw an exception. +Similar to ipv6_string_to_num function, which converts IPv6 address to binary format. + +### notice + +`Input cannot be NULL. If it is NULL, an exception will be thrown.` + +### example + +``` +mysql> select to_ipv6('::'); ++---------------+ +| to_ipv6('::') | ++---------------+ +| :: | ++---------------+ +``` + +### keywords + +TO_IPV6, IP diff --git a/docs/en/docs/sql-manual/sql-reference/Data-Types/IPV4.md b/docs/en/docs/sql-manual/sql-reference/Data-Types/IPV4.md new file mode 100644 index 00000000000..07ab836e4eb --- /dev/null +++ b/docs/en/docs/sql-manual/sql-reference/Data-Types/IPV4.md @@ -0,0 +1,85 @@ +--- +{ + "title": "IPV4", + "language": "en" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## IPV4 + +<version since="dev"> + +IPV4 + +</version> + +### description + +IPV4 +IPv4 type, stored in the form of UInt32 in 4 bytes, used to represent IPv4 addresses. +The range of values is ['0.0.0.0', '255.255.255.255']. + +`Inputs that exceed the value range or have invalid format will return NULL` + +### example + +Create table example: + +``` +CREATE TABLE ipv4_test ( + `id` int, + `ip_v4` ipv4 +) ENGINE=OLAP +DISTRIBUTED BY HASH(`id`) BUCKETS 4 +PROPERTIES ( +"replication_allocation" = "tag.location.default: 1" +); +``` + +Insert data example: + +``` +insert into ipv4_test values(1, '0.0.0.0'); +insert into ipv4_test values(2, '127.0.0.1'); +insert into ipv4_test values(3, '59.50.185.152'); +insert into ipv4_test values(4, '255.255.255.255'); +insert into ipv4_test values(5, '255.255.255.256'); // invalid data +``` + +Select data example: + +``` +mysql> select * from ipv4_test order by id; ++------+-----------------+ +| id | ip_v4 | ++------+-----------------+ +| 1 | 0.0.0.0 | +| 2 | 127.0.0.1 | +| 3 | 59.50.185.152 | +| 4 | 255.255.255.255 | +| 5 | NULL | ++------+-----------------+ +``` + +### keywords + +IPV4 diff --git a/docs/en/docs/sql-manual/sql-reference/Data-Types/IPV6.md b/docs/en/docs/sql-manual/sql-reference/Data-Types/IPV6.md new file mode 100644 index 00000000000..dcf46813240 --- /dev/null +++ b/docs/en/docs/sql-manual/sql-reference/Data-Types/IPV6.md @@ -0,0 +1,83 @@ +--- +{ + "title": "IPV6", + "language": "en" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## IPV6 + +<version since="dev"> + +IPV6 + +</version> + +### description + +IPV6 +IPv6 type, stored in Int128 format in 16 bytes, used to represent IPv6 addresses. +The range of values is ['::', 'ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff']. + +`Inputs that exceed the value range or have invalid format will return NULL` + +### example + +Create table example: + +``` +CREATE TABLE ipv6_test ( + `id` int, + `ip_v6` ipv6 +) ENGINE=OLAP +DISTRIBUTED BY HASH(`id`) BUCKETS 4 +PROPERTIES ( +"replication_allocation" = "tag.location.default: 1" +); +``` + +Insert data example: + +``` +insert into ipv6_test values(1, '::'); +insert into ipv6_test values(2, '2001:16a0:2:200a::2'); +insert into ipv6_test values(3, 'ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff'); +insert into ipv6_test values(4, 'ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffffg'); // invalid data +``` + +Select data example: + +``` +mysql> select * from ipv6_test order by id; ++------+-----------------------------------------+ +| id | ip_v6 | ++------+-----------------------------------------+ +| 1 | :: | +| 2 | 2001:16a0:2:200a::2 | +| 3 | ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff | +| 4 | NULL | ++------+-----------------------------------------+ +``` + +### keywords + +IPV6 diff --git a/docs/en/docs/sql-manual/sql-reference/Data-Types/STRUCT.md b/docs/en/docs/sql-manual/sql-reference/Data-Types/STRUCT.md index abab4148889..ba0faaf6375 100644 --- a/docs/en/docs/sql-manual/sql-reference/Data-Types/STRUCT.md +++ b/docs/en/docs/sql-manual/sql-reference/Data-Types/STRUCT.md @@ -62,7 +62,7 @@ DATEV2, DATETIME, DATETIMEV2, CHAR, VARCHAR, STRING We have a todo list for future version: ``` -TODO:支持嵌套 STRUCT 或其他的复杂类型 +TODO: Supports nested Struct or other complex types ``` ### example diff --git a/docs/sidebars.json b/docs/sidebars.json index bda6b8da310..cc8e5cfe39d 100644 --- a/docs/sidebars.json +++ b/docs/sidebars.json @@ -816,7 +816,18 @@ "sql-manual/sql-functions/ip-functions/ipv6-string-to-num-or-default", "sql-manual/sql-functions/ip-functions/ipv6-string-to-num-or-null", "sql-manual/sql-functions/ip-functions/is-ipv4-compat", - "sql-manual/sql-functions/ip-functions/is-ipv4-mapped" + "sql-manual/sql-functions/ip-functions/is-ipv4-mapped", + "sql-manual/sql-functions/ip-functions/ipv4-cidr-to-range", + "sql-manual/sql-functions/ip-functions/ipv6-cidr-to-range", + "sql-manual/sql-functions/ip-functions/is-ip-address-in-range", + "sql-manual/sql-functions/ip-functions/is-ipv4-string", + "sql-manual/sql-functions/ip-functions/is-ipv6-string", + "sql-manual/sql-functions/ip-functions/to-ipv4", + "sql-manual/sql-functions/ip-functions/to-ipv4-or-default", + "sql-manual/sql-functions/ip-functions/to-ipv4-or-null", + "sql-manual/sql-functions/ip-functions/to-ipv6", + "sql-manual/sql-functions/ip-functions/to-ipv6-or-default", + "sql-manual/sql-functions/ip-functions/to-ipv6-or-null" ] }, { @@ -926,7 +937,9 @@ "sql-manual/sql-reference/Data-Types/STRUCT", "sql-manual/sql-reference/Data-Types/JSON", "sql-manual/sql-reference/Data-Types/AGG_STATE", - "sql-manual/sql-reference/Data-Types/VARIANT" + "sql-manual/sql-reference/Data-Types/VARIANT", + "sql-manual/sql-reference/Data-Types/IPV4", + "sql-manual/sql-reference/Data-Types/IPV6" ] }, { diff --git a/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/ipv4-cidr-to-range.md b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/ipv4-cidr-to-range.md new file mode 100644 index 00000000000..ca1803db630 --- /dev/null +++ b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/ipv4-cidr-to-range.md @@ -0,0 +1,72 @@ +--- +{ +"title": "IPV4_CIDR_TO_RANGE", +"language": "zh-CN" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## IPV4_CIDR_TO_RANGE + +<version since="dev"> + +IPV4_CIDR_TO_RANGE + +</version> + +### description + +#### Syntax + +`STRUCT<IPV4, IPV4> IPV4_CIDR_TO_RANGE(IPV4 ip_v4, INT16 cidr)` + +接收一个IPv4和一个包含CIDR的Int16值。返回一个结构体，其中包含两个IPv4字段分别表示子网的较低范围（min）和较高范围（max）。 + +### notice + +`如果入参为NULL，则返回NULL，表示无效输入` + +### example + +``` +mysql> SELECT ipv4_cidr_to_range(ipv4_string_to_num('192.168.5.2'), 16); ++------------------------------------------------------------+ +| ipv4_cidr_to_range(ipv4_string_to_num('192.168.5.2'), 16) | ++------------------------------------------------------------+ +| {"min": "192.168.0.0", "max": "192.168.255.255"} | ++------------------------------------------------------------+ + +mysql> SELECT ipv4_cidr_to_range(to_ipv4('192.168.5.2'), 16); ++--------------------------------------------------+ +| ipv4_cidr_to_range(to_ipv4('192.168.5.2'), 16) | ++--------------------------------------------------+ +| {"min": "192.168.0.0", "max": "192.168.255.255"} | ++--------------------------------------------------+ + +mysql> SELECT ipv4_cidr_to_range(NULL, NULL); ++--------------------------------+ +| ipv4_cidr_to_range(NULL, NULL) | ++--------------------------------+ +| NULL | ++--------------------------------+ +``` + +### keywords + +IPV4_CIDR_TO_RANGE, IP diff --git a/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/ipv6-cidr-to-range.md b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/ipv6-cidr-to-range.md new file mode 100644 index 00000000000..a88fa5651e1 --- /dev/null +++ b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/ipv6-cidr-to-range.md @@ -0,0 +1,72 @@ +--- +{ +"title": "IPV6_CIDR_TO_RANGE", +"language": "zh-CN" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## IPV6_CIDR_TO_RANGE + +<version since="dev"> + +IPV6_CIDR_TO_RANGE + +</version> + +### description + +#### Syntax + +`STRUCT<IPV6, IPV6> IPV6_CIDR_TO_RANGE(IPV6 ip_v6, INT16 cidr)` + +接收一个IPv6和一个包含CIDR的Int16值。返回一个结构体，其中包含两个IPv6字段分别表示子网的较低范围（min）和较高范围（max）。 + +### notice + +`如果入参为NULL，则返回NULL，表示无效输入` + +### example + +``` +mysql> SELECT ipv6_cidr_to_range(ipv6_string_to_num('2001:0db8:0000:85a3:0000:0000:ac1f:8001'), 32); ++---------------------------------------------------------------------------------------+ +| ipv6_cidr_to_range(ipv6_string_to_num('2001:0db8:0000:85a3:0000:0000:ac1f:8001'), 32) | ++---------------------------------------------------------------------------------------+ +| {"min": "2001:db8::", "max": "2001:db8:ffff:ffff:ffff:ffff:ffff:ffff"} | ++---------------------------------------------------------------------------------------+ + +mysql> SELECT ipv6_cidr_to_range(to_ipv6('2001:0db8:0000:85a3:0000:0000:ac1f:8001'), 32); ++----------------------------------------------------------------------------+ +| ipv6_cidr_to_range(to_ipv6('2001:0db8:0000:85a3:0000:0000:ac1f:8001'), 32) | ++----------------------------------------------------------------------------+ +| {"min": "2001:db8::", "max": "2001:db8:ffff:ffff:ffff:ffff:ffff:ffff"} | ++----------------------------------------------------------------------------+ + +mysql> SELECT ipv6_cidr_to_range(NULL, NULL); ++--------------------------------+ +| ipv6_cidr_to_range(NULL, NULL) | ++--------------------------------+ +| NULL | ++--------------------------------+ +``` + +### keywords + +IPV6_CIDR_TO_RANGE, IP diff --git a/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/is-ip-address-in-range.md b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/is-ip-address-in-range.md new file mode 100644 index 00000000000..16c8d31a9b3 --- /dev/null +++ b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/is-ip-address-in-range.md @@ -0,0 +1,65 @@ +--- +{ +"title": "IS_IP_ADDRESS_IN_RANGE", +"language": "zh-CN" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## IS_IP_ADDRESS_IN_RANGE + +<version since="dev"> + +IS_IP_ADDRESS_IN_RANGE + +</version> + +### description + +#### Syntax + +`BOOLEAN IS_IP_ADDRESS_IN_RANGE(STRING ip_str, STRING cidr_prefix)` + +判断IP（IPv4或IPv6）地址是否包含在以CIDR表示法表示的网络中。如果是，则返回true，否则返回false。 + +### notice + +`入参ip_str和cidr_prefix均不能为NULL` + +### example + +``` +mysql> SELECT is_ip_address_in_range('127.0.0.1', '127.0.0.0/8'); ++----------------------------------------------------+ +| is_ip_address_in_range('127.0.0.1', '127.0.0.0/8') | ++----------------------------------------------------+ +| 1 | ++----------------------------------------------------+ + +mysql> SELECT is_ip_address_in_range('::ffff:192.168.0.1', '::ffff:192.168.0.4/128'); ++------------------------------------------------------------------------+ +| is_ip_address_in_range('::ffff:192.168.0.1', '::ffff:192.168.0.4/128') | ++------------------------------------------------------------------------+ +| 0 | ++------------------------------------------------------------------------+ +``` + +### keywords + +IS_IP_ADDRESS_IN_RANGE, IP diff --git a/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/is-ipv4-string.md b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/is-ipv4-string.md new file mode 100644 index 00000000000..8cd691ab878 --- /dev/null +++ b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/is-ipv4-string.md @@ -0,0 +1,80 @@ +--- +{ +"title": "IS_IPV4_STRING", +"language": "zh-CN" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## IS_IPV4_STRING + +<version since="dev"> + +IS_IPV4_STRING + +</version> + +### description + +#### Syntax + +`BOOLEAN IS_IPV4_STRING(STRING ipv4_str)` + +接收一个表示形式为字符串的IPv4地址作为参数，如果为格式正确且合法的IPv4地址，返回true；反之，返回false。 + +### notice + +`如果入参为NULL，则返回NULL，表示无效输入` + +### example + +``` +mysql> select is_ipv4_string(NULL); ++----------------------+ +| is_ipv4_string(NULL) | ++----------------------+ +| NULL | ++----------------------+ + +mysql> CREATE TABLE `test_is_ipv4_string` ( + `id` int, + `ip_v4` string + ) ENGINE=OLAP + DISTRIBUTED BY HASH(`id`) BUCKETS 4 + PROPERTIES ( + "replication_allocation" = "tag.location.default: 1" + ); + +mysql> insert into test_is_ipv4_string values(0, NULL), (1, '0.0.0.'), (2, ''), (3, '.'), (4, '255.255.255.255'); + +mysql> select id, is_ipv4_string(ip_v4) from test_is_ipv4_string order by id; ++------+-----------------------+ +| id | is_ipv4_string(ip_v4) | ++------+-----------------------+ +| 0 | NULL | +| 1 | 0 | +| 2 | 0 | +| 3 | 0 | +| 4 | 1 | ++------+-----------------------+ +``` + +### keywords + +IS_IPV4_STRING, IP diff --git a/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/is-ipv6-string.md b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/is-ipv6-string.md new file mode 100644 index 00000000000..5aa9ca6087e --- /dev/null +++ b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/is-ipv6-string.md @@ -0,0 +1,80 @@ +--- +{ +"title": "IS_IPV6_STRING", +"language": "zh-CN" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## IS_IPV6_STRING + +<version since="dev"> + +IS_IPV6_STRING + +</version> + +### description + +#### Syntax + +`BOOLEAN IS_IPV6_STRING(STRING ipv6_str)` + +接收一个表示形式为字符串的IPv6地址作为参数，如果为格式正确且合法的IPv6地址，返回true；反之，返回false。 + +### notice + +`如果入参为NULL，则返回NULL，表示无效输入` + +### example + +``` +mysql> select is_ipv6_string(NULL); ++----------------------+ +| is_ipv6_string(NULL) | ++----------------------+ +| NULL | ++----------------------+ + +mysql> CREATE TABLE `test_is_ipv6_string` ( + `id` int, + `ip_v6` string + ) ENGINE=OLAP + DISTRIBUTED BY HASH(`id`) BUCKETS 4 + PROPERTIES ( + "replication_allocation" = "tag.location.default: 1" + ); + +mysql> insert into test_is_ipv6_string values(0, NULL), (1, '::'), (2, ''), (3, '2001:1b70:a1:610::b102:2'), (4, 'ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffffg'); + +mysql> select id, is_ipv6_string(ip_v6) from test_is_ipv6_string order by id; ++------+-----------------------+ +| id | is_ipv6_string(ip_v6) | ++------+-----------------------+ +| 0 | NULL | +| 1 | 1 | +| 2 | 0 | +| 3 | 1 | +| 4 | 0 | ++------+-----------------------+ +``` + +### keywords + +IS_IPV6_STRING, IP diff --git a/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/to-ipv4-or-default.md b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/to-ipv4-or-default.md new file mode 100644 index 00000000000..f33cf4ea61a --- /dev/null +++ b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/to-ipv4-or-default.md @@ -0,0 +1,65 @@ +--- +{ +"title": "TO_IPV4_OR_DEFAULT", +"language": "zh-CN" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## TO_IPV4_OR_DEFAULT + +<version since="dev"> + +TO_IPV4_OR_DEFAULT + +</version> + +### description + +#### Syntax + +`IPV4 TO_IPV4_OR_DEFAULT(STRING ipv4_str)` + +与to_ipv4函数类似，但如果IPv4地址的格式非法，则返回0.0.0.0。 + +### notice + +`入参ipv4_str如果为NULL，则返回0.0.0.0。` + +### example + +``` +mysql> select to_ipv4_or_default('.'); ++-------------------------+ +| to_ipv4_or_default('.') | ++-------------------------+ +| 0.0.0.0 | ++-------------------------+ + +mysql> select to_ipv4_or_default(NULL); ++--------------------------+ +| to_ipv4_or_default(NULL) | ++--------------------------+ +| 0.0.0.0 | ++--------------------------+ +``` + +### keywords + +TO_IPV4_OR_DEFAULT, IP diff --git a/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/to-ipv4-or-null.md b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/to-ipv4-or-null.md new file mode 100644 index 00000000000..9ffa174e0bb --- /dev/null +++ b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/to-ipv4-or-null.md @@ -0,0 +1,65 @@ +--- +{ +"title": "TO_IPV4_OR_NULL", +"language": "zh-CN" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## TO_IPV4_OR_NULL + +<version since="dev"> + +TO_IPV4_OR_NULL + +</version> + +### description + +#### Syntax + +`IPV4 TO_IPV4_OR_NULL(STRING ipv4_str)` + +与to_ipv4函数类似，但如果IPv4地址的格式非法，则返回NULL。 + +### notice + +`入参ipv4_str如果为NULL，则返回NULL。` + +### example + +``` +mysql> select to_ipv4_or_null('.'); ++----------------------+ +| to_ipv4_or_null('.') | ++----------------------+ +| NULL | ++----------------------+ + +mysql> select to_ipv4_or_null(NULL); ++-----------------------+ +| to_ipv4_or_null(NULL) | ++-----------------------+ +| NULL | ++-----------------------+ +``` + +### keywords + +TO_IPV4_OR_NULL, IP diff --git a/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/to-ipv4.md b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/to-ipv4.md new file mode 100644 index 00000000000..f484da2905c --- /dev/null +++ b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/to-ipv4.md @@ -0,0 +1,60 @@ +--- +{ +"title": "TO_IPV4", +"language": "zh-CN" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## TO_IPV4 + +<version since="dev"> + +TO_IPV4 + +</version> + +### description + +#### Syntax + +`IPV4 TO_IPV4(STRING ipv4_str)` + +该函数类似ipv4_string_to_num，输入IPv4地址的字符串形式，并返回IPv4类型的值。 +该值的二进制形式等于ipv4_string_to_num函数返回值的二进制形式。 +如果IPv4地址为非法格式，则抛出异常。 + +### notice + +`入参ipv4_str不能为NULL，若为NULL，则抛出异常。` + +### example + +``` +mysql> select to_ipv4('255.255.255.255'); ++----------------------------+ +| to_ipv4('255.255.255.255') | ++----------------------------+ +| 255.255.255.255 | ++----------------------------+ +``` + +### keywords + +TO_IPV4, IP diff --git a/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/to-ipv6-or-default.md b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/to-ipv6-or-default.md new file mode 100644 index 00000000000..679fbf1e85b --- /dev/null +++ b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/to-ipv6-or-default.md @@ -0,0 +1,65 @@ +--- +{ +"title": "TO_IPV6_OR_DEFAULT", +"language": "zh-CN" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## TO_IPV6_OR_DEFAULT + +<version since="dev"> + +TO_IPV6_OR_DEFAULT + +</version> + +### description + +#### Syntax + +`IPV6 TO_IPV6_OR_DEFAULT(STRING ipv6_str)` + +与to_ipv6函数类似，但如果IPv6地址的格式非法，则返回::。 + +### notice + +`入参ipv6_str如果为NULL，则返回::。` + +### example + +``` +mysql> select to_ipv6_or_default('.'); ++-------------------------+ +| to_ipv6_or_default('.') | ++-------------------------+ +| :: | ++-------------------------+ + +mysql> select to_ipv6_or_default(NULL); ++--------------------------+ +| to_ipv6_or_default(NULL) | ++--------------------------+ +| :: | ++--------------------------+ +``` + +### keywords + +TO_IPV6_OR_DEFAULT, IP diff --git a/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/to-ipv6-or-null.md b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/to-ipv6-or-null.md new file mode 100644 index 00000000000..f09fd1cf691 --- /dev/null +++ b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/to-ipv6-or-null.md @@ -0,0 +1,65 @@ +--- +{ +"title": "TO_IPV6_OR_NULL", +"language": "zh-CN" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## TO_IPV6_OR_NULL + +<version since="dev"> + +TO_IPV6_OR_NULL + +</version> + +### description + +#### Syntax + +`IPV6 TO_IPV6_OR_NULL(STRING ipv6_str)` + +与to_ipv6函数类似，但如果IPv6地址的格式非法，则返回NULL。 + +### notice + +`入参ipv6_str如果为NULL，则返回NULL。` + +### example + +``` +mysql> select to_ipv6_or_null('.'); ++----------------------+ +| to_ipv6_or_null('.') | ++----------------------+ +| NULL | ++----------------------+ + +mysql> select to_ipv6_or_null(NULL); ++-----------------------+ +| to_ipv6_or_null(NULL) | ++-----------------------+ +| NULL | ++-----------------------+ +``` + +### keywords + +TO_IPV6_OR_NULL, IP diff --git a/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/to-ipv6.md b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/to-ipv6.md new file mode 100644 index 00000000000..ac7297204d2 --- /dev/null +++ b/docs/zh-CN/docs/sql-manual/sql-functions/ip-functions/to-ipv6.md @@ -0,0 +1,60 @@ +--- +{ +"title": "TO_IPV6", +"language": "zh-CN" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## TO_IPV6 + +<version since="dev"> + +TO_IPV6 + +</version> + +### description + +#### Syntax + +`IPV6 TO_IPV6(STRING ipv6_str)` + +该函数类似ipv6_string_to_num，输入IPv6地址的字符串形式，并返回IPv6类型的值。 +该值的二进制形式等于ipv6_string_to_num函数返回值的二进制形式。 +如果IPv6地址为非法格式，则抛出异常。 + +### notice + +`入参ipv6_str不能为NULL，若为NULL，则抛出异常。` + +### example + +``` +mysql> select to_ipv6('::'); ++---------------+ +| to_ipv6('::') | ++---------------+ +| :: | ++---------------+ +``` + +### keywords + +TO_IPV6, IP diff --git a/docs/zh-CN/docs/sql-manual/sql-reference/Data-Types/IPV4.md b/docs/zh-CN/docs/sql-manual/sql-reference/Data-Types/IPV4.md new file mode 100644 index 00000000000..2766a20580e --- /dev/null +++ b/docs/zh-CN/docs/sql-manual/sql-reference/Data-Types/IPV4.md @@ -0,0 +1,85 @@ +--- +{ + "title": "IPV4", + "language": "zh-CN" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## IPV4 + +<version since="dev"> + +IPV4 + +</version> + +### description + +IPV4 +IPv4类型，以UInt32的形式存储在4个字节中，用于表示IPv4地址。 +取值范围是 ['0.0.0.0', '255.255.255.255']。 + +`超出取值范围或者格式非法的输入将返回NULL` + +### example + +建表示例如下： + +``` +CREATE TABLE ipv4_test ( + `id` int, + `ip_v4` ipv4 +) ENGINE=OLAP +DISTRIBUTED BY HASH(`id`) BUCKETS 4 +PROPERTIES ( +"replication_allocation" = "tag.location.default: 1" +); +``` + +插入数据示例： + +``` +insert into ipv4_test values(1, '0.0.0.0'); +insert into ipv4_test values(2, '127.0.0.1'); +insert into ipv4_test values(3, '59.50.185.152'); +insert into ipv4_test values(4, '255.255.255.255'); +insert into ipv4_test values(5, '255.255.255.256'); // invalid data +``` + +查询数据示例： + +``` +mysql> select * from ipv4_test order by id; ++------+-----------------+ +| id | ip_v4 | ++------+-----------------+ +| 1 | 0.0.0.0 | +| 2 | 127.0.0.1 | +| 3 | 59.50.185.152 | +| 4 | 255.255.255.255 | +| 5 | NULL | ++------+-----------------+ +``` + +### keywords + +IPV4 diff --git a/docs/zh-CN/docs/sql-manual/sql-reference/Data-Types/IPV6.md b/docs/zh-CN/docs/sql-manual/sql-reference/Data-Types/IPV6.md new file mode 100644 index 00000000000..678b404a672 --- /dev/null +++ b/docs/zh-CN/docs/sql-manual/sql-reference/Data-Types/IPV6.md @@ -0,0 +1,83 @@ +--- +{ + "title": "IPV6", + "language": "zh-CN" +} +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +## IPV6 + +<version since="dev"> + +IPV6 + +</version> + +### description + +IPV6 +IPv6类型，以Int128的形式存储在16个字节中，用于表示IPv6地址。 +取值范围是 ['::', 'ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff']。 + +`超出取值范围或者格式非法的输入将返回NULL` + +### example + +建表示例如下： + +``` +CREATE TABLE ipv6_test ( + `id` int, + `ip_v6` ipv6 +) ENGINE=OLAP +DISTRIBUTED BY HASH(`id`) BUCKETS 4 +PROPERTIES ( +"replication_allocation" = "tag.location.default: 1" +); +``` + +插入数据示例： + +``` +insert into ipv6_test values(1, '::'); +insert into ipv6_test values(2, '2001:16a0:2:200a::2'); +insert into ipv6_test values(3, 'ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff'); +insert into ipv6_test values(4, 'ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffffg'); // invalid data +``` + +查询数据示例： + +``` +mysql> select * from ipv6_test order by id; ++------+-----------------------------------------+ +| id | ip_v6 | ++------+-----------------------------------------+ +| 1 | :: | +| 2 | 2001:16a0:2:200a::2 | +| 3 | ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff | +| 4 | NULL | ++------+-----------------------------------------+ +``` + +### keywords + +IPV6 --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
