Actualisation des données du dictionnaire avec LIFETIME

Configuration LIFETIME du dictionnaire pour une actualisation automatique

ClickHouse met à jour périodiquement les dictionnaires en fonction de la balise LIFETIME (définie en secondes). LIFETIME correspond à l’intervalle de mise à jour des dictionnaires entièrement téléchargés et à l’intervalle d’invalidation des dictionnaires mis en cache.

Pendant les mises à jour, l’ancienne version d’un dictionnaire reste interrogeable. Les mises à jour de dictionnaires ne bloquent pas les requêtes, sauf lors de leur chargement initial. Si une erreur se produit pendant une mise à jour, elle est consignée dans le journal du serveur, et les requêtes peuvent continuer à utiliser l’ancienne version du dictionnaire. Si la mise à jour d’un dictionnaire réussit, l’ancienne version du dictionnaire est remplacée de manière atomique.

Exemple de paramètres :

Si vous utilisez un dictionary avec ClickHouse Cloud, utilisez l’option DDL query pour créer vos dictionaries, et créez votre dictionary en tant qu’utilisateur default. Vérifiez également la liste des dictionary sources prises en charge dans le guide de compatibilité Cloud.

<dictionary>
    ...
    <lifetime>300</lifetime>
    ...
</dictionary>

ou

CREATE DICTIONARY (...)
...
LIFETIME(300)
...

Le paramètre <lifetime>0</lifetime> (LIFETIME(0)) empêche les dictionnaires de se mettre à jour.

Vous pouvez définir un intervalle de temps pour les mises à jour, et ClickHouse choisira un instant aléatoire de manière uniforme dans cette plage. Cela permet de répartir la charge sur la source du dictionnaire lors des mises à jour sur un grand nombre de serveurs.

Exemple de paramètres :

<dictionary>
    ...
    <lifetime>
        <min>300</min>
        <max>360</max>
    </lifetime>
    ...
</dictionary>

ou

LIFETIME(MIN 300 MAX 360)

Si <min>0</min> et <max>0</max>, ClickHouse ne recharge pas le dictionnaire en fonction du délai d’expiration. Dans ce cas, ClickHouse peut recharger le dictionnaire plus tôt si le fichier de configuration du dictionnaire a été modifié ou si la commande SYSTEM RELOAD DICTIONARY a été exécutée.

Lors de la mise à jour des dictionnaires, le serveur ClickHouse applique une logique différente selon le type de source :

• Pour un fichier texte, il vérifie l’heure de modification. Si elle diffère de celle enregistrée précédemment, le dictionnaire est mis à jour.
• Les dictionnaires provenant d’autres sources sont mis à jour à chaque fois par défaut.

Pour les autres sources (ODBC, PostgreSQL, ClickHouse, etc.), vous pouvez configurer une requête afin que les dictionnaires ne soient mis à jour que s’ils ont réellement changé, au lieu de l’être à chaque fois. Pour ce faire, suivez les étapes suivantes :

• La table du dictionnaire doit comporter un champ qui change systématiquement lorsque les données de la source sont mises à jour.
• Les paramètres de la source doivent spécifier une requête qui récupère le champ variable. Le serveur ClickHouse interprète le résultat de la requête comme une ligne, et si cette ligne a changé par rapport à son état précédent, le dictionnaire est mis à jour. Spécifiez la requête dans le champ <invalidate_query> des paramètres de la source.

Exemple de paramètres :

<dictionary>
    ...
    <odbc>
      ...
      <invalidate_query>SELECT update_time FROM dictionary_source where id = 1</invalidate_query>
    </odbc>
    ...
</dictionary>

ou

...
SOURCE(ODBC(... invalidate_query 'SELECT update_time FROM dictionary_source where id = 1'))
...

Pour les dictionnaires Cache, ComplexKeyCache, SSDCache et SSDComplexKeyCache, les mises à jour synchrones et asynchrones sont prises en charge.

Les dictionnaires Flat, Hashed, HashedArray et ComplexKeyHashed peuvent également ne demander que les données modifiées depuis la mise à jour précédente. Si update_field est défini dans la configuration de la source du dictionnaire, la valeur de l’horodatage de la mise à jour précédente, en secondes, sera ajoutée à la requête de données. Selon le type de source (Executable, HTTP, MySQL, PostgreSQL, ClickHouse ou ODBC), une logique différente sera appliquée à update_field avant de demander les données à une source externe.

• Si la source est HTTP, update_field est ajouté en tant que paramètre de requête, avec comme valeur l’heure de la dernière mise à jour.
• Si la source est Executable, update_field est ajouté en tant qu’argument du script exécutable, avec comme valeur l’heure de la dernière mise à jour.
• Si la source est ClickHouse, MySQL, PostgreSQL ou ODBC, une condition WHERE supplémentaire est ajoutée, dans laquelle update_field est comparé à l’heure de la dernière mise à jour avec l’opérateur supérieur ou égal.
  • Par défaut, cette condition WHERE est vérifiée au niveau le plus élevé de la requête SQL. Il est également possible de la vérifier dans n’importe quelle autre clause WHERE de la requête à l’aide du mot-clé {condition}. Exemple :
    ...
    SOURCE(CLICKHOUSE(...
        update_field 'added_time'
        QUERY '
            SELECT my_arr.1 AS x, my_arr.2 AS y, creation_time
            FROM (
                SELECT arrayZip(x_arr, y_arr) AS my_arr, creation_time
                FROM dictionary_source
                WHERE {condition}
            )'
    ))
    ...
    

Si l’option update_field est définie, l’option supplémentaire update_lag peut également être définie. La valeur de l’option update_lag est soustraite de l’heure de la mise à jour précédente avant la requête des données mises à jour.

Exemple de paramètres :

<dictionary>
    ...
        <clickhouse>
            ...
            <update_field>added_time</update_field>
            <update_lag>15</update_lag>
        </clickhouse>
    ...
</dictionary>

ou

...
SOURCE(CLICKHOUSE(... update_field 'added_time' update_lag 15))
...