remote, remoteSecure - ClickHouse Documentation

La fonction de table remote permet d’accéder à des serveurs distants à la volée, c’est-à-dire sans créer de table Distributed. La fonction de table remoteSecure est similaire à remote, mais via une connexion sécurisée. Les deux fonctions peuvent être utilisées dans des requêtes SELECT et INSERT.

Syntaxe

remote(addresses_expr, [db, table, user [, password], sharding_key])
remote(addresses_expr, [db.table, user [, password], sharding_key])
remote(named_collection[, option=value [,..]])
remoteSecure(addresses_expr, [db, table, user [, password], sharding_key])
remoteSecure(addresses_expr, [db.table, user [, password], sharding_key])
remoteSecure(named_collection[, option=value [,..]])

Paramètres

Argument	Description
`addresses_expr`	Une adresse de serveur distant, ou une expression qui génère plusieurs adresses de serveurs distants. Format : `host` ou `host:port`. `host` peut être spécifié sous forme de nom de serveur ou d’adresse IPv4 ou IPv6. Une adresse IPv6 doit être indiquée entre `[]`. `port` est le port TCP du serveur distant. Si le port est omis, tcp_port du fichier de configuration du serveur est utilisé pour la fonction de table `remote` (9000 par défaut), et tcp_port_secure pour la fonction de table `remoteSecure` (9440 par défaut). Pour les adresses IPv6, un port est obligatoire. Si seul le paramètre `addresses_expr` est spécifié, `db` et `table` utilisent `system.one` par défaut. Type : String.
`db`	Nom de la base de données. Type : String.
`table`	Nom de la table. Type : String.
`user`	Nom d’utilisateur. S’il n’est pas spécifié, `default` est utilisé. Type : String.
`password`	Mot de passe de l’utilisateur. S’il n’est pas spécifié, un mot de passe vide est utilisé. Type : String.
`sharding_key`	Clé de sharding permettant de répartir les données entre les nœuds. Par exemple : `insert into remote('127.0.0.1:9000,127.0.0.2', db, table, 'default', rand())`. Type : UInt32.

Les arguments peuvent également être transmis à l’aide de collections nommées.

Valeur renvoyée

Une table située sur un serveur distant.

Utilisation

Comme les fonctions de table remote et remoteSecure rétablissent la connexion à chaque requête, il est recommandé d’utiliser plutôt une table Distributed. De plus, si des noms d’hôte sont définis, ils sont résolus et les erreurs ne sont pas prises en compte lors de l’utilisation de différentes répliques. Pour traiter un grand nombre de requêtes, créez toujours la table Distributed à l’avance et n’utilisez pas la fonction de table remote. La fonction de table remote peut être utile dans les cas suivants :

Migration ponctuelle de données d’un système à un autre
Accès à un serveur spécifique pour comparer des données, effectuer du débogage et réaliser des tests, c.-à-d. pour des connexions ad hoc.
Requêtes entre différents clusters ClickHouse à des fins de recherche.
Requêtes distribuées peu fréquentes, effectuées manuellement.
Requêtes distribuées pour lesquelles l’ensemble des serveurs est redéfini à chaque fois.

Adresses

example01-01-1
example01-01-1:9440
example01-01-1:9000
localhost
127.0.0.1
[::]:9440
[::]:9000
[2a02:6b8:0:1111::11]:9000

Plusieurs adresses peuvent être séparées par des virgules. Dans ce cas, ClickHouse utilisera le traitement distribué et enverra la requête à toutes les adresses spécifiées (comme pour des shards contenant des données différentes). Exemple :

example01-01-1,example01-02-1

Exemples

Sélection de données à partir d’un serveur distant :

SELECT * FROM remote('127.0.0.1', db.remote_engine_table) LIMIT 3;

Ou avec les collections nommées :

CREATE NAMED COLLECTION creds AS
        host = '127.0.0.1',
        database = 'db';
SELECT * FROM remote(creds, table='remote_engine_table') LIMIT 3;

Insertion de données dans une table sur un serveur distant :

CREATE TABLE remote_table (name String, value UInt32) ENGINE=Memory;
INSERT INTO FUNCTION remote('127.0.0.1', currentDatabase(), 'remote_table') VALUES ('test', 42);
SELECT * FROM remote_table;

Migration de tables d’un système à un autre :

Cet exemple utilise une table issue d’un jeu de données d’exemple. La base de données est imdb et la table est actors.

Sur le système ClickHouse source (le système qui héberge actuellement les données)

Vérifiez le nom de la base de données source et celui de la table (imdb.actors)
show databases
show tables in imdb
Récupérez l’instruction CREATE TABLE à partir de la source :

  SELECT create_table_query
  FROM system.tables
  WHERE database = 'imdb' AND table = 'actors'

Réponse

  CREATE TABLE imdb.actors (`id` UInt32,
                            `first_name` String,
                            `last_name` String,
                            `gender` FixedString(1))
                  ENGINE = MergeTree
                  ORDER BY (id, first_name, last_name, gender);

Sur le système ClickHouse de destination

Créez la base de données de destination :
CREATE DATABASE imdb

À partir de l’instruction CREATE TABLE de la source, créez la table de destination :

CREATE TABLE imdb.actors (`id` UInt32,
                          `first_name` String,
                          `last_name` String,
                          `gender` FixedString(1))
                ENGINE = MergeTree
                ORDER BY (id, first_name, last_name, gender);

Retour au déploiement source

Insérez des données dans la nouvelle base de données et la nouvelle table créées sur le système distant. Vous aurez besoin de l’hôte, du port, du nom d’utilisateur, du mot de passe, de la base de données de destination et de la table de destination.

INSERT INTO FUNCTION
remoteSecure('remote.clickhouse.cloud:9440', 'imdb.actors', 'USER', 'PASSWORD')
SELECT * from imdb.actors

Globbing

Les motifs entre { } sont utilisés pour générer un ensemble de shards et pour spécifier des répliques. S’il y a plusieurs paires de { }, le produit cartésien des ensembles correspondants est généré. Les types de motifs suivants sont pris en charge.

{a,b,c} - Représente l’une des chaînes alternatives a, b ou c. Le motif est remplacé par a dans l’adresse du premier shard, puis par b dans l’adresse du deuxième shard, et ainsi de suite. Par exemple, example0{1,2}-1 génère les adresses example01-1 et example02-1.
{N..M} - Une plage de nombres. Ce motif génère des adresses de shards avec des indices incrémentés de N à M (inclus). Par exemple, example0{1..2}-1 génère example01-1 et example02-1.
{0n..0m} - Une plage de nombres avec des zéros en tête. Ce motif conserve les zéros en tête dans les indices. Par exemple, example{01..03}-1 génère example01-1, example02-1 et example03-1.
{a|b} - Un nombre quelconque de variantes séparées par |. Le motif spécifie des répliques. Par exemple, example01-{1|2} génère les répliques example01-1 et example01-2.

La query sera envoyée à la première réplique disponible. Cependant, pour remote, les répliques sont parcourues dans l’ordre actuellement défini par le paramètre load_balancing. Le nombre d’adresses générées est limité par le paramètre table_function_remote_max_addresses.

​Syntaxe

​Paramètres

​Valeur renvoyée

​Utilisation

​Adresses

​Exemples

​Sélection de données à partir d’un serveur distant :

​Insertion de données dans une table sur un serveur distant :

​Migration de tables d’un système à un autre :

​Sur le système ClickHouse source (le système qui héberge actuellement les données)

​Sur le système ClickHouse de destination

​Retour au déploiement source

​Globbing