thevar1able/ClickHouse
1
0
Fork 0
mirror of https://github.com/ClickHouse/ClickHouse.git synced 2024-11-10 09:32:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve documentation about protobuf format. (#5015)

Browse Source
This commit is contained in:
Vitaly Baranov 2019-04-16 23:30:47 +03:00 committed by Ivan Blinkov
parent 29c92372a2
commit 18ddacc95e
2 changed files with 21 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
docs/en/interfaces/formats.md
View File

@ -646,9 +646,9 @@ See also [Format Schema](#formatschema).
Protobuf - is a [Protocol Buffers](https://developers.google.com/protocol-buffers/) format.
ClickHouse supports both `proto2` and `proto3`. Repeated/optional/required fields are supported.
This format requires an external format schema. The schema is cached between queries.
ClickHouse supports both `proto2` and `proto3` syntaxes. Repeated/optional/required fields are supported.
Usage examples:
```sql
@ -659,7 +659,7 @@ SELECT * FROM test.table FORMAT Protobuf SETTINGS format_schema = 'schemafile:Me
cat protobuf_messages.bin | clickhouse-client --query "INSERT INTO test.table FORMAT Protobuf SETTINGS format_schema='schemafile:MessageType'"
```
Where the file `schemafile.proto` looks like this:
where the file `schemafile.proto` looks like this:
```
syntax = "proto3";
@ -691,11 +691,13 @@ message MessageType {
```
ClickHouse tries to find a column named `x.y.z` (or `x_y_z` or `X.y_Z` and so on).
Nested messages are suitable to input or output a [nested data structures](../data_types/nested_data_structures/nested/).
Nested messages are suitable to input or output a [nested data structures](../data_types/nested_data_structures/nested.md).
Default values defined in a `proto2` protobuf schema like this
Default values defined in a protobuf schema like this
```
syntax = "proto2";
message MessageType {
optional int32 result_per_page = 3 [default = 10];
}
@ -703,6 +705,10 @@ message MessageType {
are not applied; the [table defaults](../query_language/create.md#create-default-values) are used instead of them.
ClickHouse inputs and outputs protobuf messages in the `length-delimited` format.
It means before every message should be written its length as a [varint](https://developers.google.com/protocol-buffers/docs/encoding#varints).
See also [how to read/write length-delimited protobuf messages in popular languages](https://cwiki.apache.org/confluence/display/GEODE/Delimiting+Protobuf+Messages).
## Format Schema {#formatschema}
The file name containing the format schema is set by the setting `format_schema`.

13
docs/ru/interfaces/formats.md
View File

@ -638,6 +638,8 @@ struct Message {
Protobuf - формат [Protocol Buffers](https://developers.google.com/protocol-buffers/).
Формат нуждается во внешнем описании схемы. Схема кэшируется между запросами.
ClickHouse поддерживает как синтаксис `proto2`, так и `proto3`; все типы полей (repeated/optional/required) поддерживаются.
Пример использования формата:
```sql
@ -663,9 +665,9 @@ message MessageType {
};
```
Соответствие между столбцами таблицы и полями сообщения Protocol Buffers устанавливается по имени,
Соответствие между столбцами таблицы и полями сообщения `Protocol Buffers` устанавливается по имени,
при этом игнорируется регистр букв и символы `_` (подчеркивание) и `.` (точка) считаются одинаковыми.
Если типы столбцов не соответствуют точно типам полей сообщения Protocol Buffers, производится необходимая конвертация.
Если типы столбцов не соответствуют точно типам полей сообщения `Protocol Buffers`, производится необходимая конвертация.
Вложенные сообщения поддерживаются, например, для поля `z` в таком сообщении
@ -682,11 +684,13 @@ message MessageType {
```
ClickHouse попытается найти столбец с именем `x.y.z` (или `x_y_z`, или `X.y_Z` и т.п.).
Вложенные сообщения удобно использовать в качестве соответствия для [вложенной структуры данных](../data_types/nested_data_structures/nested/).
Вложенные сообщения удобно использовать в качестве соответствия для [вложенной структуры данных](../data_types/nested_data_structures/nested.md).
Значения по умолчанию, определенные в схеме, например,
```
syntax = "proto2";
message MessageType {
optional int32 result_per_page = 3 [default = 10];
}
@ -694,6 +698,9 @@ message MessageType {
не применяются; вместо них используются определенные в таблице [значения по умолчанию](../query_language/create.md#create-default-values).
ClickHouse пишет и читает сообщения `Protocol Buffers` в формате `length-delimited`. Это означает, что перед каждым сообщением пишется его длина
в формате [varint](https://developers.google.com/protocol-buffers/docs/encoding#varints). См. также [как читать и записывать сообщения Protocol Buffers в формате length-delimited в различных языках программирования](https://cwiki.apache.org/confluence/display/GEODE/Delimiting+Protobuf+Messages).
## Схема формата {#formatschema}
Имя файла со схемой записывается в настройке `format_schema`. При использовании форматов `Cap'n Proto` и `Protobuf` требуется указать схему.