invantive documentation
Foros de Soporte de InvantiveIniciar Sesión / Registrarse

Sintaxis

El conjunto de resultados de la última consulta se puede exportar a un archivo usando la sintaxis:

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

Las opciones que siguen a format pueden escribirse en cualquier orden. Disponible desde la versión 27.0; hasta la versión 26.0 inclusive, debían escribirse en el orden indicado arriba y cualquier otro orden era rechazado. Una opción escrita dos veces se rechaza, y también un par de opciones que se contradicen entre sí, como include headers junto con exclude headers.

Un valor entre comillas dobles sigue las reglas de Quoting.

La variante más utilizada es:

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

que exporta los resultados como un libro de Excel.

Nombre del archivo de salida

El nombre del archivo de salida puede indicarse fijo usando FILENAME-WITH-PATH o tomarse de una columna usando

using filename column <COLUMN-NAME>

Formato de salida

Los siguientes formatos de salida son compatibles:

  • xlsx: archivo Excel xlsx.
  • csv: valores separados por comas.
  • tsv: valores separados por tabulaciones.
  • txt: texto.
  • sql: instrucciones SQL insert.
  • html: HTML. Disponible a partir de la versión 27.0.
  • rtf: formato Rich Text Format. Disponible a partir de la versión 27.0.
  • json: formato JSON.
  • ndjson: formato NDJSON.
  • jsondataset: formato de conjunto de datos JSON.
  • xml: XML.
  • sqlselect: consulta SQL select.
  • sqlcreatetable: instrucción SQL create table. El nombre de la tabla puede especificarse dando un valor a TABLE-NAME-FOR-SQL.

La instrucción acepta tres nombres de formato de página, pero ninguno de ellos puede producirlo. Cada uno de ellos se rechaza con itgenqtl034, por lo que no se escribe ningún archivo de salida:

  • docx: formato Word docx.
  • pdf: formato de página PDF.
  • xps: formato de página Microsoft XPS.

Estos tres son producidos por la cuadrícula de resultados de Invantive Query Tool para Windows. Un documento así se diseña a partir de la cuadrícula tal como se muestra en pantalla, algo que una instrucción no tiene: una instrucción tiene un conjunto de resultados y no cuadrícula. Hasta la versión 26.0 inclusive, html y rtf eran rechazados de la misma forma.

Los formatos csv, tsv y text permiten especificar el comportamiento de separadores y entrecomillado:

  • fieldseparator: los caracteres que se usan como separador de campo.
  • recordseparator: los caracteres que se usarán como separador de registros.
  • quotingcharacter: el carácter que se usará como carácter de entrecomillado para el separador de campos y de registros en el contenido.
  • escapedquotingcharacter: el carácter que se usa para escapar el carácter de entrecomillado.

Los separadores de campos y de registros en el contenido también pueden eliminarse o sustituirse por un valor mediante la especificación remove/keep.

Salida HTML y RTF

El formato de salida html escribe un documento autosuficiente: los resultados como tabla, una hoja de estilos que hace legible una tabla de muchas columnas, y nada que deba obtenerse de otro lugar. El formato de salida rtf escribe los resultados como una tabla de un documento RTF, en la que las columnas comparten el ancho del texto en una página A4 vertical. Una tabla de muchas columnas sobrepasa el margen derecho en lugar de reducir una columna hasta el punto en que nada de su contenido se pueda leer.

Ambos formatos escriben el mismo documento tanto si la exportación procede de una instrucción como si procede de la cuadrícula de resultados de Invantive Query Tool para Windows.

Salida NDJSON

El formato de salida ndjson escribe un objeto JSON por fila del conjunto de resultados, cada uno en una línea propia. No hay un array alrededor de los objetos ni coma entre ellos. Las líneas se separan con un salto de línea, como prescribe la especificación NDJSON. Cada línea contiene todas las columnas del conjunto de resultados, por lo que una columna sin valor se escribe como null y todas las líneas llevan las mismas claves. Así es el formato desde la versión 27.0 en adelante; hasta la versión 26.0 inclusive, una línea contenía solo las columnas con valor en esa fila, y las líneas se separaban mediante un retorno de carro seguido de un salto de línea.

Una consulta con una cláusula for json produce un conjunto de resultados de una columna que contiene un documento JSON, y ese documento se exporta como el valor de esa única columna. Omita la cláusula for json para obtener una línea por fila de datos.

Dividir los conjuntos de resultados en varios archivos

Se pueden generar varios archivos de salida, cada uno con una parte diferente de los resultados, cuando se especifica split on. Se inicia un nuevo archivo de salida con cada cambio en el valor de la columna SPLIT-COLUMN-NAME.

