APEX 26.1 Nuevas APIs

Continuemos conociendo un poco más de las cosas nuevas que trae la versión 26.1 de Oracle Application Express.

En esta oportunidad quiero dar un vistazo a las nuevas APIs que forman parte de esta versión, la cual incluye dos nuevas APIs:

1. APEX_DB_DICTIONARY
2. APEX_INSTANCE_DEBUG

En este artículo, me voy a referir a la primera de ellas y luego lo haré también con la segunda.

APEX_DB_DICTIONARY

Este API, provee descripciones de metadatos de la base de datos amigables con lenguajes LLM (Large Language Model), con la finalidad de facilitar el uso de IA en tareas de interacción con la base de datos, para por ejemplo poder realizar desarrollo de aplicaciones o análisis de datos.

Está compuesta por las siguientes funciones:

• GET_METADATA
• GET_PRIMARY_KEY_COLUMNS
• GET_TABLE_INFO
• GET_TABLE_INFO_REGEX
• GET_TABLES_ARRAY
• GET_TABLES_JSON
• GET_TABLES_SUMMARY
• FORMAT_METADATA
• IS_SUPPORTED

GET_METADATA

Básicamente envuelve DBMS_DEVELOPER.GET_METADATA para que pueda ser llamada dentro de una aplicación APEX, conservando los mismos parámetros y pasándolos sin ser alterados, para devolver los valores y pasarlos tal cual a APEX_DB_DICTIONARY.FORMAT_METADATA.

Los parámetros que recibe son:

