Paquete DBMS_CLOUD_FUNCTION

El paquete DBMS_CLOUD_FUNCTION le permite invocar funciones remotas de OCI y AWS Lambda en su base de datos de IA autónoma como funciones SQL.

Note:

El soporte para DBMS_CLOUD_FUNCTION está disponible en Oracle Database 19c a partir de la versión 19.29 y en Oracle AI Database 26ai a partir de la versión 23.26.

Resumen de Subprogramas DBMS_CLOUD_FUNCTION

En esta tabla se resumen los subprogramas incluidos en el paquete DBMS_CLOUD_FUNCTION.

Tabla: Subprogramas DBMS_CLOUD_FUNCTION

Subprograma Descripción
CREATE_CATALOG Procedimiento Este procedimiento crea un catálogo.
CREATE_FUNCTION Procedimiento Este procedimiento crea funciones en un catálogo.
DROP_CATALOG Procedimiento Este procedimiento borra un catálogo y las funciones creadas mediante el catálogo.
DROP_FUNCTION Procedimiento Este procedimiento borra las funciones de un catálogo.
LIST_FUNCTIONS Procedimiento Este procedimiento enumera todas las funciones de un catálogo.
SYNC_FUNCTIONS Procedimiento Este procedimiento permite agregar nuevas funciones al catálogo y eliminar las funciones que se han suprimido del catálogo.

CREATE_CATALOG Procedimiento

El procedimiento DBMS_CLOUD_FUNCTION.CREATE_CATALOG crea un catálogo en la base de datos. Un catálogo es un juego de funciones que crea la infraestructura necesaria para ejecutar subrutinas.

Sintaxis

DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
    credential_name             IN VARCHAR2,
    catalog_name                IN VARCHAR2,
    service_provider            IN VARCHAR2, 
    cloud_params                IN CLOB
);

Parámetros

parámetro Descripción

credential_name

Especifica el nombre de la credencial para la autenticación.

Este parámetro es obligatorio.

service_provider

Especifica el tipo de proveedor de servicios.

Este parámetro puede tener OCI o AWS como valor de parámetro.

Este parámetro es obligatorio.

catalog_name

Especifica el nombre del catálogo.

Este parámetro es obligatorio.

cloud_params

Proporciona un parámetro para la función. Por ejemplo, OCID de compartimento y regiones.

Este parámetro es obligatorio.

Errores

Código de error Descripción

ORA-20000

Este error se emite en la siguiente condición:

  • Falta el valor cloud_params o se transfieren valores de parámetros incorrectos.

ORA-20001

Este error se emite en la siguiente condición:

  • La credencial a la que se hace referencia en credential_name no existe.

ORA-20002

Este error se emite en la siguiente condición:

  • Este error se produce cuando el catálogo ya existe.

ORA-20009

Este error se produce cuando el proveedor de servicios no existe.

Ejemplos

BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
        credential_name  => 'DEFAULT_CREDENTIAL', 
        catalog_name     => 'OCI_DEMO_CATALOG', 
        service_provider => 'OCI',
        cloud_params     => ("region_id":"us-phoenix-1", "compartment_id":"compartment_id"
 );
END;
/

Notas de uso

  • Para crear un catálogo, debe estar conectado como usuario ADMIN o tener privilegios en lo siguiente:

    • DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE

    • DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE_INVOKE_FUNCTION_RESPONSE_T

    • DBMS_CLOUD

    • Leer privilegio en USER_CLOUD_FUNCTION

    • Leer privilegio en USER_CLOUD_FUNCTION_CATALOG

CREATE_FUNCTION Procedimiento

Este procedimiento crea funciones en un catálogo.

Sintaxis

El procedimiento DBMS_CLOUD_FUNCTION.CREATE_FUNCTION solo se admite para funciones en la nube. 

DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
    credential_name   IN VARCHAR2,
    catalog_name      IN VARCHAR2,
    function_name     IN VARCHAR2,
    function_id       IN VARCHAR2,
    input_args        IN CLOB      DEFAULT NULL,
    return_type       IN VARCHAR2  DEFAULT 'CLOB',
    response_handler  IN VARCHAR2  DEFAULT NULL
);

Firma del manejador de respuestas

<USER DEFINED TYPE> response_handler_name(function_response in CLOB)RETURNS CLOB;

El tipo de retorno es el tipo definido por el usuario o el tipo PL/SQL. function_response es de JSON con campos. 

'{  
"STATUS":"<RESPONCE STATUS>",  
"RESPONSE_BODY":"<FUNCTION RESPONSE>"
}'

Parámetros

parámetro Descripción

credential_name

Especifica el nombre de la credencial para la autenticación.

Este parámetro es obligatorio.

catalog_name

Especifica el nombre del catálogo.

Este parámetro es obligatorio.

function_name

Especifica el nombre de la función PL/SQL.

Este parámetro es obligatorio.

function_id

El valor del parámetro function_id hace referencia a la función de OCI o AWS Lambda.

Este parámetro es obligatorio.

input_args

Especifica el par JSON de valor de clave que acepta argumentos de entrada y sus tipos.

return_type

Define el tipo que devuelve la función.

El tipo de retorno es del tipo de dato CLOB.

response_handler

Especifica la devolución de llamada definida por el usuario para manejar la respuesta.

Errores

Código de error Descripción

ORA-20001

