UDF.md

Step-by-Step Guide to Setting and Using a UDF in TDCloud

This guide will walk you through the process of setting up and using a User-Defined Function (UDF) in TDCloud. Follow the steps below to achieve this.

Step 1: Login to TDCloud

1. Login to TDCloud: Navigate to tgcloud.io and log in with your credentials.
2. Select Workspace:
   • Go to Workgroups > Workspace.
   • Click on the desired workspace name.
   • Copy the host URL for the selected workspace.

Step 2: Get the id_token

1. Open the browser console (usually by pressing F12 or Ctrl+Shift+I).

2. Run the following JavaScript command to retrieve the id_token:

   console.log(document.cookie.split('; ').find(row => row.startsWith('idTokenV4=')).split('=')[1]);

3. Copy the id_token from the output.

Step 3: Verify the Host and id_token

1. Use the copied host and id_token to verify access to the workspace.

2. Run the following curl command in your terminal:

   curl https://{{host}}:api/ping2 -H 'Authorization: Bearer {{idTokenV4}}'

3. Replace {{host}} with the copied host URL and {{idTokenV4}} with the copied id_token.

4. Expected Result:

   {
     "error": false,
     "message": "pong",
     "results": null
   }

Step 4: Upload a UDF as ExprFunctions

1. Use the following curl command to upload the UDF:

   curl -X PUT https://{{host}}/api/udf/ExprFunctions \
        -H 'Authorization: Bearer {{idTokenV4}}' \
        -H 'Content-Type: application/json' \
        -d '{
              "udf": "inline bool greater_than_three (double x) {\nreturn x > 5;\n}"
            }'

2. Expected Result:

   {
     "error": false,
     "message": "",
     "results": null
   }

Step 5: Retrieve the ExprFunctions

1. Use the following curl command to get the ExprFunctions:

   curl https://{{host}}/api/udf/ExprFunctions \
        -H 'Authorization: Bearer {{idTokenV4}}'

2. Expected Result:

   {
     "error": false,
     "message": "",
     "results": {
       "udf": "inline bool greater_than_three (double x) {\nreturn x > 5;\n}"
     }
   }

Step 6: Use the UDF in a GSQL Query

1. Create the GSQL Query:

   CREATE QUERY CallUDFExample() {
     # Declare a variable to store the input value and the result
     double input_value = 6.0;
     bool result;
   
     # Call the UDF with the input value
     result = greater_than_three(input_value);
   
     # Print the input value and the result
     PRINT input_value, result;
   }

2. Install the Query:

   INSTALL QUERY CallUDFExample

3. Run the Query:

   RUN QUERY CallUDFExample()

4. Expected Result:

   [
     {
       "input_value": 6,
       "result": true
     }
   ]

By following these steps, you will have successfully set up and used a UDF in TDCloud.