Syntaxe
Le jeu de résultats de la dernière requête peut être exporté vers un fichier à l'aide de la syntaxe :
local export results
(as "<FILENAME-WITH-PATH>"|using filename column <COLUMN-NAME>)
format FORMAT
[split on <SPLIT-COLUMN-NAME>]
[tablename "<TABLE-NAME-FOR-SQL>"]
[columns <COLUMN1>[,<COLUMN2]*]
[(exclude|include|include technical) headers]
[fieldseparator "<FIELD-SEPARATOR-TEXT"]
[recordseparator "<RECORD-SEPARATOR-TEXT>"]
[quotingcharacter "<QUOTING-TEXT>"]
[escapedquotingcharacter "<ESCAPED-QUOTING-TEXT>"]
[(include|exclude) sql]
[limit <NUMBER> rows]
[when contains at least <NUMBER> rows]
[((remove|keep) field separator in content)|replace field separator in content by "<REPLACEMENT-TEXT>"]
[((remove|keep) record separator in content)|replace record separator in content by "<REPLACEMENT-TEXT>"]
Les options qui suivent format peuvent être écrites dans n'importe quel ordre. Disponible à partir de la version 27.0 ; jusqu'à la version 26.0 incluse, elles devaient être écrites dans l'ordre indiqué ci-dessus, et tout autre ordre était refusé. Une option écrite deux fois est refusée, de même qu'une paire d'options qui se contredisent, comme include headers avec exclude headers.
Une valeur entre guillemets doubles suit les règles de Quoting.
La variante la plus fréquemment utilisée est :
local export results as "c:\temp\output.xlsx" format xlsx
qui exporte les résultats sous forme de classeur Excel.
Nom du fichier de sortie
Le nom du fichier de sortie peut être codé en dur à l'aide de FILENAME-WITH-PATH ou extrait d'une colonne à l'aide de
using filename column <COLUMN-NAME>
Format de sortie
Les formats de sortie suivants sont pris en charge :
xlsx: fichier Excel xlsx.csv: valeurs séparées par des virgules.tsv: valeurs séparées par des tabulations.txt: texte.sql: instructions SQL insert.html: HTML. Disponible à partir de la version 27.0.rtf: Rich Text Format. Disponible à partir de la version 27.0.json: format JSON.ndjson: format NDJSON.jsondataset: format d'ensemble de données JSON.xml: XML.sqlselect: requête SQL select.sqlcreatetable: instruction SQL create table. Le nom de la table peut être spécifié en indiquant une valeur pourTABLE-NAME-FOR-SQL.
Trois noms de formats de page sont acceptés par l'instruction, mais aucun d'eux ne peut être produit par celle-ci. Chacune d'elles est refusée avec itgenqtl034, de sorte qu'aucun fichier de sortie n'est écrit :
docx: format Word docx.pdf: format de page PDF.xps: format de page Microsoft XPS.
Ces trois formats sont produits par la grille de résultats d'Invantive Query Tool pour Windows. Un tel document est mis en forme à partir de la grille telle qu'elle est affichée à l'écran, ce qu'une instruction ne possède pas : une instruction a un jeu de résultats et pas de grille. Jusqu'à la version 26.0 incluse, html et rtf étaient refusés de la même manière.
Les formats de sortie csv, tsv et text permettent de spécifier le comportement des séparateurs et des guillemets :
fieldseparator: les caractères à utiliser comme séparateur de champs.recordseparator: les caractères à utiliser comme séparateur d'enregistrements.quotingcharacter: le caractère à utiliser comme guillemet pour les séparateurs de champs et d'enregistrements dans le contenu.escapedquotingcharacter: le caractère à utiliser pour échapper le caractère de guillemet.
Les séparateurs de champs et d'enregistrements dans le contenu peuvent aussi être supprimés ou remplacés par une valeur à l'aide de la spécification remove/keep.
Sortie HTML et RTF
Le format de sortie html produit un document autonome : les résultats sous forme de tableau, une feuille de style qui rend lisible un tableau de nombreuses colonnes, et rien qui doive être récupéré ailleurs. Le format de sortie rtf écrit les résultats sous forme de tableau dans un document RTF, dans lequel les colonnes se partagent la largeur du texte sur une page A4 en orientation portrait. Un tableau de nombreuses colonnes dépasse la marge droite plutôt que de réduire une colonne au point que rien de son contenu ne soit lisible.
Les deux formats produisent le même document, que l'export provienne d'une instruction ou de la grille de résultats d'Invantive Query Tool pour Windows.
Sortie NDJSON
Le format de sortie ndjson écrit un objet JSON par ligne du jeu de résultats, chacun sur une ligne distincte. Il n'y a pas de tableau autour des objets ni de virgule entre eux. Les lignes sont séparées par un saut de ligne, comme le prescrit la spécification NDJSON. Chaque ligne contient toutes les colonnes du jeu de résultats, de sorte qu'une colonne sans valeur est écrite sous la forme null et que toutes les lignes portent les mêmes clés. Telle est la forme à partir de la version 27.0; jusqu'à la version 26.0 incluse, une ligne ne contenait que les colonnes ayant une valeur sur cette ligne, et les lignes étaient séparées par un retour chariot suivi d'un saut de ligne.
Une requête avec une clause for json produit un jeu de résultats d'une seule colonne contenant un document JSON, et ce document est exporté comme valeur de cette colonne unique. Omettez la clause for json pour obtenir une ligne par ligne de données.
Répartir les jeux de résultats sur plusieurs fichiers
Plusieurs fichiers de sortie peuvent être générés, chacun avec une partie différente des résultats, lorsque split on est spécifié. Un nouveau fichier de sortie est démarré à chaque changement de valeur de la colonne SPLIT-COLUMN-NAME.
Les formats json, ndjson, jsondataset et xml placent les lignes appartenant à un fichier dans ce fichier à partir de la version 27.0; jusqu'à la version 26.0 incluse, chacun des fichiers contenait le jeu de résultats complet.
Colonnes
La liste des colonnes à inclure peut être spécifiée à l'aide d'une liste de noms de colonnes indiquée après columns. Les colonnes apparaissent dans l'ordre où elles figurent dans le jeu de résultats, quel que soit l'ordre dans lequel elles sont listées, et un nom ne correspondant à aucune colonne du jeu de résultats est refusé, avec itgendid085 pour le CSV et itgendid782 pour les autres formats.
Les formats json, ndjson, jsondataset et xml écrivent les colonnes listées à partir de la version 27.0. Jusqu'à la version 26.0 incluse, une liste de colonnes était refusée par json avec itgendid180, par jsondataset avec itgendid090 et par xml avec itgendid088, tandis que ndjson l'ignorait et exportait toutes les colonnes. Lors d'un export xlsx, un nom ne correspondant à aucune colonne du jeu de résultats est également refusé à partir de la version 27.0; jusqu'à la version 26.0 incluse, un tel nom était ignoré et le classeur comportait une colonne de moins que demandé. Les formats html et rtf écrivent les colonnes listées à partir de la version 27.0, version dans laquelle ils sont devenus disponibles.
En-têtes
Les en-têtes peuvent être configurés à l'aide de l'une des trois options suivantes :
include technical headers: les en-têtes avec les noms des colonnes sont inclus (par défaut).exclude headers: aucun en-tête n'est inclus.include headers: les en-têtes avec des libellés conviviaux sont inclus. Les en-têtes ne sont inclus que pour les formats suivants :csv,tsv,txt,html,rtfetxlsx.
Inclure/Exclure SQL
L'instruction SQL utilisée pour collecter les résultats n'est par défaut pas exportée. Les formats json, jsondataset et xml l'incluent dans les informations d'audit lorsque include sql est spécifié, et l'omettent lorsque la spécification est absente ou que exclude sql est spécifié. Tel est le comportement à partir de la version 27.0; jusqu'à la version 26.0 incluse, l'instruction faisait partie d'un tel export quelle que soit la spécification.
Le format xlsx place l'instruction sur une feuille de calcul distincte lorsque include sql est spécifié, à côté des feuilles contenant les lignes. Cette feuille de calcul indique d'abord la feuille vers laquelle les lignes ont été envoyées, puis l'instruction qui les a collectées, afin qu'un export de plusieurs jeux de résultats reste lisible. Cela s'applique à partir de la version 27.0; jusqu'à la version 26.0 incluse, la spécification était acceptée pour un classeur et sans effet.
Les formats html et rtf placent l'instruction sous le tableau des résultats lorsque include sql est spécifié, sous un titre distinct.
Les autres formats n'ont pas de place pour l'instruction ; spécifier include sql pour l'un d'eux est donc refusé. Chaque refus indique le format concerné :
ndjson: refusé avecitgendid429, car la sortie est un simple flux d'un objet JSON par ligne de données, sans enveloppe autour.csv,tsvettxt: refusés avecitgendid439, car un fichier de valeurs séparées est constitué de lignes de valeurs et une ligne portant l'instruction à la place casserait tous les lecteurs du fichier.sql: refusé avecitgendid440,sqlselectavecitgendid441etsqlcreatetableavecitgendid442, car un fichier SQL est destiné à être rejoué. Placer l'instruction dans un commentaire ne fonctionne pas pour une instruction de plusieurs lignes : chaque ligne après la première serait exécutée comme SQL.
Les refus s'appliquent à partir de la version 27.0. Jusqu'à la version 26.0 incluse, la spécification était acceptée pour chacun de ces formats et sans effet sur la sortie.
Enregistrements
Le nombre maximal de lignes à inclure dans l'export peut être spécifié à l'aide d'une spécification limit. Le nombre minimal de lignes que l'export doit contenir pour créer un fichier peut être spécifié à l'aide d'une spécification when contains at least.
Les formats json, ndjson, jsondataset, xml et xlsx appliquent la spécification limit à partir de la version 27.0; jusqu'à la version 26.0 incluse, ils exportaient chaque ligne du jeu de résultats. Les formats html et rtf l'appliquent à partir de la version 27.0, version dans laquelle ils sont devenus disponibles.
Exemples
Pour exporter les résultats d'une requête vers un fichier Excel lorsqu'il y a au moins une ligne :
select *
from dual@DataDictionary
local define OUT_PATH "c:\temp"
local define MY_FILE_NAME "my-file.xlsx"
local export results as "${OUT_PATH}${system:directoryseparator}${MY_FILE_NAME}" format xlsx include headers when contains at least 1 rows