Jump to

• Request
• Response
• Examples

Run a Python Function on Grouped Data

post

/api/py-scripts/v1/group-apply/{scriptName}

Run a user-owned Python function on data grouped by column values.

Request

Supported Media Types

• application/json

Path Parameters

• scriptName: string
  The name of the Python script

Body ()

A JSON str of (name - value) pairs specifying arguments of the request and additional arguments

Root Schema : EmbedScriptComputeGrp

Type: object

Show Source

• asyncFlag(optional): boolean
  Whether to execute the job asynchronously.
• envName(optional): string
  Name of the conda environment.
• graphicsFlag(optional): boolean
  Whether to capture images rendered in the script to the result.
• groupBy: string
  Columns to group by. To set a list of columns, provide a comma-separated list.
• input: string
  Query statement specifying input data.
• orderBy(optional): string
  Columns to order by. To set a list of columns, provide a comma-separated list.
• parallel(optional): integer(int32)
  Degree of parallel.
• parallelFlag(optional): boolean
  Whether to execute job in parallelism.
• parameters(optional): string
  A JSON str of (name - value) pairs specifying keyword arguments to be passed into the script.
• service(optional): string
  Allowed Values: [ "LOW", "MEDIUM", "HIGH" ]

  LEVEL of the service. Default is LOW.
• timeout(optional): integer(int32)
  Minimum Value: 1800

  Maximum Value: 43200

  The timeout limit (in seconds, default 1800s) of asynchronous job. Must be used together with `asyncFlag`=true.

{
    "type":"object",
    "required":[
        "groupBy",
        "input"
    ],
    "properties":{
        "parameters":{
            "type":"string",
            "description":"A JSON str of (name - value) pairs specifying keyword arguments to be passed into the script."
        },
        "graphicsFlag":{
            "type":"boolean",
            "description":"Whether to capture images rendered in the script to the result."
        },
        "asyncFlag":{
            "type":"boolean",
            "description":"Whether to execute the job asynchronously."
        },
        "timeout":{
            "type":"integer",
            "format":"int32",
            "description":"The timeout limit (in seconds, default 1800s) of asynchronous job. Must be used together with `asyncFlag`=true.",
            "minimum":1800,
            "maximum":43200
        },
        "service":{
            "type":"string",
            "description":"LEVEL of the service. Default is LOW.",
            "enum":[
                "LOW",
                "MEDIUM",
                "HIGH"
            ]
        },
        "envName":{
            "type":"string",
            "description":"Name of the conda environment."
        },
        "input":{
            "type":"string",
            "description":"Query statement specifying input data."
        },
        "groupBy":{
            "type":"string",
            "description":"Columns to group by. To set a list of columns, provide a comma-separated list."
        },
        "orderBy":{
            "type":"string",
            "description":"Columns to order by. To set a list of columns, provide a comma-separated list."
        },
        "parallelFlag":{
            "type":"boolean",
            "description":"Whether to execute job in parallelism."
        },
        "parallel":{
            "type":"integer",
            "format":"int32",
            "description":"Degree of parallel."
        }
    }
}

Example Request (application/json)

{"input":"select * from GRADE", "groupBy":"GENDER, YEAR", "orderBy":"GENDER", "parameters":"{\"oml_input_type\":\"default\"}", "parallelFlag":true}

Back to Top

Response

Supported Media Types

• application/json

200 Response

By default, returns the job result.

Body ()

Root Schema : JSONObject

Type: object

Show Source

• empty(optional): boolean

{
    "type":"object",
    "properties":{
        "empty":{
            "type":"boolean"
        }
    }
}

201 Response

If asyncFlag=True, returns the location header where the status of the job can be fetched.

Headers

• Location: string(uri)

400 Response

Invalid parameters specified, output exceeding size limit or other script execution error.

Body ()

Root Schema : InvalidParameterValueException

Type: object

Show Source

• errorCode: integer(int64)
• errorMessage(optional): string
• parameterName(optional): string
• parameterValue(optional): string

{
    "type":"object",
    "required":[
        "debug",
        "errorCode"
    ],
    "properties":{
        "errorMessage":{
            "type":"string"
        },
        "errorCode":{
            "type":"integer",
            "format":"int64"
        },
        "parameterName":{
            "type":"string"
        },
        "parameterValue":{
            "type":"string"
        }
    }
}

500 Response

Problem connecting to Broker, executing job or other unexpected error.

Body ()

Root Schema : ComputeContainerException

Type: object

Show Source

• errorCode: integer(int64)
• errorMessage(optional): string

{
    "type":"object",
    "required":[
        "debug",
        "errorCode"
    ],
    "properties":{
        "errorMessage":{
            "type":"string"
        },
        "errorCode":{
            "type":"integer",
            "format":"int64"
        }
    }
}

Back to Top

Examples

Example 1: Synchronous Example

The following example runs the script named group_count. In the example, the parallelFlag is set to true to leverage database parallelism.

curl -i -X POST --header "Authorization: Bearer ${token}" \
--header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{"input":"select * from IRIS", "parameters":"{\"oml_input_type\":\"pandas.DataFrame\"}", "groupBy":"Species", "orderBy":"Sepal_Length", "parallelFlag":true}' \
"<oml-cloud-service-location-url>/oml/api/py-scripts/v1/group-apply/group_count"

Response Headers

The response headers are the following:

HTTP/1.1 200 OK
Date: Mon, 17 Aug 2020 21:06:54 GMT
Content-Type: application/json
Content-Length: 5045
Connection: keep-alive
Cache-Control: no-cache, no-store, private
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1;mode=block
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
Set-Cookie: JSESSIONID=node0bucgs4gt7hci1gxvgtqc1hjdv647.node0; Path=/oml; Secure; HttpOnly
Expires: Thu, 01 Jan 1970 00:00:00 GMT

Response Body

A portion of the response body in JSON format is the following.

{"result":{"versicolor_8":{"SEPAL_LENGTH":{"0":5.7},"SPECIES":{"0":"versicolor"},"COUNT":{"0":5}},
"versicolor_7":{"SEPAL_LENGTH":{"0":5.6},"SPECIES":{"0":"versicolor"},"COUNT":{"0":2}},...}

Example 2

The following example runs the script named test_seaborn_inp.

curl -i -k -X POST --header "Authorization: Bearer ${token}" --header
'Content-Type: application/json' --header 'Accept: application/json' -d
'{"input": "select * from IRIS", "groupBy": "Species", "envName": "seaborn","graphicsFlag": true}' 
"<oml-cloud-service-location-url>/oml/api/py-scripts/v1/group-apply/test_seaborn_inp"

Response Body

The result of the REST endpoint is a JSON representation of the value returned from the Python script, which includes the image and the data. Image bytes are returned in PNG format.

{
  "result": {
    "0": {
      "GROUP": "setosa",
      "IMAGE": "iVBORw0KGgoAAAAN......AAAAASUVORK5CYII=",
      "DATA": "\"hello world\"",
      "TITLE": "Iris plot",
      "ID": 1
    },
      "1": {
      "GROUP": "versicolor",
      "IMAGE": "iVBORw0KGgoAAAAN......AAAAASUVORK5CYII=",
      "DATA": "\"hello world\"",
      "TITLE": "Iris plot",
      "ID": 1
    },
      "2": {
      "GROUP": "virginica",
      "IMAGE": "iVBORw0KGgoAAAAN......AAAAASUVORK5CYII=",
      "DATA": "\"hello world\"",
      "TITLE": "Iris plot",
      "ID": 1
      }
    }
}

Back to Top