merge to stable-25-2 YDBDOCS-1245 add docs for import / export (ch 1) (#24782)

Author: CyberROFL

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|

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)|

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:<br/>`/a/b/c/d/1.txt`<br/>`/a/b/2.csv`|
+|Path ends with a `/`|Path to a directory|The path `/a/` addresses all contents of the directory:<br/>`/a/b/c/d/1.txt`<br/>`/a/b/2.csv`|
 |Path contains a wildcard character `*`|Any files nested in the path|The path `/a/*.csv` addresses files in directories:<br/>`/a/b/c/1.csv`<br/>`/a/2.csv`<br/>`/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`|

ydb/docs/en/core/concepts/federated_query/s3/external_data_source.md

@@ -34,7 +34,8 @@ FROM
 WITH(
   FORMAT = "<file_format>",
   COMPRESSION = "<compression>",
-  SCHEMA = (<schema_definition>))
+  SCHEMA = (<schema_definition>),
+  <format_settings>)
 WHERE
   <filter>;
 ```
@@ -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.
+* `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.

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.

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|

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)|

ydb/docs/ru/core/concepts/federated_query/s3/_includes/path_format.md

@@ -1,5 +1,5 @@
 |Формат пути|Описание|Пример|
 |----|----|---|
-|Путь завершается символом `/`|Путь к каталогу|Путь `/a` адресует все содержимое каталога:<br/>`/a/b/c/d/1.txt`<br/>`/a/b/2.csv`|
+|Путь завершается символом `/`|Путь к каталогу|Путь `/a/` адресует все содержимое каталога:<br/>`/a/b/c/d/1.txt`<br/>`/a/b/2.csv`|
 |Путь содержит символ макроподстановки `*`|Любые файлы, вложенные в путь|Путь `/a/*.csv` адресует файлы в каталогах:<br/>`/a/b/c/1.csv`<br/>`/a/2.csv`<br/>`/a/b/c/d/e/f/g/2.csv`|
 |Путь не завершается символом `/` и не содержит символов макроподстановок|Путь к отдельному файлу|Путь `/a/b.csv` адресует конкретный файл `/a/b.csv`|

ydb/docs/ru/core/concepts/federated_query/s3/external_data_source.md

@@ -34,7 +34,8 @@ FROM
 WITH(
   FORMAT = "<file_format>",
   COMPRESSION = "<compression>",
-  SCHEMA = (<schema_definition>))
+  SCHEMA = (<schema_definition>),
+  <format_settings>)
 WHERE
   <filter>;
 ```
@@ -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.

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}