Skip to content

DOC-11704: SQL++ managed Javascript UDFs #3520

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 15, 2024
Merged

DOC-11704: SQL++ managed Javascript UDFs #3520

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e712ebd
Update Monitor Queries
simon-dew Mar 15, 2024
5ebb23b
Update UDFs UI
simon-dew Mar 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 15 additions & 7 deletions modules/manage/pages/monitor/monitoring-n1ql-query.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2270,22 +2270,26 @@ __optional__

|**text** +
__optional__
|For inline functions only: the verbatim text of the function.
|For inline functions: the verbatim text of the function.

'''

For {sqlpp} managed user-defined functions: the external code defining the function.
|String

|**library** +
__optional__
|For JavaScript functions only: the library containing the function.
|For external functions only: the library containing the function.
|String

|**name** +
__optional__
|For JavaScript functions only: the relative name of the library.
|For external functions only: the relative name of the library.
|String

|**object** +
__optional__
|For JavaScript functions only: the object defining the function.
|For external functions only: the object defining the function.
|String
|===

Expand Down Expand Up @@ -2449,17 +2453,21 @@ __optional__

|**text** +
__optional__
|For inline functions only: the verbatim text of the function.
|For inline functions: the verbatim text of the function.

'''

For {sqlpp} managed user-defined functions: the external code defining the function.
|String

|**library** +
__optional__
|For JavaScript functions only: the library containing the function.
|For external functions only: the library containing the function.
|String

|**object** +
__optional__
|For JavaScript functions only: the object defining the function.
|For external functions only: the object defining the function.
|String

|**avgServiceTime** +
Expand Down
39 changes: 24 additions & 15 deletions modules/tools/pages/udfs-ui.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,19 +5,24 @@
[abstract]
{description}

Starting from Couchbase Server 7.1, the Couchbase Administration console provides an interface to create, update, or delete user-defined functions written in {sqlpp} or JavaScript.
Couchbase Administration console provides an interface to create, update, or delete user-defined functions written in {sqlpp} or JavaScript.

Start at the administration console and select menu:Query[UDFs] from the menus to access the *UDF* screen.
Start at the administration console and select menu:Query[UDF] from the menus to access the *UDF* screen.

image::udf-screen.png[alt="screen for adding user-defined functions"]

== Javascript Function Libraries
If you have created any external libraries to store external function code, these are listed in the *JavaScript Function Libraries* section.

If you have created any inline or external user-defined functions, these are listed in the *User-Defined Functions* section.
This includes {sqlpp} managed user-defined functions -- that is, JavaScript functions which are not stored in a library.

== JavaScript Function Libraries

Click on the `{plus}{nbsp}add function library` link to create a library of JavaScript functions.

image::udf-add-library.png[,500, alt="add javascript library screen"]

When you create a new library, an example function (`add`) is supplied as an example.
When you create a new library, an example function (`add`) is supplied as an example.
You can delete it when you add your own function, or leave it to serve as a basic example.

You can set a *Namespace* for your library which will restrict its access to users that have permissions to access the bucket and scope specified by the namespace.
Expand All @@ -28,7 +33,7 @@ Click btn:[Save] to save the library and return to the main UDF screen, or btn:[

image::udf-screen-with-library.png[alt="udf screen with library added"]

You can *edit* the library again to add and/or delete functions contained inside it.
You can *edit* the library again to add and/or delete functions contained inside it.

You can also delete the whole library by clicking on the *drop* link.

Expand All @@ -37,6 +42,11 @@ You can also delete the whole library by clicking on the *drop* link.
You can add your own user-defined functions in the lower *User-Defined Functions* list.
These functions can be one of two types:

[horizontal]
*Inline*:: This is a function written in {sqlpp} which can be used as part of another {sqlpp} statement, such as xref:n1ql:n1ql-language-reference/selectintro.adoc[SELECT] and xref:n1ql:n1ql-language-reference/execfunction.adoc[EXECUTE FUNCTION].

*JavaScript*:: You can create {sqlpp} functions that call the JavaScript functions defined in your library.

To add a user-defined function, click on *{plus}{nbsp}add function* below the *User-Defined Functions* list.

image::udf-add-function-inline.png[,500, alt="Add function screen"]
Expand All @@ -50,20 +60,19 @@ The name must be unique and is case-insensitive.

You can define a list of fixed parameters for your function, or you can use the `...` symbol which indicates a variable length function list defined as `args[]`.

The *Function Type* can be either `inline` or `Javascript`:

[horizontal]
*Inline*:: This is a function written in {sqlpp} which can be used as part of another {sqlpp} statement, such as xref:n1ql:n1ql-language-reference/selectintro.adoc[SELECT] and xref:n1ql:n1ql-language-reference/execfunction.adoc[EXECUTE FUNCTION].

*JavaScript*:: You can create {sqlpp} functions that call the Javascript functions defined in your library.
The *Function Type* can be either `inline` or `javascript`.

If you are defining an `inline` function then you can fill in any valid {sqlpp} expression which can then be used as part of another {sqlpp} statement.
This is the default when creating a function.

If you switch *Function Type* to `Javascript` then the dialog will change to configure a JavaScript function call.
If you switch *Function Type* to `javascript` then the dialog will change to configure a JavaScript function call.

image::udf-add-function-js.png[,500, alt="add JavaScript function"]

image::udf-add-function-js.png[,500, alt="add Javascript function"]
Then you select the JavaScript Library where you created your JavaScript function, and the name of your function.
(There is no need to include the parameters.)

Then you select the `Javascript Library` where you created your Javascript function, and the name of your function. (There is no need to include the parameters.)
Once the details have been filled, you can click the btn:[Save Function] to save the function and exit the dialog, or click on btn:[Cancel] to exit the dialog without saving the details.

Once the details have been filled, you can click the btn:[Save Function] to save the function and exit the dialog, or click on btn:[Cancel] to exit the dialog without saving the details.
NOTE: You cannot use the UDF console to create {sqlpp} managed user-defined functions -- that is, JavaScript functions which are not stored in a library.
To do this, see xref:n1ql:n1ql-language-reference/createfunction.adoc[].