February 16, 2025
+ 12

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

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

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
json
{ "math": "function add(a, b) { return a + b; } function mul(a, b) { return a * b; }" }

Result of request 6.

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

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.