invantive documentation
Invantive Support ForumsAanmelden / Inschrijven

Syntax

De resultaatset van de laatste query kan met de volgende syntaxis naar een bestand worden geëxporteerd:

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

De opties die op format volgen, mogen in willekeurige volgorde worden opgegeven. Beschikbaar vanaf release 27.0; tot en met release 26.0 moesten ze in de hierboven getoonde volgorde worden geschreven, en elke andere volgorde werd geweigerd. Een optie die twee keer wordt opgegeven wordt geweigerd, evenals een paar opties die elkaar tegenspreken, zoals include headers samen met exclude headers.

Een waarde tussen dubbele aanhalingstekens volgt de regels van Quoting.

De meest gebruikte variant is:

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

waarmee de resultaten als Excel-werkmap worden geëxporteerd.

Uitvoerbestandsnaam

De naam van het uitvoerbestand kan worden vastgelegd met FILENAME-WITH-PATH, of worden overgenomen uit een kolom met

using filename column <COLUMN-NAME>

Uitvoerformaat

De volgende uitvoerformaten worden ondersteund:

  • xlsx: Excel xlsx-bestand.
  • csv: door komma's gescheiden waarden.
  • tsv: door tabs gescheiden waarden.
  • txt: tekst.
  • sql: SQL insert-statements.
  • html: HTML. Beschikbaar vanaf release 27.0.
  • rtf: Rich Text Format. Beschikbaar vanaf release 27.0.
  • json: JSON-formaat.
  • ndjson: NDJSON-formaat.
  • jsondataset: JSON-dataset-formaat.
  • xml: XML.
  • sqlselect: SQL select-query.
  • sqlcreatetable: SQL create table-statement. De tabelnaam kan worden opgegeven door een waarde voor TABLE-NAME-FOR-SQL op te geven.

Het statement accepteert drie namen van paginaformaten, maar geen ervan kan ermee worden geproduceerd. Elk van hen wordt geweigerd met itgenqtl034, dus er wordt geen uitvoerbestand geschreven:

  • docx: Word docx-formaat.
  • pdf: PDF-paginaformaat.
  • xps: Microsoft XPS-paginaformaat.

Deze drie worden geproduceerd door het resultatenraster van Invantive Query Tool voor Windows. Zo'n document wordt opgemaakt vanuit het raster zoals dat op het scherm wordt getoond, iets wat een instructie niet heeft: een instructie heeft een resultaatset en geen raster. T/m release 26.0 werden html en rtf op dezelfde manier geweigerd.

De uitvoerformaten csv, tsv en text staan het opgeven van scheidings- en quotegedrag toe:

  • fieldseparator: de tekens die als veldscheidingsteken worden gebruikt.
  • recordseparator: de tekens die als recordscheidingsteken worden gebruikt.
  • quotingcharacter: het teken dat als quotetekens wordt gebruikt voor veld- en recordscheidingstekens in de inhoud.
  • escapedquotingcharacter: het teken dat wordt gebruikt om het quotetekens te escapen.

De veld- en recordscheidingstekens in de inhoud kunnen ook worden verwijderd of door een waarde worden vervangen met de specificatie remove/keep.

HTML- en RTF-uitvoer

De uitvoerindeling html schrijft een document dat op zichzelf staat: de resultaten als tabel, een stijlblad dat een tabel met veel kolommen leesbaar maakt, en niets dat elders moet worden opgehaald. De uitvoerindeling rtf schrijft de resultaten als tabel in een RTF-document, waarbij de kolommen de breedte van de tekst op een staande A4-pagina delen. Een tabel met veel kolommen loopt voorbij de rechtermarge in plaats van een kolom zo te verkleinen dat niets erin leesbaar is.

Beide formaten schrijven hetzelfde document, ongeacht of de export afkomstig is van een statement of van het resultatenrooster van Invantive Query Tool voor Windows.

NDJSON-uitvoer

Het uitvoerformaat ndjson schrijft één JSON-object per rij van de resultaatset, elk op een eigen regel. Er is geen array rond de objecten en geen komma ertussen. De regels worden gescheiden door een regelinvoer, zoals de NDJSON-specificatie voorschrijft. Elke regel bevat elke kolom van de resultaatset, dus een kolom zonder waarde wordt geschreven als null en alle regels hebben dezelfde sleutels. Dat is de vorm vanaf release 27.0; t/m release 26.0 bevatte een regel alleen de kolommen met een waarde op die rij, en werden de regels gescheiden door een carriage return gevolgd door een line feed.

Een query met een for json-clausule levert een resultaatset van één kolom op met een JSON-document, en dat document wordt geëxporteerd als de waarde van die ene kolom. Laat de clausule for json weg om één regel per gegevensrij te krijgen.

Resultaatsets over bestanden splitsen

