invantive documentation
Forum di supporto InvantiveAccedi / Registrati

Sintassi

Il result set dell'ultima query può essere esportato in un file usando la sintassi:

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>"]

Le opzioni che seguono format possono essere scritte in qualsiasi ordine. Disponibile a partire dalla release 27.0; fino alla release 26.0 inclusa dovevano essere scritti nell'ordine mostrato sopra e qualsiasi altro ordine veniva rifiutato. Un'opzione scritta due volte viene rifiutata, così come una coppia di opzioni in contraddizione tra loro, come include headers insieme a exclude headers.

Un valore tra doppi apici segue le regole di Quoting.

La variante più usata è:

local export results as "c:\temp\output.xlsx" format xlsx

che esporta i risultati come cartella di lavoro Excel.

Nome file di output

Il nome del file di output può essere specificato in modo fisso usando FILENAME-WITH-PATH oppure essere preso da una colonna usando

using filename column <COLUMN-NAME>

Formato di output

I seguenti formati di output sono supportati:

  • xlsx: file Excel xlsx.
  • csv: valori separati da virgola.
  • tsv: valori separati da tabulazione.
  • txt: testo.
  • sql: istruzioni SQL insert.
  • html: HTML. Disponibile a partire dalla versione 27.0.
  • rtf: Rich Text Format. Disponibile a partire dalla versione 27.0.
  • json: formato JSON.
  • ndjson: formato NDJSON.
  • jsondataset: formato data set JSON.
  • xml: XML.
  • sqlselect: query SQL select.
  • sqlcreatetable: istruzione SQL create table. Il nome della tabella può essere specificato indicando un valore per TABLE-NAME-FOR-SQL.

Tre nomi di formati pagina sono accettati dall'istruzione, ma nessuno di essi può essere prodotto da essa. Ciascuno di essi viene rifiutato con itgenqtl034, quindi non viene scritto alcun file di output:

  • docx: formato Word docx.
  • pdf: formato pagina PDF.
  • xps: formato pagina Microsoft XPS.

Questi tre sono prodotti dalla griglia dei risultati di Invantive Query Tool per Windows. Un documento del genere viene impaginato a partire dalla griglia così come appare sullo schermo, cosa che un'istruzione non ha: un'istruzione ha un result set e nessuna griglia. Fino alla release 26.0 inclusa html e rtf venivano rifiutati allo stesso modo.

I formati di output csv, tsv e text consentono di specificare il comportamento di separazione e delimitazione:

  • fieldseparator: i caratteri da usare come separatore di campo.
  • recordseparator: i caratteri da usare come separatore di record.
  • quotingcharacter: il carattere da usare come carattere di citazione per il separatore di campo e di record nel contenuto.
  • escapedquotingcharacter: il carattere da usare per eseguire l'escape del carattere di citazione.

I separatori di campo e di record presenti nel contenuto possono anche essere rimossi o sostituiti con un valore utilizzando la specifica remove/keep.

Output HTML e RTF

Il formato di output html scrive un documento autonomo: i risultati come tabella, un foglio di stile che rende leggibile una tabella di molte colonne e nulla che debba essere recuperato altrove. Il formato di output rtf scrive i risultati come tabella di un documento RTF, in cui le colonne condividono la larghezza del testo su una pagina A4 in verticale. Una tabella con molte colonne supera il margine destro anziché ridurre una colonna al punto che nulla al suo interno sia leggibile.

Entrambi i formati scrivono lo stesso documento sia che l'esportazione provenga da un'istruzione sia dalla griglia dei risultati di Invantive Query Tool per Windows.

Output NDJSON

Il formato di output ndjson scrive un oggetto JSON per ogni riga del result set, ciascuno su una riga propria. Non ci sono parentesi quadre attorno agli oggetti né virgole tra di essi. Le righe sono separate da un line feed, come prescrive la specifica NDJSON. Ogni riga contiene tutte le colonne del set di risultati, quindi una colonna senza valore viene scritta come null e tutte le righe hanno le stesse chiavi. Questa è la forma a partire dalla release 27.0; fino alla release 26.0 inclusa una riga conteneva solo le colonne con un valore in quella riga, e le righe erano separate da un carriage return seguito da un line feed.

Una query con una clausola for json restituisce un result set di una sola colonna contenente un documento JSON, e tale documento viene esportato come valore di quella unica colonna. Ometti la clausola for json per ottenere una riga per ogni riga di dati.

Suddividere i result set in più file

È possibile generare più file di output, ciascuno con una parte diversa dei risultati, quando si specifica split on. Un nuovo file di output viene avviato a ogni variazione del valore della colonna SPLIT-COLUMN-NAME.