Los formatos json, ndjson, jsondataset y xml colocan las filas que pertenecen a un archivo en ese archivo a partir de la versión 27.0; hasta la versión 26.0 incluida, cada uno de los archivos contenía el conjunto completo de resultados.

Columnas

La lista de columnas a incluir puede especificarse mediante una lista de nombres de columna indicada después de columns. Las columnas aparecen en el orden en que se presentan en el conjunto de resultados, sin importar el orden en que se indiquen, y un nombre que no coincida con ninguna columna del conjunto de resultados es rechazado, con itgendid085 para CSV y itgendid782 para los demás formatos.

Los formatos json, ndjson, jsondataset y xml escriben las columnas indicadas desde la versión 27.0 en adelante. Hasta la versión 26.0 inclusive, json rechazaba una lista de columnas con itgendid180, jsondataset rechazaba una lista con itgendid090 y xml la rechazaba con itgendid088, mientras que ndjson la ignoraba y exportaba todas las columnas. En una exportación xlsx, un nombre que no coincide con ninguna columna del conjunto de resultados se rechaza a partir de la versión 27.0; hasta la versión 26.0 incluida, dicho nombre se ignoraba y dejaba el libro con una columna menos de las solicitadas. Los formatos html y rtf escriben las columnas indicadas desde la versión 27.0, la versión en que estuvieron disponibles.

Encabezados

Los encabezados pueden configurarse usando una de las tres opciones siguientes:

  • include technical headers: se incluyen encabezados con los nombres de las columnas (predeterminado).
  • exclude headers: no se incluyen encabezados.
  • include headers: se incluyen encabezados con etiquetas fáciles de entender. Los encabezados solo se incluyen para los siguientes formatos: csv, tsv, txt, html, rtf y xlsx.

Incluir/Excluir SQL

La instrucción SQL usada para recopilar los resultados no se exporta por defecto. Los formatos json, jsondataset y xml lo incluyen como parte de la información de auditoría cuando se especifica include sql, y lo omiten cuando la especificación está ausente o se especifica exclude sql. Ese es el comportamiento a partir de la versión 27.0; hasta la versión 26.0 incluida, la instrucción formaba parte de dicha exportación independientemente de lo especificado.

El formato xlsx coloca la instrucción en una hoja de cálculo propia cuando se especifica include sql, junto a las hojas que contienen las filas. Esa hoja de cálculo indica la hoja en la que se escribieron las filas y después la instrucción que las recopiló, de modo que una exportación de varios conjuntos de resultados siga siendo legible. Esto se aplica desde la versión 27.0 en adelante; hasta la versión 26.0 inclusive, la especificación se aceptaba en un libro y no tenía ningún efecto.

Los formatos html y rtf colocan la instrucción debajo de la tabla de resultados cuando se especifica include sql, bajo un encabezado propio.

Los demás formatos no tienen espacio para la instrucción, por lo que especificar include sql en cualquiera de ellos es rechazado. Cada rechazo indica el formato:

  • ndjson: rechazado con itgendid429, ya que la salida es un flujo simple de un objeto JSON por cada fila de datos, sin ningún envoltorio a su alrededor.
  • csv, tsv y txt: rechazados con itgendid439, ya que un archivo de valores separados es un conjunto de filas de valores, y una línea con la instrucción en su lugar rompería a cualquier lector del archivo.
  • sql: rechazado con itgendid440, sqlselect con itgendid441 y sqlcreatetable con itgendid442, ya que un archivo de SQL está pensado para reproducirse. Poner la instrucción en un comentario no funciona con una instrucción de varias líneas: cada línea después de la primera se ejecutaría como SQL.

Los rechazos se aplican desde la versión 27.0 en adelante. Hasta la versión 26.0 incluida, la especificación se aceptaba en cada uno de estos formatos y no tenía efecto en la salida.

Filas

El número máximo de filas a incluir en la exportación se puede especificar mediante una especificación limit. El número mínimo de filas que debe contener la exportación para que cree un archivo puede especificarse usando una especificación when contains at least.

Los formatos json, ndjson, jsondataset, xml y xlsx aplican la especificación limit a partir de la versión 27.0; hasta la versión 26.0 incluida exportaban todas las filas del conjunto de resultados. Los formatos html y rtf lo aplican desde la versión 27.0, la versión en la que se pusieron a disposición.

Ejemplos

Para exportar los resultados de una consulta a un archivo de Excel cuando hay al menos una fila:

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