Sentencia EXPLAIN

Invocación

Esta sentencia puede incorporarse en un programa de aplicación o emitirse de forma interactiva. Se trata de una sentencia ejecutable que puede prepararse de forma dinámica.

La sentencia que se debe explicar no se ejecuta.

Autorización

• Autorización DATAACCESS que permite una sentencia INSERT, UPDATE, DELETE o SELECT.
• El privilegio INSERT sobre las tablas de Explain y al menos en una de las autorizaciones siguientes:
  • Todos los privilegios necesarios para ejecutar la sentencia explicable especificada en la sentencia EXPLAIN (por ejemplo, si se utiliza una sentencia DELETE como la sentencia explicable, se aplican las normas de autorización de la sentencia DELETE cuando ésta se explica).
  • Autorización EXPLAIN
  • Autorización SQLADM
  • Autorización DBADM

Sintaxis

Descripción

PLAN SELECTION

Indica que la información de la fase de selección del plan de la compilación de consultas debe insertarse en las tablas de Explain.

ALL

La especificación de ALL es equivalente a especificar PLAN SELECTION.

PLAN

La opción PLAN proporciona la tolerancia de la sintaxis para las aplicaciones de bases de datos existentes de otros sistemas. La especificación de PLAN es equivalente a especificar PLAN SELECTION.

FOR SNAPSHOT

Esta cláusula indica que sólo debe tomarse una instantánea de explicación y colocarla en la columna SNAPSHOT de la tabla EXPLAIN_STATEMENT. No se captura ninguna otra información distinta de la que se encuentra en las tablas EXPLAIN_INSTANCE y EXPLAIN_STATEMENT.

WITH SNAPSHOT

Esta cláusula indica que, además de la información de explicación normal, se debe tomar una instantánea de explicación.

El comportamiento por omisión de la sentencia EXPLAIN es reunir únicamente información de explicación normal y no la instantánea de explicación.

por omisión (no se especifican FOR SNAPSHOT ni WITH SNAPSHOT)

Coloca la información de explicación en las tablas de Explain.

WITH REOPT ONCE

Esta cláusula indica que la sentencia explicable especificada se debe volver a optimizar mediante los valores para variables del lenguaje principal, marcadores de parámetro, registros especiales o variables globales que se utilizaron anteriormente para volver a optimizar esta sentencia con REOPT ONCE. Las tablas de Explain se llenarán con los datos del nuevo plan de acceso. Si el usuario tiene autorización DBADM, o la variable de registro de base de datos DB2_VIEW_REOPT_VALUES se ha establecido en YES, la tabla EXPLAIN_PREDICATE también se rellenará con los valores si se han utilizado para reoptimizar la sentencia.

SET QUERYNO = entero

Asocia el entero, a través de la columna QUERYNO de la tabla EXPLAIN_STATEMENT, con la sentencia explicable. El valor entero suministrado debe ser un valor positivo.

Si no se especifica esta cláusula para una sentencia EXPLAIN dinámica, se asigna un valor por omisión de uno (1). Para una sentencia EXPLAIN estática, el valor por omisión asignado es el número de sentencia asignado por el precompilador.

SET QUERYTAG = constante-serie

Asocia la constante-serie, a través de la columna QUERYTAG de la tabla EXPLAIN_STATEMENT, con la sentencia explicable. La constante-serie puede ser cualquier serie de caracteres de hasta 20 bytes de longitud. Si el valor suministrado es inferior a 20 bytes de longitud, el valor se rellena por la derecha con blancos hasta la longitud necesaria.

Si no se especifica esta cláusula para una sentencia EXPLAIN, se utilizan blancos como el valor por omisión.

FOR sentencia-sql-explicable

Especifica la sentencia de SQL que se debe explicar. Esta sentencia puede ser cualquier sentencia CALL, SQL compuesto (dinámico), DELETE, INSERT, MERGE, REFRESH, SELECT, SELECT INTO, SET INTEGRITY, UPDATE, VALUES o VALUES INTO SQL válida. Si la sentencia EXPLAIN está incorporada en un programa, la sentencia-sql-explicable puede contener referencias a las variables del lenguaje principal (estas variables deben estar definidas en el programa). De manera similar, si EXPLAIN se prepara de forma dinámica, la sentencia-sql-explicable puede contener marcadores de parámetro.

