Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Functions REST API

    March 16, 2025
    + 12

    Overview

    The Functions REST API is a secondary API provided by the Query service. This API enables you to manage the JavaScript libraries and objects that are used to create SQL++ user-defined functions.

    The base URL schemes for this API are as follows:

    where node is the host name or IP address of a computer running the Query service.

    Version information

    Version : 7.2

    URI scheme

    Host : localhost:8093
    Schemes : HTTP

    Consumes

    • application/json

    Produces

    • application/json

    Paths

    Table of Contents

    Read All Libraries

    GET /evaluator/v1/libraries

    Description

    Returns all libraries and functions.

    By default, this operation returns all global libraries and functions, and all scoped libraries and functions. To return all the libraries and functions in a single scope, specify a bucket and scope.

    Parameters

    Type Name Description Schema

    Query

    bucket
    optional

    For scoped libraries only. The bucket from which to fetch libraries.

    string

    Query

    scope
    optional

    For scoped libraries only. The scope from which to fetch libraries.

    string

    To fetch libraries from a scope, you must specify both the bucket and scope parameters. You cannot specify one without the other.

    Responses

    HTTP Code Description Schema

    200

    An array of objects, each giving information about a single library.

    < Libraries > array

    400

    Bad request. The path may not conform to the schema.

    string

    Security

    Type Name

    basic

    Global

    basic

    Scope

    Example HTTP request

    Request 1: Fetch all defined libraries.

    Curl request
    sh
    Copy
    curl -X GET \
"http://localhost:8093/evaluator/v1/libraries" \
-u Administrator:password

    Request 2: Fetch all defined libraries in the specified scope.

    Curl request
    sh
    Copy
    curl -X GET \
"http://localhost:8093/evaluator/v1/libraries?bucket=travel-sample&scope=inventory" \
-u Administrator:password

    Example HTTP response

    Result of request 1.

    Response 200
    json
    Copy
    [
  {
    "name": "math",
    "bucket": "",
    "scope": "",
    "code": "function add(a, b) { return a + b; } function mul(a, b) { return a * b; }"
  },
  {
    "name": "science",
    "bucket": "travel-sample",
    "scope": "inventory",
    "code": "function f2c(f) { return (5/9)*(f-32); }"
  }
]

    Result of request 2.

    Response 200
    json
    Copy
    [
  {
    "name": "science",
    "bucket": "travel-sample",
    "scope": "inventory",
    "code": "function f2c(f) { return (5/9)*(f-32); }"
  }
]

    Read a Library

    GET /evaluator/v1/libraries/{library}

    Description

    Returns a library with all its functions.

    By default, this operation returns a global library. For a scoped library, you must specify the bucket and scope.

    Parameters

    Type Name Description Schema

    Path

    library
    required

    The name of a library.

    string

    Query

    bucket
    optional

    For scoped libraries only. The bucket in which the library is stored.

    string

    Query

    scope
    optional

    For scoped libraries only. The scope in which the library is stored.

    string

    To read a scoped library, you must specify both the bucket and scope parameters. You cannot specify one without the other.

    Responses

    HTTP Code Description Schema

    200

    An object with a single property, giving information about the specified library.

    Functions

    400

    Bad request. The path may not conform to the schema.

    string

    404

    Not found. The library name in the path may be incorrect, or the bucket and scope may be specified incorrectly.

    string

    Security

    Type Name

    basic

    Global

    basic

    Scope

    Example HTTP request

    Request 3: Get all functions in the specified global library.

    Curl request
    sh
    Copy
    curl -X GET \
"http://localhost:8093/evaluator/v1/libraries/math" \
-u Administrator:password

    Request 4: Get all functions in the specified scoped library.

    Curl request
    sh
    Copy
    curl -X GET \
"http://localhost:8093/evaluator/v1/libraries/science?bucket=travel-sample&scope=inventory" \
-u Administrator:password

    Example HTTP response

    Result of request 3.

    Response 200
    json
    Copy
    {
  "math": "function add(a, b) { return a + b; } function mul(a, b) { return a * b; }"
}

    Result of request 4.

    Response 200
    json
    Copy
    {
  "science": "function f2c(f) { return (5/9)*(f-32); }"
}

    Create or Update a Library

    POST /evaluator/v1/libraries/{library}

    Description

    Creates the specified library and its associated functions. If the specified library exists, the existing library is overwritten.

    By default, this operation creates or updates a global library. For a scoped library, you must specify the bucket and scope.

    • To add a function to a library, update the library with all existing functions, plus the new function.

    • To update a function, update the library with all existing functions, including the updated function definition.

    • To delete a function from a library, update the library with all existing functions, without the deleted function.

    Parameters

    Type Name Description Schema

    Path

    library
    required

    The name of a library.

    string

    Query

    bucket
    optional

    For scoped libraries only. The bucket in which the library is stored.

    string

    Query

    scope
    optional

    For scoped libraries only. The scope in which the library is stored.

    string

    Body

    functions
    required

    The JavaScript code for all functions in the library.

    string

    To create or update a scoped library, you must specify both the bucket and scope parameters. You cannot specify one without the other.

    Responses

    HTTP Code Description Schema

    200

    The operation was successful.

    string

    400

    Bad request. The body of the request may be incorrect, or the path may not conform to the schema.

    string

    404

    Not found. The library name in the path may be incorrect, or the bucket and scope may be specified incorrectly.

    string

    Security

    Type Name

    basic

    Global

    basic

    Scope

    Example HTTP request

    Request 5: Create or update a global library called math. The library contains two functions, add and sub.

    Curl request
    sh
    Copy
    curl -X POST \
