From 55ece38b3da574b7392e4f1c4cecaf455dd45968 Mon Sep 17 00:00:00 2001 From: Ivan Sukhov Date: Sun, 30 Mar 2025 16:04:22 +0300 Subject: [PATCH 1/2] New documentation on formatting settings for reading from s3 (#15970) --- .../s3/_includes/date_formats.md | 7 ++++ .../s3/_includes/format_settings.md | 10 +++++ .../s3/_includes/path_format.md | 2 +- .../s3/external_data_source.md | 41 ++++++++++++++----- .../federated_query/s3/external_table.md | 2 + .../s3/_includes/date_formats.md | 7 ++++ .../s3/_includes/format_settings.md | 10 +++++ .../s3/_includes/path_format.md | 2 +- .../s3/external_data_source.md | 37 +++++++++++++---- .../federated_query/s3/external_table.md | 1 + 10 files changed, 97 insertions(+), 22 deletions(-) create mode 100644 ydb/docs/en/core/concepts/federated_query/s3/_includes/date_formats.md create mode 100644 ydb/docs/en/core/concepts/federated_query/s3/_includes/format_settings.md create mode 100644 ydb/docs/ru/core/concepts/federated_query/s3/_includes/date_formats.md create mode 100644 ydb/docs/ru/core/concepts/federated_query/s3/_includes/format_settings.md diff --git a/ydb/docs/en/core/concepts/federated_query/s3/_includes/date_formats.md b/ydb/docs/en/core/concepts/federated_query/s3/_includes/date_formats.md new file mode 100644 index 000000000000..845e7f40685d --- /dev/null +++ b/ydb/docs/en/core/concepts/federated_query/s3/_includes/date_formats.md @@ -0,0 +1,7 @@ +|Name|Description|Example| +|---|---|---| +|`POSIX`|String in `%Y-%m-%d %H:%M:%S` format|2001-03-26 16:10:00| +|`ISO`|Format, corresponding to the [ISO 8601](https://ru.wikipedia.org/wiki/ISO_8601) standard|2001-03-26 16:10:00Z| +|`UNIX_TIME_SECONDS`|Number of seconds that have elapsed since the 1st of january 1970 (00:00:00 UTC)|985623000| +|`UNIX_TIME_MILLISECONDS`|Number of milliseconds that have elapsed since the 1st of january 1970 (00:00:00 UTC)|985623000000| +|`UNIX_TIME_MICROSECONDS`|Number of microseconds that have elapsed since the 1st of january 1970 (00:00:00 UTC)|985623000000000| \ No newline at end of file diff --git a/ydb/docs/en/core/concepts/federated_query/s3/_includes/format_settings.md b/ydb/docs/en/core/concepts/federated_query/s3/_includes/format_settings.md new file mode 100644 index 000000000000..60f2fd1ac1a1 --- /dev/null +++ b/ydb/docs/en/core/concepts/federated_query/s3/_includes/format_settings.md @@ -0,0 +1,10 @@ +|Setting name|Description|Possible values| +|----|----|---| +|`file_pattern`|File name template|File name template string. Wildcards `*` are supported.| +|`data.interval.unit`|Unit for parsing `Interval` type|`MICROSECONDS`, `MILLISECONDS`, `SECONDS`, `MINUTES`, `HOURS`, `DAYS`, `WEEKS`| +|`data.datetime.format_name`|Predefined format in which `Datetime` data is stored|`POSIX`, `ISO`| +|`data.datetime.format`|Strftime-like template which defines how `Datetime` data is stored|Formatting string, for example: `%Y-%m-%dT%H-%M`| +|`date.timestamp.format_name`|Predefined format in which `Timestamp` data is stored|`POSIX`, `ISO`, `UNIX_TIME_SECONDS`, `UNIX_TIME_MILLISECONDS`, `UNIX_TIME_MICROSECONDS`| +|`data.timestamp.format`|Strftime-like template which defines how `Timestamp` data is stored|Formatting string, for example: `%Y-%m-%dT%H-%M-%S`| +|`data.date.format`|The format in which `Date` data is stored|Formatting string, for example: `%Y-%m-%d`| +|`csv_delimiter`|Delimeter for `csv_with_names` format|Any character (UTF-8)| diff --git a/ydb/docs/en/core/concepts/federated_query/s3/_includes/path_format.md b/ydb/docs/en/core/concepts/federated_query/s3/_includes/path_format.md index be0d6abf3bb8..4b15b4ea5248 100644 --- a/ydb/docs/en/core/concepts/federated_query/s3/_includes/path_format.md +++ b/ydb/docs/en/core/concepts/federated_query/s3/_includes/path_format.md @@ -1,5 +1,5 @@ |Path format|Description|Example| |----|----|---| -|Path ends with a `/`|Path to a directory|The path `/a` addresses all contents of the directory:
`/a/b/c/d/1.txt`
`/a/b/2.csv`| +|Path ends with a `/`|Path to a directory|The path `/a/` addresses all contents of the directory:
`/a/b/c/d/1.txt`
`/a/b/2.csv`| |Path contains a wildcard character `*`|Any files nested in the path|The path `/a/*.csv` addresses files in directories:
`/a/b/c/1.csv`
`/a/2.csv`
`/a/b/c/d/e/f/g/2.csv`| |Path does not end with `/` and does not contain wildcard characters|Path to a single file|The path `/a/b.csv` addresses the specific file `/a/b.csv`| diff --git a/ydb/docs/en/core/concepts/federated_query/s3/external_data_source.md b/ydb/docs/en/core/concepts/federated_query/s3/external_data_source.md index 85127f77e85b..90b91fb5939f 100644 --- a/ydb/docs/en/core/concepts/federated_query/s3/external_data_source.md +++ b/ydb/docs/en/core/concepts/federated_query/s3/external_data_source.md @@ -34,7 +34,8 @@ FROM WITH( FORMAT = "", COMPRESSION = "", - SCHEMA = ()) + SCHEMA = (), + ) WHERE ; ``` @@ -46,6 +47,7 @@ Where: * `file_format` — the [data format](formats.md#formats) in the files. * `compression` — the [compression format](formats.md#compression_formats) of the files. * `schema_definition` — the [schema definition](#schema) of the data stored in the files. +* `format_settings` — optional [format settings](#format_settings) ### Data schema description {#schema} @@ -97,12 +99,22 @@ Where: As a result of executing such a query, the names and types of fields will be inferred. -### Data path formats {#path_format} +### Data path formats specified in `file_path` {#path_format} -In {{ ydb-full-name }}, the following data paths are supported: +In {{ ydb-full-name }}, the followingdata paths are supported: {% include [!](_includes/path_format.md) %} +### Format settings {#format_settings} + +In {{ ydb-full-name }}, the following format settings are supported: + +{% include [!](_includes/format_settings.md) %} + +You can only specify `file_pattern` setting if `file_path` is a path to a directory. Any conversion specifiers supported by [`strftime`(C99)](https://en.cppreference.com/w/c/chrono/strftime) function can be used in formatting strings. In {{ ydb-full-name }}, the following `Datetime` and `Timestamp` formats are supported: + +{% include [!](_includes/date_formats.md) %} + ## Example {#read_example} Example query to read data from S3 ({{ objstorage-full-name }}): @@ -111,21 +123,28 @@ Example query to read data from S3 ({{ objstorage-full-name }}): SELECT * FROM - connection.`folder/filename.csv` + connection.`folder/` WITH( FORMAT = "csv_with_names", + COMPRESSION="gzip" SCHEMA = ( - Year Int32, - Manufacturer Utf8, - Model Utf8, - Price Double - ) + Id Int32 NOT NULL, + UserId Int32 NOT NULL, + TripDate Date NOT NULL, + TripDistance Double NOT NULL, + UserComment Utf8 + ), + FILE_PATTERN="*.csv.gz", + `DATA.DATE.FORMAT`="%Y-%m-%d", + CSV_DELIMITER='/' ); ``` Where: * `connection` — the name of the external data source leading to the S3 bucket ({{ objstorage-full-name }}). -* `folder/filename.csv` — the path to the file in the S3 bucket ({{ objstorage-full-name }}). -* `SCHEMA` — the data schema description in the file. \ No newline at end of file +* `folder/filename.csv` — the path to the directory in the S3 bucket ({{ objstorage-full-name }}). +* `SCHEMA` — the data schema description in the file. +* `*.csv.gz` — file name template. +* `%Y-%m-%d` — format in which `Date` type is stored in S3. diff --git a/ydb/docs/en/core/concepts/federated_query/s3/external_table.md b/ydb/docs/en/core/concepts/federated_query/s3/external_table.md index f8456f2ef5d1..b3787c3500a3 100644 --- a/ydb/docs/en/core/concepts/federated_query/s3/external_table.md +++ b/ydb/docs/en/core/concepts/federated_query/s3/external_table.md @@ -37,6 +37,8 @@ Where: - `csv_with_names` - one of the [permitted data storage formats](formats.md); - `gzip` - one of the [permitted compression algorithms](formats.md#compression). +You can also specify [format settings](external_data_source.md#format_settings). + ## Data model {#data-model} Reading data using external tables from S3 ({{ objstorage-name }}) is done with regular SQL queries as if querying a normal table. diff --git a/ydb/docs/ru/core/concepts/federated_query/s3/_includes/date_formats.md b/ydb/docs/ru/core/concepts/federated_query/s3/_includes/date_formats.md new file mode 100644 index 000000000000..ad2a6dd2172d --- /dev/null +++ b/ydb/docs/ru/core/concepts/federated_query/s3/_includes/date_formats.md @@ -0,0 +1,7 @@ +|Имя|Описание|Пример| +|---|---|---| +|`POSIX`|Строка формата `%Y-%m-%d %H:%M:%S`|2001-03-26 16:10:00| +|`ISO`|Формат, соответствующий стандарту [ISO 8601](https://ru.wikipedia.org/wiki/ISO_8601)|2001-03-26 16:10:00Z| +|`UNIX_TIME_SECONDS`|Количество секунд прошедших с 1 января 1970 года (00:00:00 UTC)|985623000| +|`UNIX_TIME_MILLISECONDS`|Количество миллисекунд прошедших с 1 января 1970 года (00:00:00 UTC)|985623000000| +|`UNIX_TIME_MICROSECONDS`|Количество микросекунд прошедших с 1 января 1970 года (00:00:00 UTC)|985623000000000| \ No newline at end of file diff --git a/ydb/docs/ru/core/concepts/federated_query/s3/_includes/format_settings.md b/ydb/docs/ru/core/concepts/federated_query/s3/_includes/format_settings.md new file mode 100644 index 000000000000..0297de1fa73d --- /dev/null +++ b/ydb/docs/ru/core/concepts/federated_query/s3/_includes/format_settings.md @@ -0,0 +1,10 @@ +|Имя параметра|Описание|Принимаемые значения| +|----|----|---| +|`file_pattern`|Шаблон имени файла|Строка шаблона имени. Поддерживаются wildcards `*`.| +|`data.interval.unit`|Единица измерения для парсинга типа `Interval`|`MICROSECONDS`, `MILLISECONDS`, `SECONDS`, `MINUTES`, `HOURS`, `DAYS`, `WEEKS`| +|`data.datetime.format_name`|Предопределенный формат, в котором записаны данные типа `Datetime`|`POSIX`, `ISO`| +|`data.datetime.format`|Шаблон, определяющий как записаны данные типа `Datetime`|Строка форматирования, например: `%Y-%m-%dT%H-%M`| +|`data.timestamp.format_name`|Предопределенный формат, в котором записаны данные типа `Timestamp`|`POSIX`, `ISO`, `UNIX_TIME_SECONDS`, `UNIX_TIME_MILLISECONDS`, `UNIX_TIME_MICROSECONDS`| +|`data.timestamp.format`|Шаблон, определяющий как записаны данные типа `Timestamp`|Строка форматирования, например: `%Y-%m-%dT%H-%M-%S`| +|`data.date.format`|Формат, в котором записаны данные типа `Date`|Строка форматирования, например: `%Y-%m-%d`| +|`csv_delimiter`|Разделитель данных в формате `csv_with_names`|Любой символ (UTF-8)| diff --git a/ydb/docs/ru/core/concepts/federated_query/s3/_includes/path_format.md b/ydb/docs/ru/core/concepts/federated_query/s3/_includes/path_format.md index ea21735d7b20..abab7b53ba5d 100644 --- a/ydb/docs/ru/core/concepts/federated_query/s3/_includes/path_format.md +++ b/ydb/docs/ru/core/concepts/federated_query/s3/_includes/path_format.md @@ -1,5 +1,5 @@ |Формат пути|Описание|Пример| |----|----|---| -|Путь завершается символом `/`|Путь к каталогу|Путь `/a` адресует все содержимое каталога:
`/a/b/c/d/1.txt`
`/a/b/2.csv`| +|Путь завершается символом `/`|Путь к каталогу|Путь `/a/` адресует все содержимое каталога:
`/a/b/c/d/1.txt`
`/a/b/2.csv`| |Путь содержит символ макроподстановки `*`|Любые файлы, вложенные в путь|Путь `/a/*.csv` адресует файлы в каталогах:
`/a/b/c/1.csv`
`/a/2.csv`
`/a/b/c/d/e/f/g/2.csv`| |Путь не завершается символом `/` и не содержит символов макроподстановок|Путь к отдельному файлу|Путь `/a/b.csv` адресует конкретный файл `/a/b.csv`| diff --git a/ydb/docs/ru/core/concepts/federated_query/s3/external_data_source.md b/ydb/docs/ru/core/concepts/federated_query/s3/external_data_source.md index 44b49fe031e6..18fa291fe290 100644 --- a/ydb/docs/ru/core/concepts/federated_query/s3/external_data_source.md +++ b/ydb/docs/ru/core/concepts/federated_query/s3/external_data_source.md @@ -34,7 +34,8 @@ FROM WITH( FORMAT = "", COMPRESSION = "", - SCHEMA = ()) + SCHEMA = (), + ) WHERE ; ``` @@ -46,6 +47,7 @@ WHERE * `file_format` — [формат данных](formats.md#formats) в файлах. * `compression` — [формат сжатия](formats.md#compression_formats) файлов. * `schema_definition` — [описание схемы хранимых данных](#schema) в файлах. +* `format_settings` — опциональные [параметры форматирования](#format_settings) ### Описание схемы данных {#schema} @@ -97,12 +99,22 @@ WHERE В результате выполнения такого запроса будут автоматически выведены названия и типы полей. -### Форматы путей к данным {#path_format} +### Форматы путей к данным задаваемых в параметре `file_path` {#path_format} В {{ ydb-full-name }} поддерживаются следующие пути к данным: {% include [!](_includes/path_format.md) %} +### Параметры форматирования {#format_settings} + +В {{ ydb-full-name }} поддерживаются следующие параметры форматирования: + +{% include [!](_includes/format_settings.md) %} + +Параметр `file_pattern` можно использовать только в том случае, если `file_path` – путь к каталогу. В строках форматирования можно использовать любые шаблонные переменные, поддерживаемые функцией [`strftime`(C99)](https://en.cppreference.com/w/c/chrono/strftime). В {{ ydb-full-name }} поддерживаются следующие форматы типов `Datetime` и `Timestamp`: + +{% include [!](_includes/date_formats.md) %} + ## Пример {#read_example} Пример запроса для чтения данных из S3 ({{ objstorage-full-name }}): @@ -111,21 +123,28 @@ WHERE SELECT * FROM - connection.`folder/filename.csv` + connection.`folder/` WITH( FORMAT = "csv_with_names", + COMPRESSION="gzip" SCHEMA = ( - Year Int32, - Manufacturer Utf8, - Model Utf8, - Price Double - ) + Id Int32 NOT NULL, + UserId Int32 NOT NULL, + TripDate Date NOT NULL, + TripDistance Double NOT NULL, + UserComment Utf8 + ), + FILE_PATTERN="*.csv.gz", + `DATA.DATE.FORMAT`="%Y-%m-%d", + CSV_DELIMITER='/' ); ``` Где: * `connection` — название внешнего источника данных, ведущего на бакет S3 ({{ objstorage-full-name }}). -* `folder/filename.csv` — путь к файлу в бакете S3 ({{ objstorage-full-name }}). +* `folder/` — путь к папке с данными в бакете S3 ({{ objstorage-full-name }}). * `SCHEMA` — описание схемы данных в файле. +* `*.csv.gz` — шаблон имени файлов с данными. +* `%Y-%m-%d` — формат записи данных типа `Date` в S3. diff --git a/ydb/docs/ru/core/concepts/federated_query/s3/external_table.md b/ydb/docs/ru/core/concepts/federated_query/s3/external_table.md index c55250c4b06b..bde27c24c296 100644 --- a/ydb/docs/ru/core/concepts/federated_query/s3/external_table.md +++ b/ydb/docs/ru/core/concepts/federated_query/s3/external_table.md @@ -37,6 +37,7 @@ CREATE EXTERNAL TABLE `s3_test_data` ( - `csv_with_names` - один из [допустимых типов хранения данных](formats.md); - `gzip` - один из [допустимых алгоритмов сжатия](formats.md#compression). +Также при создании внешних таблиц поддерживаются [параметры форматирования](external_data_source.md#format_settings). ## Модель данных {#data-model} From c396c3d06ad9e6f33dd631994d5507f0ae9e75ef Mon Sep 17 00:00:00 2001 From: Pisarenko Grigoriy Date: Fri, 12 Sep 2025 14:34:03 +0300 Subject: [PATCH 2/2] Fixed warning --- .../ru/core/concepts/federated_query/s3/external_data_source.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/ru/core/concepts/federated_query/s3/external_data_source.md b/ydb/docs/ru/core/concepts/federated_query/s3/external_data_source.md index 18fa291fe290..94fcafe5b97e 100644 --- a/ydb/docs/ru/core/concepts/federated_query/s3/external_data_source.md +++ b/ydb/docs/ru/core/concepts/federated_query/s3/external_data_source.md @@ -99,7 +99,7 @@ WHERE В результате выполнения такого запроса будут автоматически выведены названия и типы полей. -### Форматы путей к данным задаваемых в параметре `file_path` {#path_format} +### Форматы путей к данным задаваемых в параметре `file_path` {#path_format} В {{ ydb-full-name }} поддерживаются следующие пути к данным: