system.documentation

Table système qui regroupe, dans une seule table, la documentation embarquée des composants du système documentés de manière uniforme (fonctions, moteurs de table, types de données, etc.), avec la documentation de référence rendue en Markdown.

​

Description

Collecte dans une seule table la documentation embarquée des composants documentés de manière uniforme du système. Chaque ligne correspond à une entité (une fonction, un moteur de table, un type de données, etc.) et contient sa documentation de référence embarquée au format Markdown. Ce contenu sert de base à la documentation générée du site web et aux tables system.* propres à chaque type ; les pages du site web peuvent ajouter des préambules ou des conseils uniquement en MDX en dehors de leurs corps générés.

La description est construite à partir des parties structurées de la documentation embarquée (description, syntax, arguments, exemples, etc.), de sorte qu’une seule colonne contient la documentation embarquée complète d’une entité. Lorsque la documentation embarquée contient toute la page de référence dans sa description (comme c’est le cas pour les composants dont les pages du site web sont générées automatiquement à partir de celle-ci : moteurs de table, moteurs de base de données, types de données, formats, fonctions de table), la page est publiée telle quelle, sans ajouter de sections composées à partir des champs de métadonnées structurées — le corps de la page couvre déjà ces informations. Les alias sont présentés sous la forme d’un bref renvoi vers l’entité canonique, par ex. Alias of `trunc`.

Cette table regroupe, d’une certaine manière, les informations disponibles dans les tables de documentation propres à chaque type (system.functions, system.table_engines, system.data_type_families, entre autres). Elle est notamment conçue pour servir de base à une commande help interactive dans le client, mais elle est également utile à elle seule.

Les types d’entités suivants sont collectés (la valeur de la colonne type est indiquée entre parenthèses) :

• Fonctions (Function)
• Fonctions d’agrégation (Aggregate Function)
• Fonctions de table (Table Function)
• Moteurs de table (Table Engine)
• Moteurs de base de données (Database Engine)
• Types de données (Data Type)
• Structures de dictionnaire (Dictionary Layout)
• Sources de dictionnaire (Dictionary Source)
• Combinateurs de fonctions d’agrégation (Aggregate Function Combinator)
• Types d’index de saut de données (Data Skipping Index)
• Types de disque (Disk Type)
• Paramètres (Setting)
• Paramètres MergeTree (MergeTree Setting)
• Paramètres du serveur (Server Setting)
• Formats (Format)
• Codecs de compression (Compression Codec)
• Événements de profil (Profile Event)
• Métriques actuelles (Current Metric)
• Métriques asynchrones (Asynchronous Metric)
• Tables système (System Table)
• Instructions SQL (Statement)

Pour les paramètres (de tout type), la documentation correspond à la description du paramètre, ainsi qu’à son type et à sa valeur par défaut ; les paramètres obsolètes ne sont pas exposés. Elle contient également l’historique des modifications de la valeur par défaut du paramètre au fil des versions de ClickHouse : la version dans laquelle le paramètre a été introduit et chaque modification ultérieure de sa valeur par défaut, avec la valeur précédente, la nouvelle valeur et la raison de la modification. Il s’agit des mêmes données qui servent de base au paramètre compatibility et à system.settings_changes ; elles couvrent donc les modifications enregistrées depuis l’introduction de ce mécanisme : un ancien paramètre dont la valeur par défaut n’a jamais changé n’a pas d’historique, pas plus que les paramètres du serveur, que compatibility ne couvre pas. Une modification enregistrée sous un alias d’un paramètre appartient à l’historique de ce paramètre, de la même manière que compatibility l’applique ; ainsi, l’historique d’un paramètre qui a été renommé n’est pas interrompu lors du renommage. L’exception est un enregistrement écrit sous un alias dans le seul but d’enregistrer cet alias, qui appartient uniquement à l’historique de l’alias. Un alias contient l’historique de son propre nom : chaque enregistrement écrit sous celui-ci, ainsi que l’enregistrement qui l’a déclaré comme alias, que le fichier d’historique écrit parfois sous un autre nom du même paramètre.

