mirror of
https://github.com/ClickHouse/ClickHouse.git
synced 2024-11-10 01:25:21 +00:00
Add docs for URL table engine and url table function
This commit is contained in:
parent
58ebe8d572
commit
c0f5e33fe8
77
docs/en/operations/table_engines/url.md
Normal file
77
docs/en/operations/table_engines/url.md
Normal 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
|
19
docs/en/query_language/table_functions/url.md
Normal file
19
docs/en/query_language/table_functions/url.md
Normal 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
|
||||
```
|
74
docs/ru/operations/table_engines/url.md
Normal file
74
docs/ru/operations/table_engines/url.md
Normal 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`;
|
||||
- индексы;
|
||||
- репликация.
|
||||
|
20
docs/ru/query_language/table_functions/url.md
Normal file
20
docs/ru/query_language/table_functions/url.md
Normal 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
|
||||
```
|
@ -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':
|
||||
|
@ -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'
|
||||
- 'Интеграции':
|
||||
|
Loading…
Reference in New Issue
Block a user