Functions

Data Studio allows you to not only create your own Functions (by combining native Functions), but also to categorize them for ease of use and share them with other users. You can also assign variables and use parameters to make your Functions more succinct and easy to maintain/test.

External label specifications

External labels for Functions have to:

• contain only alphanumeric characters or underscores,
• be less than 255 characters long and
• not start with a number or an underscore.

Create a custom Function

To create a Function:

1. Go to Functions.
2. Click Create new Function.
3. Enter a descriptive name.
4. (Optional) Enter a summary (this will appear in the Function list).
5. (Optional) Enter a description which could describe what the Function does or when/why it should be used. This is particularly helpful if you plan to share it with other users.
6. (Optional) Enter an External label to identify this Function from systems external to Data Studio. If you don't enter a value, it will be auto-populated.
7. (Optional) Select a category for the Function to make it easier to find.
8. (Optional) To help other users find this Function, enter any aliases (comma separated).
9. (Optional) Select Data tags to suggest this Function for tagged columns.
10. (Optional) Include the Function when using Suggest validation or Suggest transformation.
11. Click Apply to save changes.

Make a Function re-usable

You'll often get to the Function editor from a specific Workflow step (such as Filter, Transform or Validate). While building out the Function, you might decide that the operation (or part of it) would be useful in other steps or even other Workflows. To do that, you have to make it re-usable first.

Turn on Drag select (or Ctrl+click), highlight all of the required Function components (ensure this returns to a single value to be a valid Function) and click Make re-useable. Give your Function a name, description and other details then Apply to create a custom Function.

Using variables

Variables are useful to simplify complex Functions and make them easier to read. They are especially useful when using the same value multiple times in a Function.

To turn part of your Function into a variable, click on a step then Make variable. Give it a name and some description text. If you add a description, the text will appear as a tooltip when hovering over the variable, wherever it's used in the Function..

Once created, it is possible to select this Variable as an Input value anywhere else in the Function.

As well as readability, variables appear as columns in the Preview grid. This allows you to see the value of the input mid-way through the Function, next to the final result, so you could introduce a variable at each stage of a complex Transformation to ensure the results are correct at each stage.

Testing your Function with parameters

To test that a Function works in different scenarios, you can specify test data for it by clicking Parameters while in edit mode.

A parameter can be a column of values from an existing Dataset/View, or you can define your own comma-separated list of test values. The values you enter will be treated as alphanumeric unless a datatype is specified:

• Numeric value - prefix with {n}, e.g.: {n}1234
• Boolean value - prefix with {b}, e.g.: {b}true
• Date value - prefix with {d}, e.g.: {d}1990-01-01 or {d:yyyy-MM-dd}1990-02-03
• Use double quotes " " if a test value contains a comma, e.g.: AB-123,{n}23.53,"Test, value"

Each parameter will appear as a column in the Preview grid, making it easy to check whether the Function is returning the expected result.

Function categories

Function categories help you organize your Functions and make them easier to locate in the Function editor. All native Functions are already in one of the existing Function categories.

Custom Functions can be added to an existing category, or new categories can be created (in Functions > Manage categories) by users who have the "Create and Edit Function Categories" permission in their Role.

Once created, Function categories are available across all Spaces.

Function versions

You can have more than one version of a Function. For example, you may want to improve a previously published Function. To create a new version in draft status, simply edit the Function.

To see the version history, go to Functions, select the required Function and click Options > Versions. To revert to a previous version, go to Functions and click Options > Revert to.

Share Functions

By default, a Function you create will be restricted to the Space it has been created in. You can share Functions with everyone by making them available to all Spaces. Only published Functions can be shared.

To share a Function:

1. Go to Functions and select the Function you want to share.
2. Click Options > Sharing Options. If this option cannot be selected, you may not have a published version of the Function.
3. Select the Scope of the sharing. Use Shared with all Spaces to make this Function available to all Spaces.
4. Click Apply to save changes.

You can use a scripting language to create new and manage existing Functions. Changes made to the script are then reflected in the Function canvas and vice versa, so you can use both interchangeably depending on the task.
Click Edit script to open the script editor and make the required changes.

To open a read-only version, click View script.

.

A script is ordered with parameters first, then variables, and finally a Function. Each parameter and variable must end with a semicolon. For example:

param Account Status;
param Payment Rating;
var RatingE = Contains([p:Payment Rating], 'E');
Or(
    Equals([p:Account Status], 'OPEN'),
    [v:RatingE]
)

Functions are selected using their external label, followed by brackets. For native Functions, this is typically the Function name without spaces. Parameters are created by using param = parameter; and variables are created assigning a Function var variableName = Function();

Function arguments have different syntax dependent on their type:

• Text values or strings should be in 'single quotes'.
• Numbers and booleans do not need quotes: 6, 7, true, false, null, ignore.
• Dates and times should be @(1999-12-31) or @(1999-12-31T11:59:59).
• Special characters should be in back quotes `Ascii 0`.
• Square brackets denote a column, parameter, variable or datasource: [c: column name], [p: parameter], [v: variable], [s: datasource], [sc: datasource column].
• Use Ctrl+Space after entering [c: or [p: or [v: to show available columns, parameters or variables.
• Curly brackets denote a multi argument within a Function, typically used when there is more than one comparison value. For example: Equals([c:Discount Code], {'A','D','P','S'}).

Function script editor tips

• Use Ctrl+Space to show available Functions or to suggest a Function according to what you have already typed.
• Hover over a Function name with the cursor to show the arguments required for that Function.
• Use Ctrl+Enter to validate and reformat the Function script.
• Syntax errors will typically correspond to a line (listed vertically) and a column (horizontal character). To help with identifying the position of errors, try splitting arguments onto different lines and use Ctrl+Enter to validate the Function.