Updated description of File table engine.

docs/ru/formats/csv.md

@@ -1,3 +1,5 @@
+<a name="csv"></a>
+
 # CSV
 
 Формат comma separated values ([RFC](https://tools.ietf.org/html/rfc4180)).

docs/ru/formats/csvwithnames.md

@@ -1,3 +1,5 @@
+<a name="csvwithnames"></a>
+
 # CSVWithNames
 
 Выводит также заголовок, аналогично `TabSeparatedWithNames`.

docs/ru/formats/index.md

@@ -3,3 +3,29 @@
 # Форматы
 
 Формат определяет, в каком виде данные отдаются вам (пишутся, форматируются сервером) при SELECT-е и в каком виде принимаются (читаются, парсятся сервером) при INSERT-е.
+
+Поддерживаемые форматы данных:
+
+- [TabSeparated](tabseparated.md#tabseparated)
+- [TabSeparatedRaw](tabseparatedraw.md#tabseparatedraw)
+- [TabSeparatedWithNames](tabseparatedwithnames.md#tabseparatedwithnames)
+- [TabSeparatedWithNamesAndTypes](tabseparatedwithnamesandtypes.md#tabseparatedwithnamesandtypes)
+- [CSV](csv.md#csv)
+- [CSVWithNames](csvwithnames.md#csvwithnames)
+- [Values](values.md#values)
+- [Vertical](vertical.md#vertical)
+- [VerticalRaw](verticalraw.md#verticalraw)
+- [JSON](json.md#json)
+- [JSONCompact](jsoncompact.md#jsoncompact)
+- [JSONEachRow](jsoneachrow.md#jsoneachrow)
+- [TSKV](tskv.md#tskv)
+- [Pretty](pretty.md#pretty)
+- [PrettyCompact](prettycompact.md#prettycompact)
+- [PrettyCompactMonoBlock](prettycompactmonoblock.md#prettycompactmonoblock)
+- [PrettyNoEscapes](prettynoescapes.md#prettynoescapes)
+- [PrettySpace](prettyspace.md#prettyspace)
+- [RowBinary](rowbinary.md#rowbinary)
+- [Native](native.md#native)
+- [Null](null.md#null)
+- [XML](xml.md#xml)
+- [CapnProto](capnproto.md#capnproto)

docs/ru/formats/json.md

@@ -1,3 +1,5 @@
+<a name="json"></a>
+
 # JSON
 
 Выводит данные в формате JSON. Кроме таблицы с данными, также выводятся имена и типы столбцов, и некоторая дополнительная информация - общее количество выведенных строк, а также количество строк, которое могло бы быть выведено, если бы не было LIMIT-а. Пример:

docs/ru/formats/jsoncompact.md

@@ -1,3 +1,5 @@
+<a name="jsoncompact"></a>
+
 # JSONCompact
 
 Отличается от JSON только тем, что строчки данных выводятся в массивах, а не в object-ах.

docs/ru/formats/jsoneachrow.md

@@ -1,3 +1,5 @@
+<a name="jsoneachrow"></a>
+
 # JSONEachRow
 
 Выводит данные в виде отдельных JSON объектов для каждой строки (newline delimited JSON).

docs/ru/formats/native.md

@@ -1,3 +1,5 @@
+<a name="native"></a>
+
 # Native
 
 Самый эффективный формат. Данные пишутся и читаются блоками в бинарном виде. Для каждого блока пишется количество строк, количество столбцов, имена и типы столбцов, а затем кусочки столбцов этого блока, один за другим. То есть, этот формат является "столбцовым" - не преобразует столбцы в строки. Именно этот формат используется в родном интерфейсе - при межсерверном взаимодействии, при использовании клиента командной строки, при работе клиентов, написанных на C++.

docs/ru/formats/null.md

@@ -1,3 +1,5 @@
+<a name="null"></a>
+
 # Null
 
 Ничего не выводит. При этом, запрос обрабатывается, а при использовании клиента командной строки, данные ещё и передаются на клиент. Используется для тестов, в том числе, тестов производительности.

docs/ru/formats/pretty.md

@@ -1,3 +1,5 @@
+<a name="pretty"></a>
+
 # Pretty
 
 Выводит данные в виде Unicode-art табличек, также используя ANSI-escape последовательности для установки цветов в терминале.

docs/ru/formats/prettycompact.md

@@ -1,3 +1,5 @@
+<a name="prettycompact"></a>
+
 # PrettyCompact
 
 Отличается от `Pretty` тем, что не рисуется сетка между строками - результат более компактный.

docs/ru/formats/prettycompactmonoblock.md

@@ -1,3 +1,5 @@
+<a name="prettycompactmonoblock"></a>
+
 # PrettyCompactMonoBlock
 
-Отличается от `PrettyCompact` тем, что строки (до 10 000 штук) буферизуются и затем выводятся в виде одной таблицы, а не по блокам.
+Отличается от [PrettyCompact](prettycompact.md#prettycompact) тем, что строки (до 10 000 штук) буферизуются и затем выводятся в виде одной таблицы, а не по блокам.

docs/ru/formats/prettynoescapes.md

@@ -1,3 +1,5 @@
+<a name="prettynoescapes"></a>
+
 # PrettyNoEscapes
 
 Отличается от Pretty тем, что не используются ANSI-escape последовательности. Это нужно для отображения этого формата в браузере, а также при использовании утилиты командной строки watch.

docs/ru/formats/prettyspace.md

@@ -1,3 +1,5 @@
+<a name="prettyspace"></a>
+
 # PrettySpace
 
-Отличается от `PrettyCompact` тем, что вместо сетки используется пустое пространство (пробелы).
+Отличается от [PrettyCompact](prettycompact.md#prettycompact) тем, что вместо сетки используется пустое пространство (пробелы).

docs/ru/formats/rowbinary.md

@@ -1,3 +1,5 @@
+<a name="rowbinary"></a>
+
 # RowBinary
 
 Форматирует и парсит данные по строкам, в бинарном виде. Строки и значения уложены подряд, без разделителей.

docs/ru/formats/tabseparated.md

@@ -1,3 +1,5 @@
+<a name="tabseparated"></a>
+
 # TabSeparated
 
 В TabSeparated формате данные пишутся по строкам. Каждая строчка содержит значения, разделённые табами. После каждого значения идёт таб, кроме последнего значения в строке, после которого идёт перевод строки. Везде подразумеваются исключительно unix-переводы строк. Последняя строка также обязана содержать перевод строки на конце. Значения пишутся в текстовом виде, без обрамляющих кавычек, с экранированием служебных символов.

docs/ru/formats/tabseparatedraw.md

@@ -1,3 +1,5 @@
+<a name="tabseparatedraw"></a>
+
 # TabSeparatedRaw
 
 Отличается от формата `TabSeparated` тем, что строки выводятся без экранирования.

docs/ru/formats/tabseparatedwithnames.md

@@ -1,3 +1,5 @@
+<a name="tabseparatedwithnames"></a>
+
 # TabSeparatedWithNames
 
 Отличается от формата `TabSeparated` тем, что в первой строке пишутся имена столбцов.

docs/ru/formats/tabseparatedwithnamesandtypes.md

@@ -1,3 +1,5 @@
+<a name="tabseparatedwithnamesandtypes"></a>
+
 # TabSeparatedWithNamesAndTypes
 
 Отличается от формата `TabSeparated` тем, что в первой строке пишутся имена столбцов, а во второй - типы столбцов.

docs/ru/formats/tskv.md

@@ -1,3 +1,5 @@
+<a name="tskv"></a>
+
 # TSKV
 
 Похож на TabSeparated, но выводит значения в формате name=value. Имена экранируются так же, как строки в формате TabSeparated и, дополнительно, экранируется также символ =.

docs/ru/formats/values.md

@@ -1,3 +1,5 @@
+<a name="values"></a>
+
 # Values
 
 Выводит каждую строку в скобках. Строки разделены запятыми. После последней строки запятой нет. Значения внутри скобок также разделены запятыми. Числа выводятся в десятичном виде без кавычек. Массивы выводятся в квадратных скобках. Строки, даты, даты-с-временем выводятся в кавычках. Правила экранирования и особенности парсинга аналогичны формату TabSeparated. При форматировании, лишние пробелы не ставятся, а при парсинге - допустимы и пропускаются (за исключением пробелов внутри значений типа массив, которые недопустимы).

docs/ru/formats/vertical.md

@@ -1,3 +1,5 @@
+<a name="vertical"></a>
+
 # Vertical
 
 Выводит каждое значение на отдельной строке, с указанием имени столбца. Формат удобно использовать для вывода одной-нескольких строк, если каждая строка состоит из большого количества столбцов.

docs/ru/formats/verticalraw.md

@@ -1,3 +1,5 @@
+<a name="verticalraw"></a>
+
 # VerticalRaw
 
 Отличается от формата `Vertical` тем, что строки выводятся без экранирования.

docs/ru/formats/xml.md

@@ -1,3 +1,5 @@
+<a name="xml"></a>
+
 # XML
 
 Формат XML подходит только для вывода данных, не для парсинга. Пример:

docs/ru/query_language/queries.md

@@ -157,13 +157,17 @@ SELECT a, b, c FROM (SELECT ...)
 
 Отсутствует отдельный запрос для удаления представлений. Чтобы удалить представление, следует использовать `DROP TABLE`.
 
+<a name="queries-attach"></a>
+
 ## ATTACH
-Запрос полностью аналогичен запросу `CREATE`, но
+Запрос полностью аналогичен запросу `CREATE`, но:
+
 - вместо слова `CREATE` используется слово `ATTACH`;
 - запрос не создаёт данные на диске, а предполагает, что данные уже лежат в соответствующих местах, и всего лишь добавляет информацию о таблице в сервер.
-После выполнения запроса ATTACH, сервер будет знать о существовании таблицы.
 
-Если таблица перед этим была отсоединена (``DETACH``), т.е. её структура известна, то можно использовать сокращенную форму записи без определения структуры.
+После выполнения `ATTACH`, сервер будет знать о существовании таблицы.
+
+Если таблица перед этим была отсоединена (`DETACH`), т.е. её структура известна, то можно использовать сокращенную форму записи без определения структуры.
 
 ```sql
 ATTACH TABLE [IF NOT EXISTS] [db.]name

docs/ru/table_engines/file.md

@@ -1,3 +1,78 @@
-# File(InputFormat)
+<a name="file"></a>
 
-Источником данных является файл, хранящий данные в одном из поддерживаемых форматов входных данных (TabSeparated, Native, и т. д.) ...
+# File(Format)
+
+Управляет данными в одном файле на диске в указанном формате.
+
+Примеры применения:
+
+- Выгрузка данных из ClickHouse в файл.
+- Преобразование данных из одного формата в другой.
+- Обновление данных в ClickHouse редактированием файла на диске.
+
+## Использование движка в сервере ClickHouse
+
+```
+File(Format)
+```
+
+`Format` необходимо выбирать из тех, которые ClickHouse может и читать и писать. Полный список поддерживаемых форматов смотрите в разделе [Форматы](../formats/index.md#formats).
+
+Сервер ClickHouse не позволяет указать путь к файлу, с которым будет работать `File`. Используется путь к хранилищу, определенный параметром [path](../operations/server_settings/settings.md#server_settings-path) в конфигурации сервера.
+
+При создании таблицы с помощью `File(Format)` сервер ClickHouse создает в хранилище каталог с именем таблицы, а после добавления в таблицу данных помещает туда файл `data.Format`.
+
+Можно вручную создать в хранилище каталог таблицы, поместить туда файл, затем на сервере ClickHouse добавить ([ATTACH](../query_language/queries.md#queries-attach)) информацию о таблице, соответствующей имени каталога и прочитать из файла данные.
+
+<div class="admonition warning">
+Будьте аккуратны с этой функциональностью, поскольку сервер ClickHouse не отслеживает внешние изменения данных. Если в файл будет производиться запись одновременно со стороны сервера ClickHouse и с внешней стороны, то результат непредсказуем.
+</div>
+
+**Пример:**
+
+**1.** Создадим на сервере таблицу `file_engine_table`:
+
+```sql
+CREATE TABLE file_engine_table (name String, value UInt32) ENGINE=File(TabSeparated)
+```
+
+В конфигурации по умолчанию сервер ClickHouse создаст каталог `/var/lib/clickhouse/data/default/file_engine_table`.
+
+**2.** Вручную создадим файл `/var/lib/clickhouse/data/default/file_engine_table/data.TabSeparated` с содержимым:
+
+```bash
+$cat data.TabSeparated
+one	1
+two	2
+```
+
+**3.** Запросим данные:
+
+```sql
+SELECT * FROM file_engine_table
+```
+
+```text
+┌─name─┬─value─┐
+│ one  │     1 │
+│ two  │     2 │
+└──────┴───────┘
+```
+
+## Использование движка в clickhouse-local
+
+В [clickhouse-local](../utils/clickhouse-local.md#utils-clickhouse-local) движок в качестве параметра принимает не только формат, но и путь к файлу. В том числе можно указать стандартные потоки ввода/вывода цифровым или буквенным обозначением `0` или `stdin`, `1` или `stdout`.
+
+**Пример:**
+
+```bash
+$ echo -e "1,2\n3,4" | clickhouse-local -q "CREATE TABLE table (a Int64, b Int64) ENGINE = File(CSV, stdin); SELECT a, b FROM table; DROP TABLE table"
+```
+
+## Особенности использования
+
+- Поддерживается многопоточное чтение и однопоточная запись.
+- Не поддерживается:
+    - использование операций `ALTER` и `SELECT...SAMPLE`;
+    - индексы;
+    - репликация.