La sentencia-sql-explicable debe ser una sentencia de SQL válida que podría prepararse y ejecutarse independientemente de la sentencia EXPLAIN. No puede ser un nombre de sentencia ni una variable del lenguaje principal. Las sentencias de SQL que hacen referencia a los cursores definidos a través de CLP no se pueden utilizar con esta sentencia.

Para explicar el SQL dinámico dentro de una aplicación, toda la sentencia EXPLAIN debe estar preparada dinámicamente.

FOR XQUERY 'sentencia-xquery-explicable'

Especifica la sentencia de XQUERY que se debe explicar. Esta sentencia puede ser cualquier sentencia XQUERY válida.

Si la sentencia EXPLAIN está incorporada en un programa, la 'sentencia-xquery-explicable' puede contener referencias a variables del lenguaje principal, siempre y cuando las variables del lenguaje principal no se utilicen en el nivel superior de la sentencia XQUERY, sino que se pasen a través de una función XMLQUERY, mediante un predicado XMLEXISTS, o una función XMLTABLE. Las variables del lenguaje principal deben definirse en el programa.

De manera similar, si EXPLAIN se prepara de forma dinámica, la 'sentencia-xquery-explicable' puede contener marcadores de parámetro, siempre y cuando se siguen las mismas restricciones que para pasar variables del lenguaje principal.

De forma alternativa, la función XQUERY de db2-fn:sqlquery se puede utilizar para incorporar sentencias SQL con referencias a variables de host y marcadores de parámetro.

La sentencia-xquery-explicable debe ser una sentencia de XQUERY válida que podría prepararse y ejecutarse independientemente de la sentencia EXPLAIN. Las sentencias de consulta que hacen referencia a los cursores definidos a través de CLP no se pueden utilizar con esta sentencia.

Notas

• El recurso Explain utiliza los ID siguientes como esquema al calificar tablas de Explain que se están llenando de datos:
  • El ID de autorización de sesión SQL dinámico
  • El ID de autorización de sentencia para SQL estático
  El esquema se puede asociar con un conjunto de tablas de Explain o alias que apuntan a un conjunto de tablas de Explain en un esquema distinto. Si no se encuentran tablas de Explain en el esquema, el recurso Explain comprueba la existencia de tablas de Explain en el esquema SYSTOOLS e intenta utilizar dichas tablas.
• La tabla siguiente muestra la interacción de las palabras clave de instantánea y la información de explicación.

  Palabra clave especificada	¿Capturar información de Explain?
  ninguna	Sí
  FOR SNAPSHOT	No
  WITH SNAPSHOT	Sí

  Si no están especificadas las cláusulas FOR SNAPSHOT ni WITH SNAPSHOT, no se toma una instantánea de explicación.
