Add docs for URL table engine and url table function

This commit is contained in:
alesapin 2018-07-27 13:21:04 +03:00
parent 58ebe8d572
commit c0f5e33fe8
6 changed files with 194 additions and 0 deletions

View File

@ -0,0 +1,77 @@
<a name="table_engines-url"></a>
# URL(URL, Format)
This data source operates with data on remote HTTP/HTTPS server. The engine is
similar to [`File`](./file.md#).
## Usage in ClickHouse server
```
URL(URL, Format)
```
`Format` should be supported for `SELECT` and/or `INSERT`. For the full list of
supported formats see [Formats](../../interfaces/formats.md#formats).
`URL` must match the format of Uniform Resource Locator. The specified
URL must address a server working with HTTP or HTTPS. The server shouldn't
require any additional HTTP-headers.
`INSERT` and `SELECT` queries are transformed into `POST` and `GET` requests
respectively. For correct `POST`-requests handling the remote server should support
[Chunked transfer encoding](https://ru.wikipedia.org/wiki/Chunked_transfer_encoding).
**Example:**
**1.** Create the `url_engine_table` table:
```sql
CREATE TABLE url_engine_table (word String, value UInt64)
ENGINE=URL('http://127.0.0.1:12345/', CSV)
```
**2.** Implement simple http-server using python3:
```python3
from http.server import BaseHTTPRequestHandler, HTTPServer
class CSVHTTPServer(BaseHTTPRequestHandler):
def do_GET(self):
self.send_response(200)
self.send_header('Content-type', 'text/csv')
self.end_headers()
self.wfile.write(bytes('Hello,1\nWorld,2\n', "utf-8"))
if __name__ == "__main__":
server_address = ('127.0.0.1', 12345)
HTTPServer(server_address, CSVHTTPServer).serve_forever()
```
```bash
python3 server.py
```
**3.** Query the data:
```sql
SELECT * FROM url_engine_table
```
```text
┌─word──┬─value─┐
│ Hello │ 1 │
│ World │ 2 │
└───────┴───────┘
```
## Details of implementation
- Reads and writes can be parallel
- Not supported:
- `ALTER`
- `SELECT ... SAMPLE`
- Indices
- Replication

View File

@ -0,0 +1,19 @@
<a name="table_functions-url"></a>
# url
`url(URL, format, structure)` - returns a table created from the `URL` with given
`format` and `structure`.
URL - HTTP or HTTPS server address, which can accept `GET` and/or `POST` requests.
format - [format](../../interfaces/formats.md#formats) of the data.
structure - table structure in `'UserID UInt64, Name String'` format. Determines column names and types.
**Example**
```sql
-- getting the first 3 lines of a table that contains columns of String and UInt32 type from HTTP-server which answers in CSV format.
SELECT * FROM url('http://127.0.0.1:12345/', CSV, 'column1 String, column2 UInt32') LIMIT 3
```

View File

@ -0,0 +1,74 @@
<a name="table_engines-url"></a>
# URL(URL, Format)
Управляет данными на удаленном HTTP/HTTPS сервере. Данный движок похож
на движок [`File`](./file.md#).
## Использование движка в сервере ClickHouse
`Format` должен быть таким, который ClickHouse, может использовать в запросах
`SELECT` и, если есть необходимость, `INSERT`. Полный список поддерживаемых форматов смотрите в
разделе [Форматы](../../interfaces/formats.md#formats).
`URL` должен соответствовать структуре Uniform Resource Locator. По указанному URL должен находится сервер
работающий по протоколу HTTP или HTTPS. При этом не должно требоваться никаких
дополнительных заголовков для получения ответа от сервера.
Запросы `INSERT` и `SELECT` транслируются в `POST` и `GET` запросы
соответственно. Для обработки `POST`-запросов удаленный сервер должен поддерживать
[Chunked transfer encoding](https://ru.wikipedia.org/wiki/Chunked_transfer_encoding).
**Пример:**
**1.** Создадим на сервере таблицу `url_engine_table`:
```sql
CREATE TABLE url_engine_table (word String, value UInt64)
ENGINE=URL('http://127.0.0.1:12345/', CSV)
```
**2.** Создадим простейший http-сервер стандартными средствами языка python3 и
запустим его:
```python3
from http.server import BaseHTTPRequestHandler, HTTPServer
class CSVHTTPServer(BaseHTTPRequestHandler):
def do_GET(self):
self.send_response(200)
self.send_header('Content-type', 'text/csv')
self.end_headers()
self.wfile.write(bytes('Hello,1\nWorld,2\n', "utf-8"))
if __name__ == "__main__":
server_address = ('127.0.0.1', 12345)
HTTPServer(server_address, CSVHTTPServer).serve_forever()
```
```bash
python3 server.py
```
**3.** Запросим данные:
```sql
SELECT * FROM url_engine_table
```
```text
┌─word──┬─value─┐
│ Hello │ 1 │
│ World │ 2 │
└───────┴───────┘
```
## Особенности использования
- Поддерживается многопоточное чтение и запись.
- Не поддерживается:
- использование операций `ALTER` и `SELECT...SAMPLE`;
- индексы;
- репликация.

View File

@ -0,0 +1,20 @@
<a name="table_functions-url"></a>
# url
`url(URL, format, structure)` - возвращает таблицу со столбцами, указанными в
`structure`, созданную из данных находящихся по `URL` в формате `format`.
URL - адрес, по которому сервер принимает `GET` и/или `POST` запросы по
протоколу HTTP или HTTPS.
format - [формат](../../interfaces/formats.md#formats) данных.
structure - структура таблицы в форме `'UserID UInt64, Name String'`. Определяет имена и типы столбцов.
**Пример**
```sql
-- получение 3-х строк таблицы, состоящей из двух колонк типа String и UInt32 от сервера, отдающего данные в формате CSV
SELECT * FROM url('http://127.0.0.1:12345/', CSV, 'column1 String, column2 UInt32') LIMIT 3
```

View File

@ -94,6 +94,7 @@ pages:
- 'merge': 'query_language/table_functions/merge.md'
- 'numbers': 'query_language/table_functions/numbers.md'
- 'remote': 'query_language/table_functions/remote.md'
- 'url': 'query_language/table_functions/url.md'
- 'Dictionaries':
- 'Introduction': 'query_language/dicts/index.md'
- 'External dictionaries':
@ -134,6 +135,7 @@ pages:
- 'Null': 'operations/table_engines/null.md'
- 'Set': 'operations/table_engines/set.md'
- 'Join': 'operations/table_engines/join.md'
- 'URL': 'operations/table_engines/url.md'
- 'View': 'operations/table_engines/view.md'
- 'MaterializedView': 'operations/table_engines/materializedview.md'
- 'Integrations':

View File

@ -97,6 +97,7 @@ pages:
- 'merge': 'query_language/table_functions/merge.md'
- 'numbers': 'query_language/table_functions/numbers.md'
- 'remote': 'query_language/table_functions/remote.md'
- 'url': 'query_language/table_functions/url.md'
- 'Словари':
- 'Введение': 'query_language/dicts/index.md'
- 'Внешние словари':
@ -138,6 +139,7 @@ pages:
- 'Null': 'operations/table_engines/null.md'
- 'Set': 'operations/table_engines/set.md'
- 'Join': 'operations/table_engines/join.md'
- 'URL': 'operations/table_engines/url.md'
- 'View': 'operations/table_engines/view.md'
- 'MaterializedView': 'operations/table_engines/materializedview.md'
- 'Интеграции':