Pour les tables système, la description, les exemples et les éléments associés sont stockés dans le commentaire de métadonnées de la table à l’aide de marqueurs de section légers. Le corps complet de la page générée est assemblé à partir de ce commentaire et du schéma de colonnes en vigueur. Les catalogues d’événements et de métriques sont générés à partir de leurs registres, de sorte que les détails générés restent synchronisés avec le binaire en cours d’exécution.

Pour les instructions SQL, la documentation est générée à partir des champs structurés exposés par system.statements, y compris la syntaxe et les instructions associées lorsque ces sections ne font pas déjà partie de la description détenue par la source.

La colonne source contient un chemin source pour l’entité, relatif à la racine du dépôt. Pour la plupart des entités, il est capturé automatiquement à l’endroit où l’objet de documentation est construit (le point d’enregistrement du composant) ; pour les tables système, il s’agit du fichier qui détient la documentation embarquée (comme attachSystemTables.cpp, SystemLog.h, ou un détenteur de documentation dédié), et pour les types documentés chacun dans un fichier source unique (comme les paramètres, les événements de profil et les métriques actuelles), il s’agit de ce fichier.

​

Colonnes

• name (String) — Le nom de l’entité, par ex. domainWithoutWWW ou MergeTree.
• type (Enum8(‘Function’ = 1, ‘Aggregate Function’ = 2, ‘Table Function’ = 3, ‘Table Engine’ = 4, ‘Database Engine’ = 5, ‘Data Type’ = 6, ‘Dictionary Layout’ = 7, ‘Dictionary Source’ = 8, ‘Aggregate Function Combinator’ = 9, ‘Data Skipping Index’ = 10, ‘Disk Type’ = 11, ‘Setting’ = 12, ‘MergeTree Setting’ = 13, ‘Server Setting’ = 14, ‘Format’ = 15, ‘Compression Codec’ = 16, ‘Profile Event’ = 17, ‘Current Metric’ = 18, ‘Asynchronous Metric’ = 19, ‘System Table’ = 20, ‘Statement’ = 21)) — Le type de l’entité, par ex. Function ou Table Engine.
• description (String) — La documentation de référence de l’entité, au format Markdown, assemblée à partir de la documentation embarquée et incluant la syntaxe, les exemples et d’autres parties structurées, le cas échéant. Les pages du site web peuvent ajouter des préambules ou des indications propres au MDX en dehors des corps générés.
• source (String) — Le chemin d’accès au fichier source où la documentation de l’entité est définie, relatif à la racine du dépôt. Vide si l’emplacement de la source est inconnu.

​

Exemple

Consultez la documentation d’une entité donnée :

Query

SELECT description
FROM system.documentation
WHERE type = 'Table Engine' AND name = 'MergeTree'
FORMAT TSVRaw;

Le même nom peut désigner plusieurs types d’entités (par exemple, il existe à la fois une fonction de table file et une source de dictionnaire file) ; il est donc pratique de rechercher un nom dans tous les types :

Query

SELECT type, name
FROM system.documentation
WHERE name = 'file'
ORDER BY type;

Comptez les entités documentées de chaque type :

Query

SELECT type, count()
FROM system.documentation
GROUP BY type
ORDER BY count() DESC;

Découvrez dans quelle version un paramètre a été introduit et comment sa valeur par défaut a évolué depuis :

Query

SELECT description
FROM system.documentation
WHERE type = 'Setting' AND name = 'async_insert_max_data_size'
FORMAT TSVRaw;

​

Voir aussi

• system.functions — Fonctions standard et d’agrégation.
• system.table_functions — Fonctions de table.
• system.table_engines — Moteurs de table.
• system.database_engines — Moteurs de base de données.
• system.data_type_families — Types de données.
• system.disk_types — Types de disques.
• system.settings — Paramètres.
• system.merge_tree_settings — Paramètres MergeTree.
• system.server_settings — Paramètres du serveur.
• system.settings_changes — Historique des modifications des valeurs par défaut des paramètres.
• system.formats — Formats.