• Antes de realizar la invocación de la sentencia EXPLAIN, el usuario deberá haber creado las tablas de Explain. La información que genera esta sentencia se almacena en las tablas de Explain, en el esquema que se ha designado en el momento de compilarse la sentencia.
• Si se producen errores durante la compilación de la sentencia explicable proporcionada, entonces no se almacena información en las tablas de Explain.
• El plan de acceso para la sentencia explicable no se guarda y, por consiguiente, no se podrá invocar posteriormente. La información de explicación para la sentencia explicable se inserta cuando se compila la sentencia EXPLAIN misma.
• Para una sentencia de consulta EXPLAIN estática, la información se inserta en las tablas de Explain en el momento de la vinculación o al volver a vincular explícitamente. Durante la precompilación, se comentan las sentencias EXPLAIN estáticas en el archivo de origen de la aplicación modificado. En el momento del enlace, las sentencias EXPLAIN del catálogo SYSCAT.STATEMENTS. Cuando se ejecuta el paquete, la sentencia EXPLAIN no se ejecuta. Tenga en cuenta que los números de sección para todas las sentencias de la aplicación serán secuenciales e incluirán las sentencias EXPLAIN. Una alternativa a utilizar una sentencia EXPLAIN estática es utilizar una combinación de las opciones EXPLAIN y EXPLSNAP BIND o PREP. Las sentencias EXPLAIN estáticas se pueden utilizar para hacer que las tablas de Explain se llenen para una sentencia de consulta estática específica entre muchas; simplemente, ponga un prefijo en la sentencia de destino con la sintaxis de sentencia EXPLAIN adecuada y vincule la aplicación sin utilizar las opciones BIND ni PREP de explicación. La sentencia EXPLAIN también se puede utilizar cuando es ventajoso establecer el campo QUERYNO o QUERYTAG en el momento de la invocación de explicación real.
• Las sentencias EXPLAIN estáticas de un procedimiento de SQL se evalúan cuando se compila el procedimiento.
• Para las sentencias EXPLAIN de consulta con vinculación incremental, las tablas de Explain se llenan de datos cuando se envía a compilación la sentencia EXPLAIN. Cuando se ejecuta el paquete, la sentencia EXPLAIN no realiza ningún proceso (aunque se ejecutará correctamente). Cuando las tablas de Explain se llenan con datos, el calificador de la tabla de Explain y el ID de autorización utilizado durante el llenado de datos serán los pertenecientes al propietario del paquete. La sentencia EXPLAIN también se puede utilizar cuando es ventajoso establecer el campo QUERYNO o QUERYTAG en el momento de la invocación de explicación real.
• Para sentencias EXPLAIN dinámicas, las tablas de Explain se llenan en el momento que la sentencia EXPLAIN se envía a la compilación. Una sentencia EXPLAIN puede prepararse con la sentencia PREPARE, pero su ejecución no realizará ningún proceso (aunque la sentencia se ejecutará correctamente). Una alternativa a la emisión de sentencias EXPLAIN dinámicas es utilizar una combinación de los registros especiales CURRENT EXPLAIN MODE y CURRENT EXPLAIN SNAPSHOT para explicar las sentencias de consulta dinámica. La sentencia EXPLAIN debe utilizarse cuando es ventajoso establecer el campo QUERYNO o QUERYTAG en el momento de la invocación de EXPLAIN real.
• Si la opción de vinculación REOPT se establece en ONCE y el registro especial CURRENT EXPLAIN MODE o CURRENT EXPLAIN SNAPSHOT se establece en REOPT, la ejecución de sentencias de consulta dinámica y estática que contienen variables del lenguaje principal, registros especiales, marcadores de parámetro o variables globales hará que sólo se capture la información de explicación para la sentencia cuando se vuelva a optimizar la sentencia. De forma alternativa, si la opción de vinculación REOPT se establece en ALWAYS, la información de explicación se capturará cada vez que se ejecuten estas sentencias.

Ejemplos

• Ejemplo 1: Explique una sentencia SELECT simple y póngale el distintivo QUERYNO = 13.

     EXPLAIN PLAN SET QUERYNO = 13
       FOR SELECT C1
       FROM T1

• Ejemplo 2: Explique una sentencia SELECT simple y póngale el distintivo QUERYTAG = 'TEST13'.

     EXPLAIN PLAN SELECTION SET QUERYTAG = 'TEST13'
       FOR SELECT C1
       FROM T1

• Ejemplo 3: Explique una sentencia SELECT simple y póngale los distintivos QUERYNO = 13 y QUERYTAG = 'TEST13'.

     EXPLAIN PLAN SELECTION SET QUERYNO = 13 SET QUERYTAG = 'TEST13'
       FOR SELECT C1
       FROM T1

• Ejemplo 4: Intente obtener información de explicación cuando no existan tablas de Explain.

     EXPLAIN ALL FOR SELECT C1
       FROM T1

  Esta sentencia fallará porque no se han definido las tablas de Explain (SQLSTATE 42704).
• Ejemplo 5: La siguiente sentencia será satisfactoria si se encuentra en la memoria caché del paquete y ya se ha compilado utilizando REOPT ONCE.

     EXPLAIN ALL WITH REOPT ONCE FOR SELECT C1
       FROM T1
       WHERE C1 = :<variable del lenguaje principal>

• Ejemplo 6: el ejemplo siguiente utiliza la función db2-fn:xmlcolumn, que toma el nombre que distingue entre mayúsculas y minúsculas de una columna XML como un argumento y devuelve una secuencia XML que es la concatenación de valores de columna XML.
  Imaginemos una tabla denominada BUSINESS.CUSTOMER con una columna XML denominada INFO. Una XQuery simple que devuelve todos los documentos de la columna INFO es:

     EXPLAIN PLAN SELECTION 
        FOR XQUERY 'db2-fn:xmlcolumn ("BUSINESS.CUSTOMER.INFO")'

  Si un valor de la columna es nulo, la secuencia que se obtendrá para esa fila estará vacía.