Meerdere uitvoerbestanden kunnen worden gegenereerd, elk met een ander deel van de resultaten, wanneer split on is opgegeven. Bij elke wijziging in de waarde van de kolom SPLIT-COLUMN-NAME wordt een nieuw uitvoerbestand gestart.

De formaten json, ndjson, jsondataset en xml plaatsen de rijen die bij een bestand horen vanaf release 27.0 in dat bestand; t/m release 26.0 bevatte elk van de bestanden de volledige resultaatset.

Kolommen

De lijst van op te nemen kolommen kan worden opgegeven met een lijst van kolomnamen na columns. De kolommen verschijnen in de volgorde waarin ze in de resultaatset voorkomen, ongeacht de volgorde van opgave, en een naam die met geen enkele kolom van de resultaatset overeenkomt wordt geweigerd, met itgendid085 voor CSV en itgendid782 voor de andere formaten.

De formaten json, ndjson, jsondataset en xml schrijven de opgesomde kolommen vanaf release 27.0. Tot en met release 26.0 werd een kolomlijst door json geweigerd met itgendid180, door jsondataset met itgendid090 en door xml met itgendid088, terwijl ndjson deze negeerde en alle kolommen exporteerde. Bij een xlsx-export wordt een naam die met geen enkele kolom van de resultaatset overeenkomt vanaf release 27.0 eveneens geweigerd; tot en met release 26.0 werd zo'n naam genegeerd en bleef de werkmap één kolom korter dan gevraagd. De formaten html en rtf schrijven de opgesomde kolommen vanaf release 27.0, de release waarin ze beschikbaar kwamen.

Koppen

De koppen kunnen worden ingesteld met een van de volgende drie opties:

  • include technical headers: koppen met de kolomnamen worden opgenomen (standaard).
  • exclude headers: er worden geen koppen opgenomen.
  • include headers: koppen met gebruiksvriendelijke labels worden opgenomen. Koppen worden alleen opgenomen voor de volgende formaten: csv, tsv, txt, html, rtf en xlsx.

Include/Exclude SQL

De SQL-instructie die is gebruikt om de resultaten te verzamelen, wordt standaard niet geëxporteerd. De formaten json, jsondataset en xml nemen het op als onderdeel van de auditinformatie wanneer include sql is opgegeven, en laten het weg wanneer de specificatie ontbreekt of exclude sql is opgegeven. Dat is het gedrag vanaf release 27.0; tot en met release 26.0 maakte de instructie deel uit van zo'n export, ongeacht wat was opgegeven.

Het formaat xlsx plaatst de instructie op een eigen werkblad naast de werkbladen met de rijen wanneer include sql is opgegeven. Dat werkblad noemt eerst het werkblad waar de rijen naartoe zijn gegaan en daarna de instructie die ze heeft verzameld, zodat een export van meerdere resultaatsets leesbaar blijft. Dit geldt vanaf release 27.0; tot en met release 26.0 werd de specificatie geaccepteerd op een werkmap en had deze geen effect.

De formaten html en rtf plaatsen de instructie onder de tabel met resultaten wanneer include sql is opgegeven, onder een eigen kop.

De overige formaten hebben geen ruimte voor de instructie, dus het opgeven van include sql bij een van die formaten wordt geweigerd. Elke weigering noemt het formaat:

  • ndjson: wordt geweigerd met itgendid429, omdat de uitvoer een kale stroom is van één JSON-object per rij met gegevens, zonder omhulsel eromheen.
  • csv, tsv en txt: worden geweigerd met itgendid439, omdat een bestand met gescheiden waarden bestaat uit rijen met waarden en een regel met de instructie in plaats daarvan elke lezer van het bestand zou breken.
  • sql: wordt geweigerd met itgendid440, sqlselect met itgendid441 en sqlcreatetable met itgendid442, omdat een bestand met SQL bedoeld is om opnieuw te worden uitgevoerd. De instructie in een commentaar zetten werkt niet bij een instructie van meerdere regels: elke regel na de eerste zou als SQL worden uitgevoerd.

De weigeringen gelden vanaf release 27.0. T/m release 26.0 werd de specificatie bij elk van deze formaten geaccepteerd en had ze geen effect op de uitvoer.

Rijen

Het maximale aantal rijen dat in de export wordt opgenomen, kan worden opgegeven met een limit-specificatie. Het minimale aantal rijen dat de export moet bevatten voordat er een bestand wordt aangemaakt, kan worden opgegeven met een when contains at least-specificatie.

De formaten json, ndjson, jsondataset, xml en xlsx passen de limit-specificatie toe vanaf release 27.0; t/m release 26.0 exporteerden ze elke rij van de resultaatset. De formaten html en rtf passen het toe vanaf release 27.0, de release waarin ze beschikbaar kwamen.

Voorbeelden

Om de resultaten van een query naar een Excel-bestand te exporteren wanneer er minstens één rij is:

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