Los motores de base de datos Remote y RemoteSecure proporcionan acceso en tiempo real a las tablas de una base de datos en un servidor ClickHouse remoto mediante el protocolo TCP nativo. Son los equivalentes entre ClickHouse de los motores de base de datos MySQL y PostgreSQL.
La lista de tablas y su estructura se obtienen del servidor remoto bajo demanda (mediante SHOW TABLES y DESCRIBE TABLE internamente), por lo que la base de datos siempre refleja el estado actual del servidor remoto. Cada tabla se expone como un almacenamiento Distributed en un clúster ad hoc creado a partir de las direcciones proporcionadas, que reenvía las consultas SELECT e INSERT al servidor remoto.
Esto resulta útil para federar varios clústeres de ClickHouse o para conectar un clúster de ClickHouse más grande con clickhouse-local o con un clúster más pequeño.
Creación de una base de datos
Remote se conecta mediante el puerto TCP sin cifrar (tcp_port, 9000 de forma predeterminada) cuando no se especifica el puerto.RemoteSecure se conecta mediante una conexión TLS segura a través del puerto TCP seguro (tcp_port_secure, 9440 de forma predeterminada) cuando no se especifica el puerto.
addresses_expr — Una dirección de servidor remoto o una expresión que genera varias direcciones, con el formato host o host:port. La expresión de dirección admite los mismos patrones glob que la función de tabla remote (por ejemplo, {a,b,c}, {N..M} y {a|b} para expandirse en varios segmentos y réplicas). Cuando no se especifica el puerto, Remote utiliza el puerto TCP sin cifrar (tcp_port, 9000 de forma predeterminada) y RemoteSecure utiliza el puerto TCP seguro (tcp_port_secure, 9440 de forma predeterminada).database — El nombre de la base de datos en el servidor remoto.user — El nombre del usuario remoto. Opcional; valor predeterminado: default.password — La contraseña del usuario remoto. Opcional; valor predeterminado: vacía.
Las direcciones y las credenciales se almacenan en la definición de la base de datos, por lo que la contraseña se oculta en SHOW CREATE DATABASE. Al igual que con la función de tabla remote, una dirección que apunta al servidor actual se trata como un segmento local: SELECT e INSERT se ejecutan directamente con el usuario actual —que, por tanto, necesita los privilegios correspondientes sobre la base de datos subyacente y sus tablas— y las credenciales almacenadas solo se utilizan para servidores realmente remotos. Si la réplica local de un segmento no contiene la base de datos o una tabla, la búsqueda recurre a las réplicas remotas del segmento, como lo hace una tabla Distributed. En ese caso, SHOW CREATE TABLE muestra las direcciones de respaldo efectivas (las réplicas locales se eliminan de sus segmentos) en lugar de las configuradas, de modo que la definición de tabla Remote(...) generada reconstruye el objeto que realmente atiende las consultas.
Cuando la expresión de dirección describe varios segmentos, cada tabla proxy lee de todos ellos, pero los metadatos —la lista de tablas y su estructura— se obtienen de un segmento arbitrario (preferiblemente uno local), igual que con la función de tabla remote, de modo que una enumeración requiere una sola consulta en lugar de una por segmento. Por lo tanto, se espera que los segmentos de un clúster sirvan el mismo conjunto de tablas; una tabla presente solo en algunos de ellos se sirve mediante un proxy cuyas consultas fallan en los segmentos que no la tienen. Un INSERT en una tabla de una base de datos con varios segmentos envía cada fila a un segmento aleatorio (las tablas proxy Distributed tienen una clave de sharding rand() implícita); para fijar el segmento de una consulta, establezca insert_shard_id. La clave implícita solo distribuye las filas insertadas: para las lecturas, la tabla se comporta como una tabla Distributed sin clave de sharding (en particular, optimize_skip_unused_shards y force_optimize_skip_unused_shards no la tratan como una clave de poda de segmentos). SHOW CREATE TABLE incluye la clave en la definición de tabla Remote(...) generada, por lo que una tabla recreada a partir de ella también acepta consultas INSERT con varios segmentos.
También se admiten colecciones con nombre:
- El motor es una vista de lectura directa del servidor remoto: las sentencias DDL
CREATE TABLE, DROP TABLE, ALTER y similares aplicadas a la base de datos Remote no son compatibles. Administre el esquema directamente en el servidor remoto.
- Los derechos de acceso se aplican en el servidor remoto al usuario remoto configurado y, localmente, mediante los privilegios habituales sobre la base de datos y sus tablas.
- Una tabla de un segmento local que el usuario no tiene permitido ver se informa como inexistente en lugar de como prohibida, por lo que una base de datos
Remote no puede utilizarse para sondear los nombres de las tablas de una base de datos local sobre la que el usuario no tiene privilegios. Esto se aplica tanto a la enumeración (SHOW TABLES, EXISTS TABLE) como a la resolución (DESCRIBE TABLE, SHOW CREATE TABLE, SELECT), y dicha tabla tampoco se proporciona a través de las réplicas remotas de su segmento: la alternativa descrita anteriormente solo se activa cuando la réplica local realmente no tiene la tabla.
- La enumeración de las tablas de una base de datos que existe en la réplica local de un segmento también incluye las tablas que solo existen en las réplicas remotas de ese segmento, de modo que
SHOW TABLES y system.tables coincidan con EXISTS TABLE, DESCRIBE TABLE y SELECT, que recurren a esas réplicas. Cuando ninguna de las réplicas remotas responde, se devuelve la lista de la réplica local tal cual, porque ya es la respuesta de una réplica disponible.
- Si el servidor remoto no está disponible, la enumeración de sus tablas (
SHOW TABLES, system.tables) informa del error de conexión en lugar de devolver una lista vacía de tablas, igual que EXISTS TABLE y SELECT en la misma base de datos. Tenga en cuenta que un SELECT de system.tables que abarque todas las bases de datos también falla mientras una de esas bases de datos no sea accesible.
- Una base de datos
Remote puede apuntar a otra base de datos Remote en el mismo servidor. Enumerar y describir las tablas de dicha cadena no requiere privilegios sobre la base de datos intermedia: no contiene datos ni metadatos propios, y cada salto ya comprueba los derechos del solicitante sobre los objetos que representa. En cambio, leer y escribir datos requiere SELECT / INSERT en cada salto de la cadena, porque la consulta se ejecuta realmente sobre la tabla de la base de datos intermedia, exactamente igual que para una tabla Distributed sobre otra tabla Distributed. La regla de visibilidad descrita anteriormente se mantiene a lo largo de la cadena: una tabla que la base de datos intermedia oculta al solicitante tampoco se proporciona a través de las réplicas remotas de la base de datos externa. Si la base de datos intermedia de la réplica local no puede acceder a su propio destino, la réplica local del segmento externo no puede responder en absoluto —exactamente como si la propia réplica estuviera inactiva—, y la base de datos externa recurre a las réplicas remotas del segmento.
Cree una base de datos Remote que apunte a la base de datos system de un servidor remoto y lea datos de ella:
Última modificación el 14 de agosto de 2026
