IPv4 and IPv6 domain docs.

4c178646 · Vasily Nemkov · b7f4d1ac · 4c178646 · 4c178646 · 4c178646
17 changed file
--- a/docs/en/data_types/domains/ipv4.md
+++ b/docs/en/data_types/domains/ipv4.md
+## IPv4
+
+`IPv4` is a domain based on `UInt32` type and serves as typed replacement for storing IPv4 values. It provides compact storage with human-friendly input-output format, and column type information on inspection.
+
+### Basic Usage
+
+``` sql
+CREATE TABLE hits (url String, from IPv4) ENGINE = MergeTree() ORDER BY url;
+
+DESCRIBE TABLE hits;
+```
+
+```
+┌─name─┬─type───┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┐
+│ url  │ String │              │                    │         │                  │
+│ from │ IPv4   │              │                    │         │                  │
+└──────┴────────┴──────────────┴────────────────────┴─────────┴──────────────────┘
+```
+
+OR you can use IPv4 domain as a key:
+
+``` sql
+CREATE TABLE hits (url String, from IPv4) ENGINE = MergeTree() ORDER BY from;
+```
+
+`IPv4` domain supports custom input format as IPv4-strings:
+
+``` sql
+INSERT INTO hits (url, from) VALUES ('https://wikipedia.org', '116.253.40.133')('https://clickhouse.yandex', '183.247.232.58')('https://clickhouse.yandex/docs/en/', '116.106.34.242');
+
+SELECT * FROM hits;
+```
+
+```
+┌─url────────────────────────────────┬───────────from─┐
+│ https://clickhouse.yandex/docs/en/ │ 116.106.34.242 │
+│ https://wikipedia.org              │ 116.253.40.133 │
+│ https://clickhouse.yandex          │ 183.247.232.58 │
+└────────────────────────────────────┴────────────────┘
+```
+
+Values are stored in compact binary form:
+
+``` sql
+SELECT toTypeName(from), hex(from) FROM hits LIMIT 1;
+```
+
+```
+┌─toTypeName(from)─┬─hex(from)─┐
+│ IPv4             │ B7F7E83A  │
+└──────────────────┴───────────┘
+```
+
+Domain values are not implicitly convertible to types other than `UInt32`.
+If you want to convert `IPv4` value to a string, you have to do that explicitly with `IPv4NumToString()` function:
+
+``` sql
+SELECT toTypeName(s), IPv4NumToString(from) as s FROM hits LIMIT 1;
+```
+
+```
+┌─toTypeName(IPv4NumToString(from))─┬─s──────────────┐
+│ String                            │ 183.247.232.58 │
+└───────────────────────────────────┴────────────────┘
+```
+
+Or cast to a `UInt32` value:
+
+``` sql
+SELECT toTypeName(i), CAST(from as UInt32) as i FROM hits LIMIT 1;
+```
+
+```
+┌─toTypeName(CAST(from, 'UInt32'))─┬──────────i─┐
+│ UInt32                           │ 3086477370 │
+└──────────────────────────────────┴────────────┘
+```
+
+[Original article](https://clickhouse.yandex/docs/en/data_types/domains/ipv4) <!--hide-->
--- a/docs/en/data_types/domains/ipv6.md
+++ b/docs/en/data_types/domains/ipv6.md
+## IPv6
+
+`IPv6` is a domain based on `FixedString(16)` type and serves as typed replacement for storing IPv6 values.  It provides compact storage with human-friendly input-output format, and column type information on inspection.
+
+### Basic Usage
+
+``` sql
+CREATE TABLE hits (url String, from IPv6) ENGINE = MergeTree() ORDER BY url;
+
+DESCRIBE TABLE hits;
+```
+
+```
+┌─name─┬─type───┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┐
+│ url  │ String │              │                    │         │                  │
+│ from │ IPv6   │              │                    │         │                  │
+└──────┴────────┴──────────────┴────────────────────┴─────────┴──────────────────┘
+```
+
+OR you can use `IPv6` domain as a key:
+
+``` sql
+CREATE TABLE hits (url String, from IPv6) ENGINE = MergeTree() ORDER BY from;
+```
+
+`IPv6` domain supports custom input as IPv6-strings:
+
+``` sql
+INSERT INTO hits (url, from) VALUES ('https://wikipedia.org', '2a02:aa08:e000:3100::2')('https://clickhouse.yandex', '2001:44c8:129:2632:33:0:252:2')('https://clickhouse.yandex/docs/en/', '2a02:e980:1e::1');
+
+SELECT * FROM hits;
+```
+
+```
+┌─url────────────────────────────────┬─from──────────────────────────┐
+│ https://clickhouse.yandex          │ 2001:44c8:129:2632:33:0:252:2 │
+│ https://clickhouse.yandex/docs/en/ │ 2a02:e980:1e::1               │
+│ https://wikipedia.org              │ 2a02:aa08:e000:3100::2        │
+└────────────────────────────────────┴───────────────────────────────┘
+```
+
+Values are stored in compact binary form:
+
+``` sql
+SELECT toTypeName(from), hex(from) FROM hits LIMIT 1;
+```
+
+```
+┌─toTypeName(from)─┬─hex(from)────────────────────────┐
+│ IPv6             │ 200144C8012926320033000002520002 │
+└──────────────────┴──────────────────────────────────┘
+```
+
+Domain values are not implicitly convertible to types other than `FixedString(16)`.
+If you want to convert `IPv6` value to a string, you have to do that explicitly with `IPv6NumToString()` function:
+
+``` sql
+SELECT toTypeName(s), IPv6NumToString(from) as s FROM hits LIMIT 1;
+```
+
+```
+┌─toTypeName(IPv6NumToString(from))─┬─s─────────────────────────────┐
+│ String                            │ 2001:44c8:129:2632:33:0:252:2 │
+└───────────────────────────────────┴───────────────────────────────┘
+```
+
+Or cast to a `FixedString(16)` value:
+
+``` sql
+SELECT toTypeName(i), CAST(from as FixedString(16)) as i FROM hits LIMIT 1;
+```
+
+```
+┌─toTypeName(CAST(from, 'FixedString(16)'))─┬─i───────┐
+│ FixedString(16)                           │  ��� │
+└───────────────────────────────────────────┴─────────┘
+```
+
+[Original article](https://clickhouse.yandex/docs/en/data_types/domains/ipv6) <!--hide-->
--- a/docs/en/data_types/domains/overview.md
+++ b/docs/en/data_types/domains/overview.md
+# Domains
+
+Domains are special-purpose types, that add some extra features atop of existing base type, leaving on-wire and on-disc format of underlying table intact. At the moment, ClickHouse does not support user-defined domains.
+
+You can use domains anywhere corresponding base type can be used:
+
+* Create a column of domain type
+* Read/write values from/to domain column
+* Use it as index if base type can be used as index
+* Call functions with values of domain column
+* etc.
+
+### Extra Features of Domains
+
+* Explicit column type name in `SHOW CREATE TABLE` or `DESCRIBE TABLE`
+* Input from human-friendly format with `INSERT INTO domain_table(domain_column) VALUES(...)`
+* Output to human-friendly format for `SELECT domain_column FROM domain_table`
+* Loading data from external source in human-friendly format: `INSERT INTO domain_table FORMAT CSV ...`
+
+### Limitations
+
+* Can't convert index column of base type to domain type via `ALTER TABLE`.
+* Can't implicitly convert string values into domain values when inserting data from another column or table.
+* Domain adds no constrains on stored values.
+
+[Original article](https://clickhouse.yandex/docs/en/data_types/domains/overview) <!--hide-->
\ No newline at end of file
--- a/docs/en/query_language/functions/ip_address_functions.md
+++ b/docs/en/query_language/functions/ip_address_functions.md
@@ -131,7 +131,7 @@ SELECT IPv6NumToString(IPv4ToIPv6(IPv4StringToNum('192.168.0.1'))) AS addr

 Accepts a FixedString(16) value containing the IPv6 address in binary format. Returns a string containing the address of the specified number of bits removed in text format. For example:

-```sql
+``` sql
 WITH
    IPv6StringToNum('2001:0DB8:AC10:FE01:FEED:BABE:CAFE:F00D') AS ipv6,
    IPv4ToIPv6(IPv4StringToNum('192.168.0.1')) AS ipv4
@@ -178,5 +178,68 @@ SELECT IPv6CIDRtoIPv6Range(toIPv6('2001:0db8:0000:85a3:0000:0000:ac1f:8001'), 32
 └────────────────────────────────────────────────────────────────────────────┘
 ```

+## toIPv4(string)
+
+An alias to `IPv4StringToNum()` that takes a string form of IPv4 address and returns value of [IPv4](../../data_types/domains/ipv4.md) type, which is binary equal to value returned by `IPv4StringToNum()`.
+
+``` sql
+WITH
+    '171.225.130.45' as IPv4_string
+SELECT
+    toTypeName(IPv4StringToNum(IPv4_string)),
+    toTypeName(toIPv4(IPv4_string))
+```
+
+```
+┌─toTypeName(IPv4StringToNum(IPv4_string))─┬─toTypeName(toIPv4(IPv4_string))─┐
+│ UInt32                                   │ IPv4                            │
+└──────────────────────────────────────────┴─────────────────────────────────┘
+```
+
+``` sql
+WITH
+    '171.225.130.45' as IPv4_string
+SELECT
+    hex(IPv4StringToNum(IPv4_string)),
+    hex(toIPv4(IPv4_string))
+```
+
+```
+┌─hex(IPv4StringToNum(IPv4_string))─┬─hex(toIPv4(IPv4_string))─┐
+│ ABE1822D                          │ ABE1822D                 │
+└───────────────────────────────────┴──────────────────────────┘
+```
+
+## toIPv6(string)
+
+An alias to `IPv6StringToNum()` that takes a string form of IPv6 address and returns value of [IPv6](../../data_types/domains/ipv6.md) type, which is binary equal to value returned by `IPv6StringToNum()`.
+
+``` sql
+WITH
+    '2001:438:ffff::407d:1bc1' as IPv6_string
+SELECT
+    toTypeName(IPv6StringToNum(IPv6_string)),
+    toTypeName(toIPv6(IPv6_string))
+```
+
+```
+┌─toTypeName(IPv6StringToNum(IPv6_string))─┬─toTypeName(toIPv6(IPv6_string))─┐
+│ FixedString(16)                          │ IPv6                            │
+└──────────────────────────────────────────┴─────────────────────────────────┘
+```
+
+``` sql
+WITH
+    '2001:438:ffff::407d:1bc1' as IPv6_string
+SELECT
+    hex(IPv6StringToNum(IPv6_string)),
+    hex(toIPv6(IPv6_string))
+```
+
+```
+┌─hex(IPv6StringToNum(IPv6_string))─┬─hex(toIPv6(IPv6_string))─────────┐
+│ 20010438FFFF000000000000407D1BC1  │ 20010438FFFF000000000000407D1BC1 │
+└───────────────────────────────────┴──────────────────────────────────┘
+```

 [Original article](https://clickhouse.yandex/docs/en/query_language/functions/ip_address_functions/) <!--hide-->
--- a/docs/fa/data_types/domains/ipv4.md
+++ b/docs/fa/data_types/domains/ipv4.md
+../../../en/data_types/domains/ipv4.md
\ No newline at end of file
--- a/docs/fa/data_types/domains/ipv6.md
+++ b/docs/fa/data_types/domains/ipv6.md
+../../../en/data_types/domains/ipv6.md
\ No newline at end of file
--- a/docs/fa/data_types/domains/overview.md
+++ b/docs/fa/data_types/domains/overview.md
+../../../en/data_types/domains/overview.md
\ No newline at end of file
--- a/docs/ru/data_types/domains/ipv4.md
+++ b/docs/ru/data_types/domains/ipv4.md
+../../../en/data_types/domains/ipv4.md
\ No newline at end of file
--- a/docs/ru/data_types/domains/ipv6.md
+++ b/docs/ru/data_types/domains/ipv6.md
+../../../en/data_types/domains/ipv6.md
\ No newline at end of file
--- a/docs/ru/data_types/domains/overview.md
+++ b/docs/ru/data_types/domains/overview.md
+../../../en/data_types/domains/overview.md
\ No newline at end of file
--- a/docs/toc_en.yml
+++ b/docs/toc_en.yml
@@ -56,6 +56,10 @@ nav:
    - 'Expression': 'data_types/special_data_types/expression.md'
    - 'Set': 'data_types/special_data_types/set.md'
    - 'Nothing': 'data_types/special_data_types/nothing.md'
+  - 'Domains':
+    - 'Overview': 'data_types/domains/overview.md'
+    - 'IPv4': 'data_types/domains/ipv4.md'
+    - 'IPv6': 'data_types/domains/ipv6.md'

 - 'Table Engines':
  - 'Introduction': 'operations/table_engines/index.md'

--- a/docs/toc_fa.yml
+++ b/docs/toc_fa.yml
@@ -56,6 +56,10 @@ nav:
    - 'Expression': 'data_types/special_data_types/expression.md'
    - 'Set': 'data_types/special_data_types/set.md'
    - 'Nothing': 'data_types/special_data_types/nothing.md'
+  - 'Domains':
+    - 'Overview': 'data_types/domains/overview.md'
+    - 'IPv4': 'data_types/domains/ipv4.md'
+    - 'IPv6': 'data_types/domains/ipv6.md'

 - 'Table Engines':
  - 'Introduction': 'operations/table_engines/index.md'

--- a/docs/toc_ru.yml
+++ b/docs/toc_ru.yml
@@ -57,6 +57,10 @@ nav:
    - 'Expression': 'data_types/special_data_types/expression.md'
    - 'Set': 'data_types/special_data_types/set.md'
    - 'Nothing': 'data_types/special_data_types/nothing.md'
+  - 'Domains':
+    - 'Overview': 'data_types/domains/overview.md'
+    - 'IPv4': 'data_types/domains/ipv4.md'
+    - 'IPv6': 'data_types/domains/ipv6.md'

 - 'Движки таблиц':
  - 'Введение': 'operations/table_engines/index.md'

--- a/docs/toc_zh.yml
+++ b/docs/toc_zh.yml
@@ -55,6 +55,10 @@ nav:
    - 'Expression': 'data_types/special_data_types/expression.md'
    - 'Set': 'data_types/special_data_types/set.md'
    - 'Nothing': 'data_types/special_data_types/nothing.md'
+  - 'Domains':
+    - 'Overview': 'data_types/domains/overview.md'
+    - 'IPv4': 'data_types/domains/ipv4.md'
+    - 'IPv6': 'data_types/domains/ipv6.md'

 - 'Table Engines':
  - 'Introduction': 'operations/table_engines/index.md'

--- a/docs/zh/data_types/domains/ipv4.md
+++ b/docs/zh/data_types/domains/ipv4.md
+../../../en/data_types/domains/ipv4.md
\ No newline at end of file
--- a/docs/zh/data_types/domains/ipv6.md
+++ b/docs/zh/data_types/domains/ipv6.md
+../../../en/data_types/domains/ipv6.md
\ No newline at end of file
--- a/docs/zh/data_types/domains/overview.md
+++ b/docs/zh/data_types/domains/overview.md
+../../../en/data_types/domains/overview.md
\ No newline at end of file