Este error se emite cuando la credencial a la que se hace referencia en credential_name no existe.

ORA-20003

Este error se produce cuando el catálogo especificado no existe.

ORA-20004

Este error se emite cuando la función especificada ya existe.

ORA-20005

Este error se produce cuando el ID de función o la función Nombres de recursos de Amazon (ARN) no existen.

ORA-20006

Este error se emite cuando los argumentos de entrada no son válidos.

ORA-20007

Este error se genera cuando falta el tipo de devolución o no es válido.

ORA-20008

Este error se emite cuando falta el manejador de respuestas o no es válido.

Ejemplo

VAR function_args CLOB;
EXEC :function_args := TO_CLOB('{"command": "VARCHAR2", "value": "VARCHAR2"}');
BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
	credential_name  => 'DEFAULT_CREDENTIAL',    
       catalog_name     => 'OCI_DEMO_CATALOG',
       function_name    => 'demo_function', 
       function_id      => 'ocid1.fnfunc.oc1.phx.aaaaaaaazkrbjv6ntowwxlbbp5ct4otsj4o2hdw4ayosyosv4sthmya2lyza',
       input_args       => :function_args);
 );
END;
/

DROP_CATALOG Procedimiento

El procedimiento DBMS_CLOUD_FUNCTION.DROP_CATALOG borra el catálogo y las funciones creadas mediante el catálogo.

Sintaxis

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    catalog_name      IN VARCHAR2
 );

Parámetros

parámetro Descripción

catalog_name

Especifica el nombre del catálogo.

Este parámetro es obligatorio.

Errores

Código de error Descripción

ORA-20003

Este error se produce cuando el catálogo especificado no existe.

Por ejemplo: 

BEGIN
    DBMS_CLOUD_FUNCTION.DROP_CATALOG (
      catalog_name     => 'OCI_DEMO_CATALOG'
  );
END;
/

DROP_FUNCTION Procedimiento

El procedimiento DBMS_CLOUD_FUNCTION.DROP_FUNCTION borra la función.

Sintaxis

El procedimiento DBMS_CLOUD_FUNCTION.DROP_FUNCTION solo se admite para funciones en la nube. 

DBMS_CLOUD_FUNCTION.DROP_FUNCTION (
    catalog_name      IN VARCHAR2,
    function_name     IN VARCHAR2
);

Parámetros

parámetro Descripción

catalog_name

Especifica el nombre del catálogo.

Este parámetro es obligatorio.

function_name

Especifica el nombre de la función que se va a borrar.

Este parámetro es obligatorio.

Errores

Código de error Descripción

ORA-20003

Este error se emite cuando la función especificada no existe.

Ejemplos

BEGIN
    DBMS_CLOUD_FUNCTION.DROP_FUNCTION (
       catalog_name     => 'OCI_DEMO_CATALOG',
       function_name    => 'demo_function');
END;
/

LIST_FUNCTIONS Procedimiento

Este procedimiento enumera todas las funciones de un catálogo.

Sintaxis

DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS (
    credential_name   IN VARCHAR2,
    catalog_name      IN VARCHAR2,
    function_list     OUT VARCHAR2
);

Parámetros

parámetro Descripción

credential_name

Especifica el nombre de la credencial para la autenticación.

Este parámetro es obligatorio.

function_list

Devuelve la lista de funciones en formato JSON.

Este parámetro es obligatorio.

catalog_name

Especifica el nombre del catálogo.

Este parámetro es obligatorio.

Errores

Código de error Descripción

ORA-20000

Este error se produce cuando se transfieren valores de parámetros incorrectos.

ORA-20001

Este error se emite cuando la credencial a la que se hace referencia en credential_name no existe.

ORA-20003

Este error se produce cuando el catálogo especificado no existe.

Por ejemplo: 

VAR function_list CLOB;
BEGIN
    DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS (
	credential_name  => 'DEFAULT_CREDENTIAL', 
	catalog_name     => 'OCI_DEMO_CATALOG',  
	function_list    => :function_list);
 );
END;
/
SELECT JSON_QUERY(:function_list, '$' RETURNING VARCHAR2(32676) pretty) AS search_results FROM dual;

SYNC_FUNCTIONS Procedimiento

Este procedimiento permite agregar nuevas funciones al catálogo y eliminar las funciones que se han suprimido del catálogo.

Sintaxis

DBMS_CLOUD_FUNCTION.SYNC_FUNCTIONS (
    catalog_name      IN VARCHAR2,
    refresh_rate     IN VARCHAR2 DEFAULT 'DAILY'
);

Parámetros

parámetro Descripción

catalog_name

Especifica el nombre del catálogo.

Este parámetro es obligatorio.

refresh_rate

Especifica el ratio de refrescamiento de la función.

refresh_rate puede aceptar los siguientes valores:

  • HOURLY

  • DAILY

  • WEEKLY

  • MONTHLY

El valor por defecto del parámetro es DAILY.

Errores

Código de error Descripción

ORA-20003

Este error se produce cuando el catálogo especificado no existe.

ORA-20004

Este error se emite cuando se transfiere un valor no válido para el parámetro refresh_rate.

Por ejemplo: 


BEGIN
    DBMS_CLOUD_FUNCTION.SYNC_FUNCTIONS (
       catalog_name     => 'OCI_DEMO_CATALOG'
 );
END;
/