10.6.2.7 rqGroupEval2 Function

The function rqGroupEval2 when used in Oracle Autonomous Database, groups data by one or more columns and runs a user-defined R function on each group.

The function rqGroupEval2 runs the user-defined R function specified by the scr_name parameter. Pass data to the user-defined R function with the inp_nam parameter, pass arguments to the user-defined R function with the par_lst parameter. Specify one or more grouping columns with the grp_col parameter. Define the form of the returned value with the out_fmt parameter.

Syntax

rqGroupEval2 (
    INP_NAM VARCHAR2,
    PAR_LST VARCHAR2,
    OUT_FMT VARCHAR2,
    GRP_COL VARCHAR2,
    SCR_NAME VARCHAR2,
    SCR_OWNER VARCHAR2 DEFAULT NULL,
    ENV_NAME  VARCHAR2 DEFAULT NULL
    )

Parameters

Parameter Description

INP_NAM

The name of a table or view that specifies the data to pass to the R function specified by the SCR_NAME parameter. If using a table or view owned by another user, use the format

<owner name>.<table/view name>

You must have read access to the specified table or view.

PAR_LST

A JSON string that contains additional parameters to pass to the user-defined R function specified by the scr_name parameter. Special control arguments, which start with ore, are not passed to the function specified by scr_name, but instead control what happens before or after the invocation of the function.

For example, to run the R function with data parallelism, use:

'{"ore_parallel_flag":true}'

See also: Special Control Arguments

OUT_FMT

The format of the output returned by the function. It can be one of the following:

  • A JSON string that specifies the column names and data types of the table returned by the function. Any image data is discarded.
  • The string 'JSON', which specifies that the table returned contains a CLOB that is a JSON string.
  • The string 'XML', which specifies that the table returned contains a CLOB that is an XML string. The XML can contain both structured data and images, with structured or semi-structured R objects first, followed by the image or images generated by the R function.
  • The string 'PNG', which specifies that the table returned contains a BLOB that has the image or images generated by the R function. Images are returned as a base 64 encoding of the PNG representation.

See also: Output Formats.

GRP_COL

The names of the grouping columns by which to partition the data. Use commas to separate multiple columns. For example, to group by GENDER and YEAR:

"GENDER,YEAR"

SCR_NAME

The name of a user-defined R function in the OML4R script repository.

SCR_OWNER

The owner of the registered R script. The default value is NULL. If NULL, will search for the R script in the user’s script repository.

ENV_NAME

The name of the conda environment that should be used when running the named user-defined R function.

Return Value

The user-defined rqGroupEval2 function returns a table that has the structure specified by the OUT_FMT parameter value.

Examples

Example 10-45 Using an rqGroupEval2 Function

This example uses the IRIS table created in the example shown in rqTableEval2 Function (Autonomous Database). Define the R function and store it with the name groupCount in the script repository.

%script
BEGIN
    sys.rqScriptCreate('groupCount',
        'function(dat){
            x <- data.frame(table(dat$Species))
            names(x) <- c("Species", "Count")
            x}',
        FALSE, TRUE); -- V_GLOBAL, V_OVERWRITE
END;
/

The output is similar to the following:

PL/SQL procedure successfully completed. 

---------------------------

Example 10-46 JSON Output

Calls the rqGroupEval2 function, which runs the user defined function groupCount. In the function, the INP_NAM argument specifies the data in the IRIS table to pass to the function. The PAR_LST argument specifies the special control argument ore_input_type. In the OUT_FMT argument, the string 'JSON', specifies that the table returned contains a CLOB that is a JSON string The GRP_COL parameter specifies the column to group by. The SCR_NAME parameter specifies the user-defined R function stored with the name groupCount in the script repository.

%script
set long 500
SELECT * FROM table(rqGroupEval2(
            inp_nam => 'IRIS',
            par_lst => '{"ore_service_level":"MEDIUM", "ore_parallel_flag":true}',
            out_fmt => 'JSON',
            grp_col => 'Species',
            scr_name => 'groupCount'));

The output is similar to the following:

NAME VALUE 
[{"Count":50,"Species":"setosa"},{"Count":50,"Species":"versicolor"},{"Count":50,"Species":"virginica"}]

Example 10-47 XML Output

Calls the rqGroupEval2 function, which runs the user defined function groupCount. In the function, the INP_NAM argument specifies the data in the IRIS table to pass to the function. The PAR_LST argument specifies using MEDIUM service level with special control argument ore_service_level and set the special control argument ore_parallel_flag to true. The OUT_FMT parameter specifies returning the value in XML format. The GRP_COL parameter specifies the column to group by. The SCR_NAME parameter specifies the user-defined R function stored with the name groupCount in the script repository.

%script
set long 500
SELECT * FROM table(rqGroupEval2(
            inp_nam => 'IRIS',
            par_lst => '{ore_service_level":"MEDIUM", "ore_parallel_flag":true}',
            out_fmt => 'XML',
            grp_col => 'Species',
            scr_name => 'groupCount'));

The ouput is similar to the following:

NAME VALUE
       <root><frame_obj><ROW-frame_obj><Species>setosa</Species><Count>50</Count></ROW-frame_obj><ROW-frame_obj><Species>versicolor</Species><Count>50</Count></ROW-frame_obj><ROW-frame_obj><Species>virginica</Species><Count>50</Count></ROW-frame_obj></frame_obj></root>

Example 10-48 Relational Output

Run the Select statement to get a Relational output.

%script
SELECT * FROM table(rqGroupEval2(
            inp_nam => 'IRIS',
            par_lst => '{"ore_service_level":"MEDIUM", "ore_parallel_flag":true}',
            out_fmt => '{"Species":"VARCHAR2(10)", "Count":"NUMBER"}',
            grp_col => 'Species',
            scr_name => 'groupCount'));
Species Count 
setosa 50 
versicolor 50 
virginica 50

The following code runs a SQL query to retrieve all columns from the result of an rqGroupEval2 function call, which generates a PNG output based on a specified script and environment.

select *
from table(rqGroupEval2(
inp_nam => 'IRIS',
par_lst => '{"ore_graphics_flag":true}',
out_fmt => 'PNG',
grp_col => 'Species',
scr_name => 'test_ggplot2_inp',
scr_owner => NULL,
env_name => 'myrenv'));

The output appears as follows:

NAME ID       VALUE               IMAGE
---------- ---------- -------------------- ------------------------------
GROUP_seto    1        "hello world"         89504E470D0A1A0A0000000D494844
sa                                           52000001E0000001E008060000007D
                                             D4BE950000200049444154789CEDDD
                                             777C14D5FEC6F1676B7A42E8BD480B
                                             C58BB41F57A504040554044150B180
                                             8A624541B1
GROUP_vers     1       "hello world"         89504E470D0A1A0A0000000D494844
icolor                                       52000001E0000001E008060000007D
                                             D4BE950000200049444154789CEDDD
                                             777414E5E2C6F16753482F90D0420B
NAME       ID         VALUE                IMAGE
---------- ---------- -------------------- ------------------------------
                                           3D34E9971F0AA10852548A20551154
                                           C48E342BD7
GROUP_virg  1        "hello world"         89504E470D0A1A0A0000000D494844
inica                                      52000001E0000001E008060000007D
                                           D4BE950000200049444154789CEDDD
                                           777C1475E2C6F1674B7A0112A49720
                                           2D1405293F0EA50404292A45101014
                                           4145ACA020