Template

Entrée	Sortie	Alias
✔	✔

Description

Lorsque vous avez besoin de davantage de personnalisation que ce qu’offrent les autres formats standard, le format Template permet à l’utilisateur de définir sa propre chaîne de format avec des espaces réservés pour les valeurs, ainsi que de spécifier des règles d’échappement pour les données. Il utilise les paramètres suivants :

Paramètre	Description
`format_template_row`	Spécifie le chemin du fichier qui contient les chaînes de format pour les lignes.
`format_template_resultset`	Spécifie le chemin du fichier qui contient les chaînes de format pour les lignes
`format_template_rows_between_delimiter`	Spécifie le délimiteur entre les lignes, qui est affiché (ou attendu) après chaque ligne, sauf la dernière (`\n` par défaut)
`format_template_row_format`	Spécifie la chaîne de format des lignes en ligne.
`format_template_resultset_format`	Spécifie la chaîne de format du jeu de résultats en ligne.
Certains paramètres d’autres formats (par ex. `output_format_json_quote_64bit_integers` lors de l’utilisation de l’échappement `JSON`

Paramètres et règles d’échappement

format_template_row

Le paramètre format_template_row indique le chemin du fichier contenant les chaînes de format des lignes, selon la syntaxe suivante :

delimiter_1${column_1:serializeAs_1}delimiter_2${column_2:serializeAs_2} ... delimiter_N

Où :

Partie de la syntaxe	Description
`delimiter_i`	Un délimiteur entre les valeurs (le symbole `$` peut être échappé sous la forme `$$`)
`column_i`	Le nom ou l’index d’une colonne dont les valeurs doivent être sélectionnées ou insérées (si ce champ est vide, la colonne sera ignorée)
`serializeAs_i`	Une règle d’échappement pour les valeurs de la colonne.

Les règles d’échappement suivantes sont prises en charge :

Règle d’échappement	Description
`CSV`, `JSON`, `XML`	Semblable aux formats du même nom
`Escaped`	Semblable à `TSV`
`Quoted`	Semblable à `Values`
`Raw`	Sans échappement, semblable à `TSVRaw`
`None`	Aucune règle d’échappement — voir la note ci-dessous

Si aucune règle d’échappement n’est indiquée, None sera utilisé. XML convient uniquement à la sortie.

Prenons un exemple. Étant donné la chaîne de format suivante :

Search phrase: ${s:Quoted}, count: ${c:Escaped}, ad price: $$${p:JSON};

Les valeurs suivantes seront affichées (si vous utilisez SELECT) ou attendues (si vous utilisez INPUT), entre les délimiteurs de colonnes Search phrase:, , count:, , ad price: $ et ;, respectivement :

s (avec la règle d’échappement Quoted)
c (avec la règle d’échappement Escaped)
p (avec la règle d’échappement JSON)

Par exemple :

Lors d’un INSERT, la ligne ci-dessous correspond au modèle attendu et permettrait de lire les valeurs bathroom interior design, 2166, $3 dans les colonnes Search phrase, count, ad price.
Lors d’un SELECT, la ligne ci-dessous correspond à la sortie, en supposant que les valeurs bathroom interior design, 2166, $3 sont déjà stockées dans une table dans les colonnes Search phrase, count, ad price.

Search phrase: 'bathroom interior design', count: 2166, ad price: $3;

format_template_rows_between_delimiter

Le paramètre format_template_rows_between_delimiter spécifie le délimiteur entre les lignes, imprimé (ou attendu) après chaque ligne, sauf la dernière (\n par défaut)

format_template_resultset

Le paramètre format_template_resultset spécifie le chemin vers le fichier qui contient une chaîne de format pour le jeu de résultats. La chaîne de format du jeu de résultats a la même syntaxe qu’une chaîne de format pour les lignes. Elle permet de définir un préfixe, un suffixe et une façon d’afficher des informations supplémentaires, et contient les espaces réservés suivants au lieu des noms de colonnes :

data correspond aux lignes de données au format format_template_row, séparées par format_template_rows_between_delimiter. Cet espace réservé doit être le premier de la chaîne de format.
totals correspond à la ligne contenant les valeurs totales au format format_template_row (lors de l’utilisation de WITH TOTALS).
min correspond à la ligne contenant les valeurs minimales au format format_template_row (lorsque extremes est défini sur 1).
max correspond à la ligne contenant les valeurs maximales au format format_template_row (lorsque extremes est défini sur 1).
rows correspond au nombre total de lignes en sortie.
rows_before_limit correspond au nombre minimal de lignes qu’il y aurait eu sans LIMIT. Il n’est produit que si la requête contient LIMIT. Si la requête contient GROUP BY, rows_before_limit_at_least correspond au nombre exact de lignes qu’il y aurait eu sans LIMIT.
time correspond au temps d’exécution de la requête, en secondes.
rows_read correspond au nombre de lignes lues.
bytes_read correspond au nombre d’octets (non compressés) lus.

Les espaces réservés data, totals, min et max ne doivent pas avoir de règle d’échappement spécifiée (ou None doit être spécifié explicitement). Les autres espaces réservés peuvent avoir n’importe quelle règle d’échappement.

Si le paramètre format_template_resultset est une chaîne vide, ${data} est utilisé comme valeur par défaut.

Pour le format des requêtes d’insertion, il est possible d’ignorer certaines colonnes ou certains champs si un préfixe ou un suffixe est utilisé (voir l’exemple).

spécification en ligne

Il est souvent difficile, voire impossible, de déployer les configurations de format (définies par format_template_row, format_template_resultset) du format Template dans un répertoire sur tous les nœuds d’un cluster. De plus, le format peut être si simple qu’il n’est pas nécessaire de le placer dans un fichier. Dans ce cas, format_template_row_format (pour format_template_row) et format_template_resultset_format (pour format_template_resultset) peuvent être utilisés pour définir directement la chaîne de modèle dans la requête, plutôt que sous la forme d’un chemin vers le fichier qui la contient.

Les règles relatives aux chaînes de format et aux séquences d’échappement sont les mêmes que pour :

format_template_row lors de l’utilisation de format_template_row_format.
format_template_resultset lors de l’utilisation de format_template_resultset_format.

Exemple d’utilisation

Examinons deux exemples d’utilisation du format Template : d’abord pour sélectionner des données, puis pour en insérer.

Sélection des données

Query

SELECT SearchPhrase, count() AS c FROM test.hits GROUP BY SearchPhrase ORDER BY c DESC LIMIT 5 FORMAT Template SETTINGS
format_template_resultset = '/some/path/resultset.format', format_template_row = '/some/path/row.format', format_template_rows_between_delimiter = '\n    '

/some/path/resultset.format

<!DOCTYPE HTML>
<html> <head> <title>Search phrases</title> </head>
 <body>
  <table border="1"> <caption>Search phrases</caption>
    <tr> <th>Search phrase</th> <th>Count</th> </tr>
    ${data}
  </table>
  <table border="1"> <caption>Max</caption>
    ${max}
  </table>
  <b>Processed ${rows_read:XML} rows in ${time:XML} sec</b>
 </body>
</html>

/some/path/row.format

<tr> <td>${0:XML}</td> <td>${1:XML}</td> </tr>

Response

<!DOCTYPE HTML>
<html> <head> <title>Search phrases</title> </head>
 <body>
  <table border="1"> <caption>Search phrases</caption>
    <tr> <th>Search phrase</th> <th>Count</th> </tr>
    <tr> <td></td> <td>8267016</td> </tr>
    <tr> <td>bathroom interior design</td> <td>2166</td> </tr>
    <tr> <td>clickhouse</td> <td>1655</td> </tr>
    <tr> <td>spring 2014 fashion</td> <td>1549</td> </tr>
    <tr> <td>freeform photos</td> <td>1480</td> </tr>
  </table>
  <table border="1"> <caption>Max</caption>
    <tr> <td></td> <td>8873898</td> </tr>
  </table>
  <b>Processed 3095973 rows in 0.1569913 sec</b>
 </body>
</html>

Insertion de données

Some header
Page views: 5, User id: 4324182021466249494, Useless field: hello, Duration: 146, Sign: -1
Page views: 6, User id: 4324182021466249494, Useless field: world, Duration: 185, Sign: 1
Total rows: 2

INSERT INTO UserActivity SETTINGS
format_template_resultset = '/some/path/resultset.format', format_template_row = '/some/path/row.format'
FORMAT Template

/some/path/resultset.format

Some header\n${data}\nTotal rows: ${:CSV}\n

/some/path/row.format

Page views: ${PageViews:CSV}, User id: ${UserID:CSV}, Useless field: ${:CSV}, Duration: ${Duration:CSV}, Sign: ${Sign:CSV}

PageViews, UserID, Duration et Sign à l’intérieur des espaces réservés sont des noms de colonnes de la table. Les valeurs situées après Useless field dans les lignes et après \nTotal rows: dans le suffixe seront ignorées. Tous les délimiteurs des données d’entrée doivent correspondre strictement aux délimiteurs des chaînes de format spécifiées.

Spécification en ligne

Vous en avez assez de mettre en forme manuellement des tableaux Markdown ? Dans cet exemple, nous allons voir comment utiliser le format Template et les paramètres de spécification en ligne pour accomplir une tâche simple : effectuer un SELECT sur les noms de quelques formats ClickHouse dans la table system.formats et les mettre en forme sous forme de tableau Markdown. Cela se fait facilement à l’aide du format Template et des paramètres format_template_row_format et format_template_resultset_format. Dans les exemples précédents, nous avons spécifié les chaînes de format du jeu de résultats et des lignes dans des fichiers distincts, dont les chemins étaient indiqués à l’aide des paramètres format_template_resultset et format_template_row, respectivement. Ici, nous allons le faire en ligne, car notre modèle est trivial et ne contient que quelques | et - pour construire le tableau Markdown. Nous allons spécifier notre chaîne de modèle pour le jeu de résultats à l’aide du paramètre format_template_resultset_format. Pour créer l’en-tête du tableau, nous avons ajouté |ClickHouse Formats|\n|---|\n avant ${data}. Nous utilisons le paramètre format_template_row_format pour définir la chaîne de modèle |`{0:XML}`| pour nos lignes. Le format Template insérera nos lignes, avec le format indiqué, à l’espace réservé ${data}. Dans cet exemple, nous n’avons qu’une seule colonne, mais si vous vouliez en ajouter d’autres, vous pourriez le faire en ajoutant {1:XML}, {2:XML}… etc. à votre chaîne de modèle de ligne, en choisissant la règle d’échappement appropriée. Dans cet exemple, nous avons retenu la règle d’échappement XML.

Query

WITH formats AS
(
 SELECT * FROM system.formats
 ORDER BY rand()
 LIMIT 5
)
SELECT * FROM formats
FORMAT Template
SETTINGS
 format_template_row_format='|`${0:XML}`|',
 format_template_resultset_format='|ClickHouse Formats|\n|---|\n${data}\n'

Regardez un peu ! Nous nous sommes évité d’avoir à ajouter manuellement tous ces | et - pour créer ce tableau Markdown :

Response

|ClickHouse Formats|
|---|
|`BSONEachRow`|
|`CustomSeparatedWithNames`|
|`Prometheus`|
|`DWARF`|
|`Avro`|

Référence SQL

Types de données

Moteurs

Fonctions

Formats

Paramètres

Tables système

Lacs de données

Description

Paramètres et règles d’échappement

format_template_row

format_template_rows_between_delimiter

format_template_resultset

spécification en ligne

Exemple d’utilisation

Sélection des données

Insertion de données

Spécification en ligne

​Description

​Paramètres et règles d’échappement

​format_template_row

​format_template_rows_between_delimiter

​format_template_resultset

​spécification en ligne

​Exemple d’utilisation

​Sélection des données

​Insertion de données

​Spécification en ligne

Description

Paramètres et règles d’échappement

format_template_row

format_template_rows_between_delimiter

format_template_resultset

spécification en ligne

Exemple d’utilisation

Sélection des données

Insertion de données

Spécification en ligne