motor de tabla URL - ClickHouse Documentation

Consulta datos desde/hacia un servidor HTTP/HTTPS remoto. Este motor es similar al motor File. El motor URL también es un envoltorio unificado que enruta al backend correcto según el esquema de URL, por lo que un esquema no HTTP reconocido se delega al motor correspondiente; consulte enrutamiento según el esquema de URL a continuación. Sintaxis: URL(URL [,Format] [,CompressionMethod])

El parámetro URL debe ajustarse a la estructura de un Uniform Resource Locator. Para una URL http/https (el backend predeterminado), debe apuntar a un servidor que use HTTP o HTTPS, y obtener una respuesta del servidor no requiere encabezados adicionales. En cambio, una URL con un esquema no HTTP reconocido (file://, s3://, az://, hdfs://, …) se delega al motor correspondiente; consulte enrutamiento según el esquema de URL a continuación.
Format debe ser uno que ClickHouse pueda usar en consultas SELECT y, si es necesario, en INSERTs. Para ver la lista completa de formatos admitidos, consulte Formats. Si no se especifica este argumento, ClickHouse detecta el formato automáticamente a partir del sufijo del parámetro URL. Si el sufijo del parámetro URL no coincide con ninguno de los formatos admitidos, no se podrá crear la tabla. Por ejemplo, para la expresión del motor URL('http://localhost/test.json'), se aplica el formato JSON.
CompressionMethod indica si el body HTTP debe comprimirse. Si la compresión está habilitada, los paquetes HTTP enviados por el motor URL contienen el header ‘Content-Encoding’ para indicar qué método de compresión se está usando.

Para habilitar la compresión, primero asegúrese de que el endpoint HTTP remoto indicado por el parámetro URL admita el algoritmo de compresión correspondiente. Los valores admitidos de CompressionMethod deben ser uno de los siguientes:

gzip or gz
deflate
brotli or br
lzma or xz
zstd or zst
lz4
bz2
snappy
none
auto

Si no se especifica CompressionMethod, el valor predeterminado es auto. Esto significa que ClickHouse detecta automáticamente el método de compresión a partir del sufijo del parámetro URL. Si el sufijo coincide con cualquiera de los métodos de compresión enumerados anteriormente, se aplica la compresión correspondiente; de lo contrario, no se habilita ninguna compresión. Por ejemplo, para la expresión del motor URL('http://localhost/test.gzip'), se aplica el método de compresión gzip, pero para URL('http://localhost/test.fr'), no se habilita ninguna compresión porque el sufijo fr no coincide con ninguno de los métodos de compresión anteriores.

Enrutamiento según el esquema de URL

El motor URL es un envoltorio unificado para los demás motores de archivos y de almacenamiento de objetos: enruta al backend adecuado según el esquema de URL. http/https (y cualquier esquema no reconocido) los gestiona el propio motor URL; file:// lo gestiona el motor File; s3://, gs://, gcs://, oss://, el motor S3; az://, azure://, abfss://, abfs://, el motor AzureBlobStorage; y hdfs://, el motor HDFS. Solo se enrutan los esquemas de S3 que el mapeador de URI de S3 resuelve a un endpoint concreto sin configuración adicional (s3, además de gs/gcs/oss). Otros esquemas de proveedores compatibles con S3 (cos, obs, eos, …) son específicos de cada región y no tienen una correspondencia predeterminada de endpoint, por lo que pasar una URL de ese tipo al motor URL se considera un esquema no reconocido y se notifica como error; para esos backends, use directamente el motor S3 (con url_scheme_mappers configurado). El ajuste url_base se aplica antes del enrutamiento por esquema, por lo que una referencia relativa primero se resuelve con respecto a la base y luego se enruta al motor correspondiente.

CREATE TABLE file_via_url (a UInt32, b String) ENGINE = URL('file://data.csv', CSV);
CREATE TABLE s3_via_url (a UInt32, b String) ENGINE = URL('s3://bucket/key.csv', CSV);

Uso

Las consultas INSERT y SELECT se transforman en peticiones POST y GET, respectivamente. Para procesar las peticiones POST, el servidor remoto debe admitir la codificación de transferencia en fragmentos. Puede limitar el número máximo de redirecciones HTTP GET mediante el ajuste max_http_get_redirects.

Comodines con páginas de índice HTTP

Cuando allow_experimental_url_wildcard_from_index_pages está habilitada, el motor de tabla URL puede expandir comodines obteniendo páginas de índice HTTP y extrayendo enlaces de ellas. Es el mismo mecanismo que utiliza la función de tabla url. La expansión está limitada por max_http_index_page_size para cada página de índice obtenida y por url_wildcard_max_directories_to_read para el recorrido recursivo de directorios.

Ejemplo

1. Cree una tabla url_engine_table en el servidor:

CREATE TABLE url_engine_table (word String, value UInt64)
ENGINE=URL('http://127.0.0.1:12345/', CSV)

2. Crea un servidor HTTP básico con las herramientas estándar de Python 3 e inícialo:

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

$ python3 server.py

3. Solicitar datos:

SELECT * FROM url_engine_table

┌─word──┬─value─┐
│ Hello │     1 │
│ World │     2 │
└───────┴───────┘

Detalles de la implementación

Las lecturas y escrituras pueden realizarse en paralelo
No se admite:
- las operaciones ALTER y SELECT...SAMPLE.
- Índices.
- Replicación.

Columnas virtuales

_path — Ruta de la URL. Tipo: LowCardinality(String).
_file — Nombre del recurso de la URL. Tipo: LowCardinality(String).
_size — Tamaño del recurso en bytes. Tipo: Nullable(UInt64). Si se desconoce el tamaño, el valor es NULL.
_time — Fecha y hora de la última modificación del archivo. Tipo: Nullable(DateTime). Si se desconoce la hora, el valor es NULL.
_headers - Encabezados de la respuesta HTTP. Tipo: Map(LowCardinality(String), LowCardinality(String)).

Resolución de las URL relativas

La configuración url_base permite usar una URL relativa en el motor URL. Cuando se establece url_base, la URL que se pasa al motor se resuelve con respecto a esta según la RFC 3986. Para obtener una descripción completa de las reglas de resolución, consulta la documentación de la función de tabla url. Ejemplo

SET url_base = 'http://127.0.0.1:12345/';
CREATE TABLE url_engine_table (word String, value UInt64) ENGINE = URL('hello.csv', CSV);
SELECT * FROM url_engine_table;

Configuración de almacenamiento

engine_url_skip_empty_files - permite omitir archivos vacíos durante la lectura. Está deshabilitado de forma predeterminada.
enable_url_encoding - permite habilitar o deshabilitar la decodificación/codificación de la ruta en el URI. Está habilitado de forma predeterminada.
url_base - URL base para resolver las URL relativas que se pasan al motor.

​Enrutamiento según el esquema de URL

​Uso

​Comodines con páginas de índice HTTP

​Ejemplo

​Detalles de la implementación

​Columnas virtuales

​Resolución de las URL relativas

​Configuración de almacenamiento