I formati json, ndjson, jsondataset e xml inseriscono nel file le righe appartenenti a quel file a partire dalla release 27.0; fino alla release 26.0 inclusa ciascuno dei file conteneva l'intero result set.

Colonne

L'elenco delle colonne da includere può essere specificato usando un elenco di nomi di colonna indicato dopo columns. Le colonne compaiono nell'ordine in cui si presentano nel result set, indipendentemente dall'ordine in cui sono elencate, e un nome che non corrisponde ad alcuna colonna del result set viene rifiutato, con itgendid085 per CSV e itgendid782 per gli altri formati.

I formati json, ndjson, jsondataset e xml scrivono le colonne elencate a partire dalla release 27.0. Fino alla release 26.0 inclusa, un elenco di colonne veniva rifiutato da json con itgendid180, da jsondataset con itgendid090 e da xml con itgendid088, mentre ndjson lo ignorava ed esportava tutte le colonne. In un'esportazione xlsx un nome che non corrisponde ad alcuna colonna del result set viene rifiutato anche a partire dalla release 27.0; fino alla release 26.0 inclusa tale nome veniva ignorato e la cartella di lavoro risultava con una colonna in meno rispetto a quanto richiesto. I formati html e rtf scrivono le colonne elencate a partire dalla versione 27.0, la versione in cui sono diventati disponibili.

Intestazioni

Le intestazioni possono essere configurate usando una delle seguenti tre opzioni:

  • include technical headers: vengono inclusi gli intestazioni con i nomi delle colonne (predefinito).
  • exclude headers: non vengono inclusi intestazioni.
  • include headers: vengono incluse le intestazioni con etichette intuitive per l'utente. Le intestazioni sono incluse solo per i seguenti formati: csv, tsv, txt, html, rtf e xlsx.

Includere/Escludere SQL

L'istruzione SQL utilizzata per raccogliere i risultati, per impostazione predefinita, non viene esportata. I formati json, jsondataset e xml la includono come parte delle informazioni di audit quando è specificato include sql, e la omettono quando la specifica è assente o è specificato exclude sql. Questo è il comportamento a partire dalla release 27.0; fino alla release 26.0 inclusa, l'istruzione faceva parte di tale esportazione indipendentemente da quanto specificato.

Il formato xlsx inserisce l'istruzione in un foglio di lavoro dedicato quando si specifica include sql, accanto ai fogli di lavoro che contengono le righe. Quel foglio di lavoro indica il foglio in cui sono finite le righe e poi l'istruzione che le ha raccolte, così un'esportazione di più result set resta leggibile. Questo vale a partire dalla release 27.0; fino alla release 26.0 inclusa la specifica veniva accettata su una cartella di lavoro senza alcun effetto.

I formati html e rtf inseriscono l'istruzione sotto la tabella dei risultati quando è specificato include sql, sotto un'intestazione propria.

Gli altri formati non hanno spazio per l'istruzione, quindi specificare include sql su uno di essi viene rifiutato. Ogni rifiuto indica il formato:

  • ndjson: rifiutato insieme a itgendid429, poiché l'output è un flusso semplice di un oggetto JSON per riga di dati, senza un involucro che lo racchiuda.
  • csv, tsv e txt: rifiutati con itgendid439, poiché un file di valori separati è costituito da righe di valori, e una riga contenente l'istruzione invece comprometterebbe ogni programma che legge il file.
  • sql: rifiutato con itgendid440; sqlselect con itgendid441 e sqlcreatetable con itgendid442, poiché un file SQL è destinato a essere rieseguito. Inserire l'istruzione in un commento non funziona con un'istruzione su più righe: ogni riga dopo la prima verrebbe eseguita come SQL.

I rifiuti valgono a partire dalla versione 27.0 in poi. Fino alla release 26.0 inclusa la specifica veniva accettata su ciascuno di questi formati senza alcun effetto sull'output.

Righe

Il numero massimo di righe da includere nell'esportazione può essere specificato usando una specifica limit. Il numero minimo di righe che l'esportazione deve contenere affinché venga creato un file può essere specificato usando una specifica when contains at least.

I formati json, ndjson, jsondataset, xml e xlsx applicano la specifica limit a partire dalla release 27.0; fino alla release 26.0 inclusa esportavano ogni riga del result set. I formati html e rtf la applicano a partire dalla release 27.0, la release in cui sono diventati disponibili.

Esempi

Per esportare i risultati di una query in un file Excel quando c'è almeno una riga:

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