DBMS_CLOUD_FUNCTION Package
The DBMS_CLOUD_FUNCTION
package
allows you invoke OCI and AWS Lambda remote functions in your
Autonomous Database as SQL functions.
- Summary of DBMS_CLOUD_FUNCTION Subprograms
This table summarizes the subprograms included in theDBMS_CLOUD_FUNCTION
package.
Parent topic: Autonomous Database Supplied Package Reference
Summary of DBMS_CLOUD_FUNCTION Subprograms
This table summarizes the subprograms included in the DBMS_CLOUD_FUNCTION
package.
Subprogram | Description |
---|---|
This procedure creates a catalog. |
|
This procedure creates functions in a catalog. |
|
This procedure drops a catalog and functions created using the catalog |
|
This procedure drops functions from a catalog. |
|
This procedure lists all the functions in a catalog. |
|
This procedure creates a PL/SQL wrapper for adding new functions to the catalog and removing wrappers for functions that have been deleted from the catalog. |
- CREATE_CATALOG Procedure
This procedure creates a catalog in the database. TheDBMS_CLOUD_FUNCTION.CREATE_CATALOG
procedure creates a catalog. A catalog is a set of functions that creates the required infrastructure to execute subroutines. This procedure is overloaded. - CREATE_FUNCTION Procedure
This procedure creates functions in a catalog. There are two overloadedDBMS_CLOUD_FUNCTION.CREATE_FUNCTION
procedures. - DROP_CATALOG Procedure
TheDBMS_CLOUD_FUNCTION.DROP_CATALOG
procedure drops the catalog and functions created using the catalog. This procedure is overloaded. - DROP_FUNCTION Procedure
TheDBMS_CLOUD_FUNCTION.DROP_FUNCTION
procedure drops the function. This procedure is overloaded. - LIST_FUNCTIONS Procedure
This procedure lists all the functions in a catalog. - SYNC_FUNCTIONS Procedure
This procedure creates a PL/SQL wrapper for adding new functions to the catalog and removing wrappers for functions that have been deleted from the catalog.
Parent topic: DBMS_CLOUD_FUNCTION Package
CREATE_CATALOG Procedure
This procedure creates a catalog in the database. The DBMS_CLOUD_FUNCTION.CREATE_CATALOG
procedure creates a catalog. A catalog is a set of functions that creates the required infrastructure to execute subroutines. This procedure is overloaded.
Syntax
DBMS_CLOUD_FUNCTION.CREATE_CATALOG
(
credential_name IN VARCHAR2,
catalog_name IN VARCHAR2,
service_provider IN VARCHAR2,
cloud_params IN CLOB
);
DBMS_CLOUD_FUNCTION.CREATE_CATALOG
(
library_name IN VARCHAR2,
library_listener_url IN VARCHAR2,
library_wallet_dir_name IN VARCHAR2,
library_ssl_server_cert_dn IN VARCHAR2,
library_remote_path IN VARCHAR2
);
Parameters
Parameter | Description |
---|---|
|
Specifies the name of the credential for authentication. This parameter is mandatory. |
|
Specifies the type of the service provider. This parameter can have This parameter is mandatory. |
|
Specifies the catalog name. This parameter is mandatory. |
|
Provides parameter to the function. For example, Compartment OCID, Regions and Azure subscription_id. This parameter is mandatory. |
|
Specifies the name of the library when creating a remote library. This parameter is mandatory. |
|
Specifies the remote location of the library. The parameter accepts a String value in For example: This parameter is mandatory. |
|
Specifies the remote library path. You must provide the full absolute path to the remote library. For example: This parameter is mandatory. |
|
Specifies the directory where the self-signed wallet is stored. This parameter is mandatory. |
|
Specifies the server certificate Distinguished Name (DN). This parameter is mandatory. |
Errors
Error Code | Description |
---|---|
|
This error is raised in either of the following conditions:
|
|
This error is raised in either of the following conditions:
|
|
This error is raised in either of the following conditions:
|
|
This error is raised when the service provider doesn't exist. |
Examples
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;
/
BEGIN
DBMS_CLOUD_FUNCTION.CREATE_CATALOG
(
credential_name => 'AZURE$PA',
catalog_name => 'AZURE_DEMO_CATALOG',
service_provider => 'AZURE',
cloud_params => '{"subscription_id":"44495e6a-8ff1-4161-b387-0e14e675b878"}'
);
END;
/
BEGIN
DBMS_CLOUD_FUNCTION.CREATE_CATALOG
(
library_name => 'EXT_DEMOLIB',
library_listener_url => 'remote_extproc_hostname:16000',
library_wallet_dir_name => 'WALLET_DIR',
library_ssl_server_cert_dn => 'CN=VM Hostname',
library_remote_path => '/u01/app/oracle/extproc_libs/library name'
);
END;
/
Usage Note
-
To create a catalog you must be logged in as the
ADMIN
user or have privileges on the following:-
DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE
-
DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE_INVOKE_FUNCTION_RESPONSE_T
-
DBMS_CLOUD
-
Read privilege on
USER_CLOUD_FUNCTION
-
Read privilege on
USER_CLOUD_FUNCTION_CATALOG
-
Parent topic: Summary of DBMS_CLOUD_FUNCTION Subprograms
CREATE_FUNCTION Procedure
This procedure creates functions in a catalog. There are two overloaded DBMS_CLOUD_FUNCTION.CREATE_FUNCTION
procedures.
CREATE_FUNCTION
Syntax
The DBMS_CLOUD_FUNCTION.CREATE_FUNCTION
procedure is only supported for cloud functions.
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
);
Response Handler signature
<USER DEFINED TYPE> response_handler_name(function_response in CLOB)RETURNS CLOB;
The return type of this is user defined type or PL/SQL type. The function_response
is of JSON with fields.
'{
"STATUS":"<RESPONCE STATUS>",
"RESPONSE_BODY":"<FUNCTION RESPONSE>"
}'
CREATE_FUNCTION
Parameters
CREATE_FUNCTION
Exceptions
Parameter | Description |
---|---|
|
Specifies the name of the credential for authentication. This parameter is mandatory. |
|
Specifies the catalog name. This parameter is mandatory. |
|
Specifies the PL/SQL function name. This parameter is mandatory. |
|
The This parameter is mandatory. |
|
Specifies the key value JSON pair accepting input arguments and their types. |
|
Defines the return type of the function. The return type is of |
|
Specifies the user defined callback to handle response. |
Error Code | Description |
---|---|
|
This error is raised when the credential referenced in the |
|
This error is raised when the specified catalog does not exist. |
|
This error is raised when the specified function already exists. |
|
This error is raised when the function ID or function Amazon Resource Names (ARN) does not exist. |
|
This error is raised when the input arguments are invalid. |
|
This error is raised when the return type is missing or invalid. |
|
This error is raised when the response handler is missing or invalid. |
CREATE_FUNCTION
Example
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;
/
CREATE_FUNCTION
Syntax
DBMS_CLOUD_FUNCTION.CREATE_FUNCTION
(
library_name IN VARCHAR2,
function_name IN VARCHAR2,
function_id IN VARCHAR2 DEFAULT NULL,
plsql_params IN CLOB DEFAULT NULL,
external_params IN CLOB DEFAULT NULL,
api_type IN VARCHAR2 DEFAULT 'FUNCTION',
with_context IN BOOLEAN DEFAULT FALSE,
return_type IN VARCHAR2 DEFAULT NULL
);
CREATE_FUNCTION
Parameters
Parameter | Description |
---|---|
|
Specifies the remote library name. This parameter is mandatory. |
|
Specifies the PL/SQL function name. This parameter is mandatory. |
|
The If the value for |
|
Specifies the key value JSON pair accepting the parameters for the PL/SQL wrapper. The values must be provided in the
The default value for |
|
Specifies the parameters that need to be provided to the external C function. If value is not provided for
|
|
Specifies the type of API (function or procedure). The default value for |
|
Specifies that a context pointer is passed to the external procedure. This context is used by the external C library for connecting back to the database. The default value for |
|
Specifies the return type of the function created. |
CREATE_FUNCTION
Example
DECLARE
plsql_params clob := TO_CLOB('{"sal": "IN, FLOAT", "comm" :"IN, FLOAT"}');
external_params clob := TO_CLOB('sal FLOAT, sal INDICATOR SHORT, comm FLOAT, comm INDICATOR SHORT,
RETURN INDICATOR SHORT, RETURN FLOAT');
BEGIN
DBMS_CLOUD_FUNCTION.CREATE_FUNCTION
(
LIBRARY_NAME => 'demolib',
FUNCTION_NAME => '"PercentComm"',
PLSQL_PARAMS => plsql_params,
EXTERNAL_PARAMS => external_params,
API_TYPE => 'FUNCTION',
WITH_CONTEXT => FALSE,
RETURN_TYPE => 'FLOAT'
);
END;
/
Parent topic: Summary of DBMS_CLOUD_FUNCTION Subprograms
DROP_CATALOG Procedure
The DBMS_CLOUD_FUNCTION.DROP_CATALOG
procedure drops the catalog and functions created using the catalog. This procedure is overloaded.
Syntax
DBMS_CLOUD_FUNCTION.DROP_CATALOG
(
catalog_name IN VARCHAR2
);
DBMS_CLOUD_FUNCTION.DROP_CATALOG
(
library_name IN VARCHAR2
);
Parameters
Parameter | Description |
---|---|
|
Specifies the catalog name. This parameter is mandatory. |
library_name |
Specifies the library name. This parameter is mandatory. |
Errors
Error Code | Description |
---|---|
|
This error is raised when the specified catalog doesn't exist. |
Example:
BEGIN
DBMS_CLOUD_FUNCTION.DROP_CATALOG
(
catalog_name => 'OCI_DEMO_CATALOG'
);
END;
/
Example:
BEGIN
DBMS_CLOUD_FUNCTION.DROP_CATALOG
(
library_name => 'library_name'
);
END;
/
Parent topic: Summary of DBMS_CLOUD_FUNCTION Subprograms
DROP_FUNCTION Procedure
The DBMS_CLOUD_FUNCTION.DROP_FUNCTION
procedure drops the function. This procedure is overloaded.
Syntax
The DBMS_CLOUD_FUNCTION.DROP_FUNCTION
procedure is only supported for cloud functions.
DBMS_CLOUD_FUNCTION.DROP_FUNCTION
(
catalog_name IN VARCHAR2,
function_name IN VARCHAR2
);
DBMS_CLOUD_FUNCTION.DROP_FUNCTION
(
library_name IN VARCHAR2,
function_name IN VARCHAR2
);
Parameters
Parameter | Description |
---|---|
|
Specifies the catalog name. This parameter is mandatory. |
|
Specifies the name of the function to be dropped. This parameter is mandatory. |
|
Specifies the library name. This parameter is mandatory. |
Examples
BEGIN
DBMS_CLOUD_FUNCTION.DROP_FUNCTION
(
catalog_name => 'OCI_DEMO_CATALOG',
function_name => 'demo_function');
END;
/
BEGIN
DBMS_CLOUD_FUNCTION.DROP_FUNCTION
(
library_name => 'EXTPROC_DEMO_LIBRARY',
function_name => 'demo_function');
END;
/
Parent topic: Summary of DBMS_CLOUD_FUNCTION Subprograms
LIST_FUNCTIONS Procedure
This procedure lists all the functions in a catalog.
Syntax
DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS
(
credential_name IN VARCHAR2,
catalog_name IN VARCHAR2,
function_list OUT VARCHAR2
);
Parameters
Parameter | Description |
---|---|
|
Specifies the name of the credential for authentication. This parameter is mandatory. |
|
Returns the list of functions in JSON format. This parameter is mandatory. |
|
Specifies the catalog name. This parameter is mandatory. |
Errors
Error Code | Description |
---|---|
|
This error is raised when |
|
This error is raised when the credential referenced in the |
|
This error is raised when the specified catalog does not exist. |
Example:
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;
Parent topic: Summary of DBMS_CLOUD_FUNCTION Subprograms
SYNC_FUNCTIONS Procedure
This procedure creates a PL/SQL wrapper for adding new functions to the catalog and removing wrappers for functions that have been deleted from the catalog.
Syntax
DBMS_CLOUD_FUNCTION.SYNC_FUNCTIONS
(
catalog_name IN VARCHAR2,
refresh_rate IN VARCHAR2 DEFAULT 'DAILY'
);
Parameters
Parameter | Description |
---|---|
|
Specifies the catalog name. This parameter is mandatory. |
|
Specifies the refresh rate of the function. refresh_rate can accept the following values:
The default value for this parameter is |
Errors
Error Code | Description |
---|---|
|
This error is raised when the specified catalog does not exist. |
|
This error is raised when an invalid value is passed for the |
Example:
BEGIN
DBMS_CLOUD_FUNCTION.SYNC_FUNCTIONS
(
catalog_name => 'OCI_DEMO_CATALOG'
);
END;
/
Parent topic: Summary of DBMS_CLOUD_FUNCTION Subprograms