• p_name, el nombre del objeto
• p_schema, el nombre del esquema de base de datos
• p_object_type, el tipo del objeto que quiere obtener
• p_level, el nivel de detalle a retornar, que puede ser TYPICAL (por defeccto), BASIC o ALL
• p_etag, un identificador único para una versión específica del documento (para poder verificar si hay cambios entre versiones de un documento.

Retorna los metadatos en formato JSON como un objeto JSON para bases de datos 21c o superiores y como CLOB en versiones anteriores.

Veamos un ejemplo en el que queremos recuperar los metadatos de la tabla EMP con nivel de detalle ALL: 

Al ejecutarlo, obtenemos el siguiente objeto JSON:

GET_PRIMARY_KEY_COLUMNS

Esta función retorna una lista delimitada por comas “,” de los nombres de las columnas en la llave primaria de una tabla. Si la tabla no tiene una llave primaria, entonces retorna un valor nulo.

La función recibe los siguientes parámetros:

• p_table, el nombre de la tabla
• p_owner, el nombre del esquema dueño de la tabla (opcional)
• p_delimiter, el delimitador de la lista, que como lo expliqué si no se proporciona utiliza “,”

Sigamos utilizando la tabla EMP y veamos como obtenemos las columnas de llave primaria de dicha tabla:

Si lo ejecutamos, el código va a retornar simplemente:

     EMPNO

Que corresponde al nombre de la columna definida como llave primaria de la tabla EMP.

GET_TABLE_INFO

Esta función tiene dos versiones o variantes diferentes, las cuales retornan metadatos formateados para una o más tablas o vistas, con la única diferencia entre ambas en la forma en que se proporciona la lista de tablas o vistas de las cuales se quiere recuperar los metadatos.

En la primera versión, pasamos los nombres como una lista de valores separados por coma, mientras que en la segunda, los pasamos como un arreglo con los nombres de las tablas o vistas.

Los parámetros que aceptan estas funciones son:

• p_table_names / p_table_array, la lista de tablas o vistas a procesar
• p_include_constraints, mostrar u ocultar la sección de constraints – TRUE por defecto
• p_include_indexes, mostrar u ocultar sección de indices – FALSE por defecto
• p_include_comments, mostrar u ocultar comentarios de tabla/columnas -TRUE por defecto
• p_include_annotations, mostrar u ocultar sección de anotaciones – TRUE por defecto
• p_include_domains, mostrar u ocultar sección de metadatos de dominios SQL – TRUE por defecto
• p_include_virtual_columns, mostrar u ocultar en la salida columnas virtuales – FALSE por defecto
• p_format, formato de salida c_markdown o c_plain, el primero de ellos por defecto

El objeto retornado es un CLOB con los metadatos solicitados.

Veamos ahora un ejemplo en el que vamos a utilizar la primera de las versiones para obtener los metadatos de las tablas EMP y DEPT:

Al ejecutarlo, vamos a obtener lo siguiente:

GET_TABLE_INFO_REGEX

Esta función a las funciones GET_TABLE_INFO, la única diferencia es que devuelve la información de las tablas o vistas que concuerdan con la expresión regular que se le proporciona.

Los parámetros que aceptan estas funciones son:

• p_regex, expresión regular usada para buscar las tablas o vistas
• p_owner, nombre del esquema dueño de las tablas o vistas,
• p_object_type, tipo de objetos a recuperar, puede ser TABLE o VIEW, si no se proporciona devuelve ambos tipos de objeto
• p_include_constraints, mostrar u ocultar la sección de constraints – TRUE por defecto
• p_include_indexes, mostrar u ocultar sección de indices – FALSE por defecto
• p_include_comments, mostrar u ocultar comentarios de tabla/columnas -TRUE por defecto
• p_include_annotations, mostrar u ocultar sección de anotaciones – TRUE por defecto
• p_include_domains, mostrar u ocultar sección de metadatos de dominios SQL – TRUE por defecto
• p_include_virtual_columns, mostrar u ocultar en la salida columnas virtuales – FALSE por defecto
• p_format, formato de salida c_markdown o c_plain, el primero de ellos por defecto

El objeto retornado es un CLOB con los metadatos solicitados.

Veamos ahora un ejemplo en el que vamos a solicitar la información de tablas o vistas que contengan en su nombre ORDER o TAGS:

El resultado de ejecutar este código devuelve en mi ambiente de pruebas:

GET_TABLES_ARRAY

Esta función devuelve una lista de nombres de tablas y/o vistas que coinciden con el criterio de búsqueda proporcionado como una expresión regular. Si el parámetro p_regex resulta nulo después de aplicar un “trim”, entonces se retorna un arreglo vacío, de lo contrario se devuelve un arreglo de nombres cualificados en el formato “owner.name”.

Los parámetros utilizados por esta función son:

• p_regex, expresión regular para los nombres de objetos
• p_owner, nombre del esquema dueño de los objetos
• p_object_type, tipo de objetos a considerar: TABLE o VIEW, si no se proporciono retorna ambos tipos

En el ejemplo a continuación, vamos a recuperar los nombres de las tablas que inician con “EBA_”:

Si ejecutamos el código, en mi ambiente de pruebas, recibo el siguinte resultado:

GET_TABLES_JSON

Esta función es similar a la anterior, solo que en este caso retorna un objeto JSON que contiene dueño, nombre de objeto y tipo de objeto que coinciden con el criterio de búsqueda proporcionado como una expresión regular y, adicionalmente también podría incluir información de comentarios de tabla y columnas, así como de las anotaciones hechas en tablas o columnas de tablas, en caso de que existan. Si el parámetro p_regex resulta nulo después de aplicar un “trim”, entonces se retorna un arreglo vacío, de lo contrario se devuelve un arreglo de nombres cualificados en el formato “owner.name”.

Los parámetros utilizados por esta función son:

• p_regex, expresión regular para los nombres de objetos
• p_owner, nombre del esquema dueño de los objetos
• p_object_type, tipo de objetos a considerar: TABLE o VIEW, si no se proporciono retorna ambos tipos
• p_include_comments, incluir u ocultar comentarios de tablas y vistas – TRUE por defecto
• p_include_annotations, incluir u ocultar anotaciones de tablas y viastas – TRUE por defecto

En el ejemplo a continuación, al igual que en el anterior, vamos a recuperar los nombres de las tablas que inician con “EBA_”:

El resultado, luego de pasarlo por un formateador de JSON, luce así:

GET_TABLES_SUMMARY

Esta función retorna un resumen de las tablas y vistas en un esquema de base de datos que coinciden con la expresión regular de búsqueda proporcionada, el resultado lo genera ya sea en texto plano o en formato markdown, dentro de un objeto CLOB.

Los parámetros que utiliz la función son:

• p_regex, expresión regular de búsqueda
• p_owner, nombre del esquema de base de datos dueño de los objetos
• p_object_type, tipo de objetos: TABLE o VIEW, si no se proporciona retorna ambos tipos
• p_include_comments, incluir u ocultar comentarios – TRUE por defecto
• p_include_annotations, incluir u ocultar anotaciones – TRUE por defecto
• p_format, formato de salida: c_markdown (por defecto) o c_plain

En el ejemplo para esta función, vamos a conservar la misma premisa que en los ejemplos anteriores y vamos a recuperar la infomación de tablas y vistas que empiezaen con “EBA_”:

Y a continuación el resultado:

FORMAT_METADATA

Convierte la salida JSON de DBMS_DEVELOPER.GET_METADATA a un formato de texto legible por humanos y LLM.

Utiliza los parámetros:

• p_json, objeto JSON a formatear
• p_include_constraints, mostrar u ocultar la sección de constraints – TRUE por defecto
• p_include_indexes, mostrar u ocultar la sección de índices – FALSE por defecto
• p_include_comments, incluir u ocultar comentarios – TRUE por defecto
• p_include_annotations, incluir u ocultar anotaciones – TRUE por defecto
• p_include_domains, mostrar u ocultar la sección de metadatos de dominios SQL – TRUE por defecto
• p_include_virtual_columns, mostrar u ocultar columnas virtuales en la salida – FALSE por defecto
• p_format, formato de salida: c_markdown (por defecto) o c_plain

Al inicio de esta sección, mencioné que la función GET_METADATA es un envoltorio para DBMS_DEVELOPER.GET_METADATA, de manera que en este ejemplo vamos a tomar la salida de GET_METADATA y la vamos a pasar a esta función para ver el resultado:

El resultado obtenido es:

Como puede ver, la función a tomado el objeto JSON y lo muestra como texto legible de manera sencilla por cualquier persona o LLM.

Esta función tiene una segunda versión para quienes manejan bases de datos 19c, de manera que la puedan utilizar. La única diferencia estriva en que en lugar de proporcionar un objeto de tipo JSON a la misma, se proporciona un objeto CLOB con formato JSON.

IS_SUPPORTED

Esta función verifica si su base de datos puede utilizar el paquete DBMS_DEVELOPER, en el cual está basada la API de APEX 26.1 APEX_DB_DICTIONARY y retorna un valor boleano.

No utiliza ningún parámetro.

A continuación un ejemplo de su uso, en el que simplemente muestro un mensaje que indica si DBMS_DEVELOPER es soportado por la base de datos:

El resultado obtenido es:

Pata conocer más sobre la API APEX_DB_DICTIONARY, visite el enlace

APEX_DB_DICTIONARY documentación oficial