"http://localhost:8093/evaluator/v1/libraries/math" \
-u Administrator:password \
-H 'content-type: application/json' \
-d 'function add(a, b) { let data = a + b; return data; }
    function sub(a, b) { let data = a - b; return data; }'

    Request 6: Add a function called mul to the global library, leaving the other functions unchanged.

    Curl request
    sh
    Copy
    curl -X POST \
"http://localhost:8093/evaluator/v1/libraries/math" \
-u Administrator:password \
-H 'content-type: application/json' \
-d 'function add(a, b) { let data = a + b; return data; }
    function sub(a, b) { let data = a - b; return data; }
    function mul(a, b) { let data = a * b; return data; }'

    Request 7: Edit the function called sub to use a helper function called helper, leaving the other functions unchanged.

    Curl request
    sh
    Copy
    curl -X POST \
"http://localhost:8093/evaluator/v1/libraries/math" \
-u Administrator:password \
-H 'content-type: application/json' \
-d 'function add(a, b) { let data = a + b; return data; }
    function mul(a, b) { let data = a * b; return data; }
    function sub(a, b) { return helper(a, b); }
    function helper(a, b) { return a - b; }'

    Request 8: Remove the function called sub and the helper function called helper, leaving the other functions unchanged.

    Curl request
    sh
    Copy
    curl -X POST \
"http://localhost:8093/evaluator/v1/libraries/math" \
-u Administrator:password \
-H 'content-type: application/json' \
-d 'function add(a, b) { let data = a + b; return data; }
    function mul(a, b) { let data = a * b; return data; }'

    Request 9: Create or update a scoped library called science. The library contains one function, f2c.

    Curl request
    sh
    Copy
    curl -X POST \
"http://localhost:8093/evaluator/v1/libraries/science?bucket=travel-sample&scope=inventory" \
-u Administrator:password \
-H 'content-type: application/json' \
-d 'function f2c(f) { return (5/9)*(f-32); }'

    Delete a Library

    DELETE /evaluator/v1/libraries/{library}

    Description

    Deletes the specified library entirely.

    By default, this operation deletes a global library. For a scoped library, you must specify the bucket and scope.

    Before you can delete a library, you must first drop all SQL++ external user-defined functions which point to any of the JavaScript functions within that library. For further details, refer to DROP FUNCTION.

    Parameters

    Type Name Description Schema

    Path

    library
    required

    The name of a library.

    string

    Query

    bucket
    optional

    For scoped libraries only. The bucket in which the library is stored.

    string

    Query

    scope
    optional

    For scoped libraries only. The scope in which the library is stored.

    string

    To delete a scoped library, you must specify both the bucket and scope parameters. You cannot specify one without the other.

    Responses

    HTTP Code Description Schema

    200

    The operation was successful.

    string

    400

    Bad request. The path may not conform to the schema.

    string

    404

    Not found. The library name in the path may be incorrect, or the bucket and scope may be specified incorrectly.

    string

    Security

    Type Name

    basic

    Global

    basic

    Scope

    Example HTTP request

    Request 10: Delete a global library entirely.

    Curl request
    sh
    Copy
    curl -X DELETE \
"http://localhost:8093/evaluator/v1/libraries/math" \
-u Administrator:password

    Request 11: Delete a scoped library entirely.

    Curl request
    sh
    Copy
    curl -X DELETE \
"http://localhost:8093/evaluator/v1/libraries/science?bucket=travel-sample&scope=inventory" \
-u Administrator:password

    Definitions

    Table of Contents

    Libraries

    Name Description Schema

    name
    required

    The name of a library.
    Example : "math"

    string

    bucket
    required

    For scoped libraries, the bucket in which the library is stored. For global libraries, this string is empty.
    Example : "travel-sample"

    string

    scope
    required

    For scoped libraries, the scope in which the library is stored. For global libraries, this string is empty.
    Example : "inventory"

    string

    code
    required

    The JavaScript code for all functions in the library.
    Example : "function add(a, b) { return a + b; } function mul(a, b) { return a * b; }"

    string

    Functions

    Name Description Schema

    library
    required

    The JavaScript code for all functions in the library.

    The name of the property is the name of the library.
    Example : "function add(a, b) { return a + b; } function mul(a, b) { return a * b; }"

    string

    Security

    The Functions API supports admin credentials. Credentials can be passed via HTTP headers (HTTP basic authentication).

    Global

    To manage global libraries, users must have the Manage Global External Functions RBAC role.

    This role enables you to create, read, update, or delete any global library, but does not give you access to any scoped libraries.

    Type : basic

    Scope

    To manage scoped libraries, users must have the Manage Scope External Functions RBAC role, with permissions on the specified bucket and scope.

    This role enables you to create, read, update, or delete any library in the scope to which you have access, but does not give you access to any other scoped libraries. In addition, this role enables you to read any global library, but not to create, update, or delete them.

    Type : basic

    Refer to Roles for more details.