ClickHouse/docs/en/operations/table_engines/file.md
Ivan Blinkov c7e526e050
WIP on documentation (#2692)
* Additional .gitignore entries

* Merge a bunch of small articles about system tables into single one

* Merge a bunch of small articles about formats into single one

* Adapt table with formats to English docs too

* Add SPb meetup link to main page

* Move Utilities out of top level of docs (the location is probably not yet final) + translate couple articles

* Merge MacOS.md into build_osx.md

* Move Data types higher in ToC

* Publish changelog on website alongside documentation

* Few fixes for en/table_engines/file.md

* Use smaller header sizes in changelogs

* Group up table engines inside ToC

* Move table engines out of top level too

* Specificy in ToC that query language is SQL based. Thats a bit excessive, but catches eye.

* Move stuff that is part of query language into respective folder

* Move table functions lower in ToC

* Lost redirects.txt update

* Do not rely on comments in yaml + fix few ru titles

* Extract major parts of queries.md into separate articles

* queries.md has been supposed to be removed

* Fix weird translation

* Fix a bunch of links

* There is only table of contents left

* "Query language" is actually part of SQL abbreviation

* Change filename in README.md too

* fix mistype

* s/formats\/interfaces/interfaces\/formats/g

* Remove extra clarification from header as it was too verbose, probably making it a bit more confusing

* Empty article was supposed to be hidden

* At least change incorrect title

* Move special links to the bottom of nav and slightly highlight them

* Skip hidden pages in bottom navigation too

* Make front page of documentation to be part of Introduction

* Make tables in introduction somewhat readable + move abbreviation definitions earlier

* Some introduction text refactoring

* Some docs introduction refactoring

* Use admonitions instead of divs

* Additional .gitignore

* Treat .gif as images too

* Clarify ToC item
2018-07-20 20:35:34 +03:00

79 lines
2.5 KiB
Markdown

<a name="table_engines-file"></a>
# File(InputFormat)
The data source is a file that stores data in one of the supported input formats (TabSeparated, Native, etc.).
Usage examples:
- Data export from ClickHouse to file.
- Convert data from one format to another.
- Updating data in ClickHouse via editing a file on a disk.
## Usage in ClickHouse server
```
File(Format)
```
`Format` should be supported for either `INSERT` and `SELECT`. For the full list of supported formats see [Formats](../../interfaces/formats.md#formats).
ClickHouse does not allow to specify filesystem path for`File`. It will use folder defined by [path](../server_settings/settings.md#server_settings-path) setting in server configuration.
When creating table using `File(Format)` it creates empty subdirectory in that folder. When data is written to that table, it's put into `data.Format` file in that subdirectory.
You may manually create this subfolder and file in server filesystem and then [ATTACH](../../query_language/misc.md#queries-attach) it to table information with matching name, so you can query data from that file.
!!! warning
Be careful with this funcionality, because ClickHouse does not keep track of external changes to such files. The result of simultaneous writes via ClickHouse and outside of ClickHouse is undefined.
**Example:**
**1.** Set up the `file_engine_table` table:
```sql
CREATE TABLE file_engine_table (name String, value UInt32) ENGINE=File(TabSeparated)
```
By default ClickHouse will create folder `/var/lib/clickhouse/data/default/file_engine_table`.
**2.** Manually create `/var/lib/clickhouse/data/default/file_engine_table/data.TabSeparated` containing:
```bash
$ cat data.TabSeparated
one 1
two 2
```
**3.** Query the data:
```sql
SELECT * FROM file_engine_table
```
```text
┌─name─┬─value─┐
│ one │ 1 │
│ two │ 2 │
└──────┴───────┘
```
## Usage in clickhouse-local
In [clickhouse-local](../utils/clickhouse-local.md#utils-clickhouse-local) File engine accepts file path in addition to `Format`. Default input/output streams can be specified using numeric or human-readable names like `0` or `stdin`, `1` or `stdout`.
**Example:**
```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"
```
## Details of implementation
- Reads can be parallel, but not writes
- Not supported:
- `ALTER`
- `SELECT ... SAMPLE`
- Indices
- Replication