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

      +

      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 N1QL 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 N1QL query engine.

      Version information

      Version : 7.1

      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
      curl -X GET \
"http://localhost:8093/evaluator/v1/libraries" \
-u Administrator:password

      Request 2: 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 1.

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

      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.

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

      Result of request 4.

      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.

      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
      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
      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
      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
      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
      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 N1QL 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
      curl -X DELETE \
"http://localhost:8093/evaluator/v1/libraries/math" \
-u Administrator:password

      Request 11: 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

      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.