Returns `true` if all of the conditions are met. See also <<any_fn>>.
*Accepts:* `null`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_ *** *†*
Alias: `condition`
|`boolean`
|The conditions to check.
|===
*Returns:* `boolean`
[float]
[[alterColumn_fn]]
=== `alterColumn`
Converts between core types, including `string`, `number`, `null`, `boolean`, and `date`, and renames columns. See also <<mapColumn_fn>> and <<staticColumn_fn>>.
*Accepts:* `datatable`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_ ***
Alias: `column`
|`string`
|The name of the column to alter.
|`name`
|`string`
|The resultant column name. Leave blank to not rename.
|`type`
|`string`
|The type to convert the column to. Leave blank to not change the type.
|===
*Returns:* `datatable`
[float]
[[any_fn]]
=== `any`
Returns `true` if at least one of the conditions is met. See also <<all_fn>>.
*Accepts:* `null`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_ *** *†*
Alias: `condition`
|`boolean`
|The conditions to check.
|===
*Returns:* `boolean`
[float]
[[as_fn]]
=== `as`
Creates a `datatable` with a single value. See also <<getCell_fn>>.
*Accepts:* `string`, `boolean`, `number`, `null`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_
Alias: `name`
|`string`
|The name to give the column.
Default: `"value"`
|===
*Returns:* `datatable`
[float]
[[asset_fn]]
=== `asset`
Retrieves Canvas workpad asset objects to provide as argument values. Usually images.
*Accepts:* `null`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_ ***
Alias: `id`
|`string`
|The ID of the asset to retrieve.
|===
*Returns:* `string`
[float]
[[axisConfig_fn]]
=== `axisConfig`
Configures the axis of a visualization. Only used with <<plot_fn>>.
*Accepts:* `null`
[cols="3*^<"]
|===
|Argument |Type |Description
|`max`
|`number`, `string`, `null`
|The maximum value displayed in the axis. Must be a `number`, a date in milliseconds since epoch, or an ISO8601 `string`
|`min`
|`number`, `string`, `null`
|The minimum value displayed in the axis. Must be a `number`, a date in milliseconds since epoch, or an ISO8601 `string`
|`position`
|`string`
|The position of the axis labels. For example, `"top"`, `"bottom"`, `"left"`, or `"right"`.
Default: `"left"`
|`show`
|`boolean`
|Show the axis labels?
Default: `true`
|`tickSize`
|`number`, `null`
|The increment size between each tick. Use for `number` axes only.
Builds a `case` (including a condition/result) to pass to the <<switch_fn>> function.
*Accepts:* `any`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_
Alias: `when`
|`any`
|The value compared to the _context_ to see if they are equal. The `when` argument is ignored when the `if` argument is also specified.
|`if`
|`boolean`
|This value indicates whether the condition is met. The `if` argument overrides the `when` argument when both are provided.
|`then` ***
|`any`
|The value returned if the condition is met.
|===
*Returns:* `case`
[float]
[[clear_fn]]
=== `clear`
Clears the _context_, and returns `null`.
*Accepts:* `null`
*Returns:* `null`
[float]
[[columns_fn]]
=== `columns`
Includes or excludes columns from a data table. If you specify both, this will exclude first.
*Accepts:* `datatable`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_
Alias: `include`
|`string`
|A comma-separated list of column names to keep in the `datatable`.
|`exclude`
|`string`
|A comma-separated list of column names to remove from the `datatable`.
|===
*Returns:* `datatable`
[float]
[[compare_fn]]
=== `compare`
Compares the _context_ to specified value to determine `true` or `false`.
Usually used in combination with <<if_fn>> or <<case_fn>>. This only works with primitive types,
such as `number`, `string`, and `boolean`. See also <<eq_fn>>, <<gt_fn>>, <<gte_fn>>, <<lt_fn>>, <<lte_fn>>, and <<neq_fn>>.
*Accepts:* `string`, `number`, `boolean`, `null`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_
Alias: `op`
|`string`
|The operator to use in the comparison: `eq` (equal to), `gt` (greater than), `gte` (greater than or equal to), `lt` (less than), `lte` (less than or equal to), `ne` or `neq` (not equal to).
Default: `"eq"`
|`to`
Alias: `this`, `b`
|`any`
|The value compared to the _context_.
|===
*Returns:* `boolean`
[float]
[[containerStyle_fn]]
=== `containerStyle`
Creates an object used for styling an element's container, including background, border, and opacity.
*Accepts:* `null`
[cols="3*^<"]
|===
|Argument |Type |Description
|`backgroundColor`
|`string`
|A valid CSS background color.
|`backgroundImage`
|`string`
|A valid CSS background image.
|`backgroundRepeat`
|`string`
|A valid CSS background repeat.
Default: `"no-repeat"`
|`backgroundSize`
|`string`
|A valid CSS background size.
Default: `"contain"`
|`border`
|`string`
|A valid CSS border.
|`borderRadius`
|`string`
|The number of pixels to use when rounding the corners.
|`opacity`
|`number`
|A number between 0 and 1 that represents the degree of transparency of the element.
|`overflow`
|`string`
|A valid CSS overflow.
Default: `"hidden"`
|`padding`
|`string`
|The distance of the content, in pixels, from the border.
|===
*Returns:* `containerStyle`
[float]
[[context_fn]]
=== `context`
Returns whatever you pass into it. This can be useful when you need to use the
_context_ as an argument to a function as a sub-expression.
Returns the current time, or a time parsed from a `string`, as milliseconds since epoch.
*Accepts:* `null`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_
Alias: `value`
|`string`
|A date string to be parsed into milliseconds since epoch. The date string be either a valid JavaScript Date input or a string to parse
using the `format` argument. Must be an ISO8601 string or you must provide the format.
|`format`
|`string`
|The MomentJS format for parsing the optional date
`string`. See the https://momentjs.com/docs/#/displaying/[MomentJS documentation].
|===
*Returns:* `number`
[float]
[[demodata_fn]]
=== `demodata`
A mock data set that includes project CI times with usernames, countries, and run phases.
*Accepts:* `filter`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_
Alias: `type`
|`string`
|The name of the demo data set to use.
Default: `"ci"`
|===
*Returns:* `datatable`
[float]
[[do_fn]]
=== `do`
Executes multiple sub-expressions, then returns the original _context_. Use for running functions that produce an action or side effect without changing the original _context_.
*Accepts:* `any`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_ *†*
Aliases: `expression`, `exp`, `fn`, `function`
|`any`
|The sub-expressions to execute. The return values of these sub-expressions are not available in the root pipeline as this function simply returns the _context_.
|===
*Returns:* Original _context_
[float]
[[dropdownControl_fn]]
=== `dropdownControl`
Configures a dropdown filter control element.
*Accepts:* `datatable`
[cols="3*^<"]
|===
|Argument |Type |Description
|`filterColumn` ***
|`string`
|The column or field that you want to filter.
|`valueColumn` ***
|`string`
|The column or field to extract the unique values for the drop-down control.
|The font weight. For example, `"normal"`, `"bold"`, `"bolder"`, `"lighter"`, `"100"`, `"200"`, `"300"`, `"400"`, `"500"`, `"600"`, `"700"`, `"800"`, or `"900"`.
Default: `"normal"`
|===
*Returns:* `style`
[float]
[[formatdate_fn]]
=== `formatdate`
Formats an ISO8601 date string or a date in milliseconds since epoch using MomentJS. See https://momentjs.com/docs/#/displaying/.
*Accepts:* `number`, `string`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_ ***
Alias: `format`
|`string`
|A MomentJS format. For example, `"MM/DD/YYYY"`. See https://momentjs.com/docs/#/displaying/.
|===
*Returns:* `string`
[float]
[[formatnumber_fn]]
=== `formatnumber`
Formats a `number` into a formatted `string` using NumeralJS. See http://numeraljs.com/#format.
*Accepts:* `number`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_ ***
Alias: `format`
|`string`
|A NumeralJS format string. For example, `"0.0a"` or `"0%"`. See http://numeraljs.com/#format.
|A `true` or `false` indicating whether a condition is met, usually returned by a sub-expression. When unspecified, the original _context_ is returned.
|`then`
|`any`
|The return value when the condition is `true`. When unspecified and the condition is met, the original _context_ is returned.
|`else`
|`any`
|The return value when the condition is `false`. When unspecified and the condition is not met, the original _context_ is returned.
|===
*Returns:* Depends on your _context_ and arguments
[float]
[[image_fn]]
=== `image`
Displays an image. Provide an image asset as a `base64` data URL, or pass in a sub-expression.
*Accepts:* `null`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_
Aliases: `dataurl`, `url`
|`string`, `null`
|The HTTP(S) URL or `base64` data URL of an image.
|`mode`
|`string`
|`"contain"` shows the entire image, scaled to fit.
`"cover"` fills the container with the image, cropping from the sides or bottom as needed.
`"stretch"` resizes the height and width of the image to 100% of the container.
Default: `"contain"`
|===
Example value for the `dataurl` argument, formatted as a `base64` data URL:
Adds a column calculated as the result of other columns. Changes are made only when you provide arguments. See also <<alterColumn_fn>> and <<staticColumn_fn>>.
*Accepts:* `datatable`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_ ***
Alias: `column`
|`string`
|The name of the resulting column.
|`expression` ***
Alias: `exp`, `fn`, `function`
|`boolean`, `number`, `string`, `null`
|A Canvas expression that is passed to each row as a single row `datatable`.
|===
*Returns:* `datatable`
[float]
[[markdown_fn]]
=== `markdown`
Adds an element that renders Markdown text. TIP: Use the <<markdown_fn>> function for single numbers, metrics, and paragraphs of text.
*Accepts:* `datatable`, `null`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_ *†*
Alias: `expression`, `content`
|`string`
|A string of text that contains Markdown. To concatenate, pass the <<string_fn>> function multiple times.
Default: `""`
|`font`
|`style`
|The CSS font properties for the content. For example, `font-family` or `font-weight`.
Default: `{<<font_fn>>}`
|===
*Returns:* `render`
[float]
[[math_fn]]
=== `math`
Interprets a `TinyMath` math expression using a `number` or `datatable` as _context_. The `datatable` columns are available by their column name. If the _context_ is a `number`, it is available as `value`.
*Accepts:* `number`, `datatable`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_ ***
Alias: `expression`
|`string`
|An evaluated TinyMath expression. See <<canvas-tinymath-functions>>.
|===
*Returns:* `number`
[float]
[[metric_fn]]
=== `metric`
Displays a number over a label.
*Accepts:* `number`, `string`, `null`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_
Aliases: `label`, `text`, `description`
|`string`
|The text describing the metric.
Default: `""`
|`metricFont`
|`style`
|The CSS font properties for the metric. For example, `font-family` or `font-weight`.
|The palette colors. Accepts an HTML color name, HEX, HSL, HSLA, RGB, or RGBA.
|`gradient`
|`boolean`
|Make a gradient where supported?
Default: `false`
|`reverse`
|`boolean`
|Reverse the palette?
Default: `false`
|===
*Returns:* `palette`
[float]
[[pie_fn]]
=== `pie`
Configures a pie chart element.
*Accepts:* `pointseries`
[cols="3*^<"]
|===
|Argument |Type |Description
|`font`
|`style`
|The CSS font properties for the labels. For example, `font-family` or `font-weight`.
Default: `{<<font_fn>>}`
|`hole`
|`number`
|Draws a hole in the pie, 0-100, as a percentage of the pie radius.
Default: `0`
|`labelRadius`
|`number`
|The percentage of the container area to use as a radius for the label circle.
Default: `100`
|`labels`
|`boolean`
|Display the pie labels?
Default: `true`
|`legend`
|`string`, `boolean`
|The legend position. For example, `"nw"`, `"sw"`, `"ne"`, `"se"`. When `false`, the legend is hidden.
Default: `false`
|`palette`
|`palette`
|A `palette` object for describing the colors to use in this pie chart
Default: `{<<palette_fn>>}`
|`radius`
|`string`, `number`
|The radius of the pie as a percentage (between 0 and 1) of the available space. To automatically set radius, use `"auto"`.
Default: `"auto"`
|`seriesStyle` *†*
|`seriesStyle`
|A style of a specific series
|`tilt`
|`number`
|The percentage of tilt, where 1 is fully vertical, and 0 is completely flat.
Default: `1`
|===
*Returns:* `render`
[float]
[[plot_fn]]
=== `plot`
Configures a plot element.
*Accepts:* `pointseries`
[cols="3*^<"]
|===
|Argument |Type |Description
|`defaultStyle`
|`seriesStyle`
|The default style to use for every series.
Default: `{<<seriesStyle_fn>> points=5}`
|`font`
|`style`
|The CSS font properties for the labels. For example, `font-family` or `font-weight`.
Default: `{<<font_fn>>}`
|`legend`
|`string`, `boolean`
|The legend position. For example, `"nw"`, `"sw"`, `"ne"`, `"se"`, or `false`. When `false`, the legend is hidden.
Default: `"ne"`
|`palette`
|`palette`
|A `palette` object for describing the colors to use in this chart
Default: `{<<palette_fn>>}`
|`seriesStyle` *†*
|`seriesStyle`
|A style of a specific series
|`xaxis`
|`boolean`, `axisConfig`
|The axis configuration. When `false`, the axis is hidden.
Default: `true`
|`yaxis`
|`boolean`, `axisConfig`
|The axis configuration. When `false`, the axis is hidden.
Default: `true`
|===
*Returns:* `render`
[float]
[[ply_fn]]
=== `ply`
Subdivides a `datatable` by the unique values of the specified columns, and passes the resulting tables into an expression, then merges the outputs of each expression.
|An expression to pass into each resulting data table. Expressions must return a `datatable`. Use `as` to turn literals into `datatable`s. Multiple expressions must return the same number of rows. If you need to return a different row count, pipe into another instance of <<ply_fn>>. If multiple expressions return `datatable`s with the same column names, the last one wins.
|===
*Returns:* `datatable`
[float]
[[pointseries_fn]]
=== `pointseries`
Turns a `datatable` into a point series model. Currently we differentiate measure from dimensions by looking for a <<canvas-tinymath-functions, Tiny Math function>>. If you enter a TinyMath
expression in your argument, Canvas treats that argument as a measure. Otherwise, it is a dimension. Dimensions are combined to create unique keys. Measures are then deduplicated by those keys using the specified TinyMath function.
*Accepts:* `datatable`
[cols="3*^<"]
|===
|Argument |Type |Description
|`color`
|`string`
|An expression to use in determining the mark's color.
|`size`
|`string`
|The size of the marks. Only applicable to supported elements.
|`text`
|`string`
|The text to show on the mark. Only applicable to supported elements.
|`x`
|`string`
|The values along the X-axis.
|`y`
|`string`
|The values along the Y-axis.
|===
*Returns:* `pointseries`
[float]
[[progress_fn]]
=== `progress`
Configures a progress element
*Accepts:* `number`
[cols="3*^<"]
|===
|Argument |Type |Description
| _Unnamed_
Alias: `shape`
|`string`
|Select `"gauge"`, `"horizontalBar"`, `"horizontalPill"`, `"semicircle"`, `"unicorn"`, `"verticalBar"`, `"verticalPill"`, or `"wheel"`.
Default: `"gauge"`
|`barColor`
|`string`
|The color of the background bar.
Default: `"#f0f0f0"`
|`barWeight`
|`number`
|The thickness of the background bar.
Default: `20`
|`font`
|`style`
|The CSS font properties for the label. For example, `font-family` or `font-weight`.
Renders the _context_ as a specific element and sets element level options, such as background and border styling.
*Accepts:* `render`
[cols="3*^<"]
|===
|Argument |Type |Description
|`as`
|`string`
|The element type to render. You might want to use a specialized function instead, such as <<plot_fn>> or <<shape_fn>>.
|`css`
|`string`
|Any block of custom CSS to be scoped to the element
Default: `".canvasRenderEl{\n\n}"`
|`containerStyle`
|`containerStyle`
|The style for the container, including background, border, and opacity.
Default: `{<<containerStyle_fn>>}`
|===
*Returns:* `render`
[float]
[[repeatImage_fn]]
=== `repeatImage`
Configures a repeating image element.
*Accepts:* `number`
[cols="3*^<"]
|===
|Argument |Type |Description
|`emptyImage`
|`string`
|Fills the difference between the _context_ and `max` parameter for the element with this image. Provide an image asset as a `base64` data URL, or pass in a sub-expression.
Default: `null`
|`image`
|`string`
|The image to repeat. Provide an image asset as a `base64` data URL, or pass in a sub-expression.
|`max`
|`number`
|The maximum number of times the image can repeat.
Default: `100`
|`size`
|`number`
|The maximum height or width of the image, in pixels. When the image is taller than it is wide, this function limits the height.
Default: `100`
|===
Example value for the `image` argument, formatted as a `base64` data URL:
Creates an object used for describing the properties of a series on a chart. Use <<seriesStyle_fn>> inside of a charting function, like <<plot_fn>> or <<pie_fn>>.
*Accepts:* `null`
[cols="3*^<"]
|===
|Argument |Type |Description
|`label`
|`string`
|The name of the series to style.
|`color`
|`string`
|The line color.
|`lines`
|`number`
|The width of the line.
|`bars`
|`number`
|The width of bars.
|`points`
|`number`
|The size of points on line.
|`fill`
|`number`, `boolean`
|Should we fill in the points?
Default: `false`
|`stack`
|`number`, `null`
|Specifies if the series should be stacked. The number is the stack ID. Series with the same stack ID are stacked together.
|`horizontalBars`
|`boolean`
|Sets the orientation of the bars in the chart to horizontal.
Default: `false`
|===
*Returns:* `seriesStyle`
[float]
[[shape_fn]]
=== `shape`
Creates a shape.
*Accepts:* `null`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_
Alias: `shape`
|`string`
|Pick a shape
Default: `"square"`
|`border`
Alias `stroke`
|`number`
|An SVG color for the border outlining the shape.
|`borderWidth`
Alias: `strokeWidth`
|`number`
|The thickness of the border
Default: `0`
|`fill`
|`string`
|An SVG color to fill the shape.
Default: `"black"`
|`maintainAspect`
|`boolean`
|Maintain the shape's original aspect ratio?
Default: `false`
|===
*Returns:* shape
[float]
[[sort_fn]]
=== `sort`
Sorts a `datatable` by the specified column.
*Accepts:* `datatable`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_
Alias: `column`
|`string`
|The column to sort by. When unspecified, the `datatable` is sorted by the first column.
|`reverse`
|`boolean`
|Reverse the sorting order? When unspecified, the `datatable` is sorted in ascending order.
Default: `false`
|===
*Returns:* `datatable`
[float]
[[staticColumn_fn]]
=== `staticColumn`
Adds a column with the same static value in every row. See also <<alterColumn_fn>> and <<mapColumn_fn>>.
*Accepts:* `datatable`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_ ***
Alias: `column`, `name`
|`string`
|The name of the new column.
|`value`
|`string`, `number`, `boolean`, `null`
|The value to insert in each row in the new column. Tip: use a sub-expression to rollup other columns into a static value.
Default: `null`
|===
*Returns:* `datatable`
[float]
[[string_fn]]
=== `string`
Concatenates all of the arguments into a single string.
*Accepts:* `null`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_ *** *†*
Alias: `value`
|`string`, `number`, `boolean`
|The values to join together into one string. Include spaces where needed.
|===
*Returns:* `string`
[float]
[[switch_fn]]
=== `switch`
Performs conditional logic with multiple conditions. See also <<case_fn>>, which builds a `case` to pass to the <<switch_fn>> function.
*Accepts:* `any`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_ *** *†*
Alias: `case`
|`case`
|The conditions to check.
|`default`
Alias: `finally`
|`any`
|The value returned when no conditions are met. When unspecified and no conditions are met, the original _context_ is returned.
Retrieves a URL parameter to use in an expression. The <<urlparam_fn>> function always returns a `string`. For example, you can retrieve the value `"20"` from the parameter `myVar` from the URL `https://localhost:5601/app/canvas?myVar=20`.
*Accepts:* `null`
[cols="3*^<"]
|===
|Argument |Type |Description
|_Unnamed_ ***
Aliases: `var`, `variable`
|`string`
|The URL hash parameter to retrieve.
|`default`
|`string`
|The string returned when the URL parameter is unspecified.