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.

Query Functions REST API

  • reference
    +

    Overview

    The Query 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.

    Version information

    Version : 7.6

    Host information

    {scheme}://{host}:{port}

    The URL scheme, host, and port are as follows.

    Component Description

    scheme

    The URL scheme. Use https for secure access.

    Values: http, https
    Example: http

    host

    The host name or IP address of a node running the Query service.

    Example: localhost

    port

    The Query service REST port. Use 18093 for secure access.

    Values: 8093, 18093
    Example: 8093

    Resources

    This section describes the operations available with this REST API.

    Delete a Library
    Read All Libraries
    Read a Library
    Create or Update a Library

    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

    Path Parameters

    Name Description Schema

    library
    required

    The name of a library.

    String
    Query Parameters

    Name Description Schema

    bucket
    optional

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

    String

    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.

    400

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

    404

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

    Security

    Type Name

    http (basic)

    Scope

    http (basic)

    Global

    Example HTTP Request

    Request 1: Delete a global library entirely.

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

    Request 2: Delete a scoped library entirely.

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

    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.

    Produces

    • application/json

    Parameters

    Query Parameters

    Name Description Schema

    bucket
    optional

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

    String

    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.

    Library array

    400

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

    Security

    Type Name

    http (basic)

    Scope

    http (basic)

    Global

    Example HTTP Request

    Request 3: Fetch all defined libraries.

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

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

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

    Example HTTP Response

    Result of request 3.

    Response 200
    [
  {
    "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 4.

    Response 200
    [
  {
    "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.

    Produces

    • application/json

    Parameters

    Path Parameters

    Name Description Schema

    library
    required

    The name of a library.

    String
    Query Parameters

    Name Description Schema

    bucket
    optional

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

    String

    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.

    404

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

    Security

    Type Name

    http (basic)

    Scope

    http (basic)

    Global

    Example HTTP Request

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

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

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

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

    Example HTTP Response

    Result of request 5.

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

    Result of request 6.

    Response 200
    {
  "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.
    Consumes

    • application/json

    Parameters

    Path Parameters

    Name Description Schema

    library
    required

    The name of a library.

    String
    Query Parameters

    Name Description Schema

    bucket
    optional

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

    String

    scope
    optional

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

    String
    Body Parameter

    Name Description Schema

    Body
    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.

    400

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

    404

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

    Security

    Type Name

    http (basic)

    Scope

    http (basic)

    Global

    Example HTTP Request

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

    Curl request
    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 8: Add a function called mul to the global library, leaving the other functions unchanged.

    Curl request
    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 9: Edit the function called sub to use a helper function called helper, leaving the other functions unchanged.

    Curl request
    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 10: Remove the function called sub and the helper function called helper, leaving the other functions unchanged.

    Curl request
    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 11: Create or update a scoped library called science. The library contains one function, f2c.

    Curl request
    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); }'

    Definitions

    This section describes the properties consumed and returned by this REST API.

    Functions
    Library

    Functions

    Object

    Property Schema

    additional
    property

    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

    Library

    Object

    Property 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

    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 : http

    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 : http

    Refer to Roles for more details.