Canvas function reference

Elastic Stack Serverless

Behind the scenes, Canvas is driven by a powerful expression language, with dozens of functions and other capabilities, including table transforms, type casting, and sub-expressions.

The Canvas expression language also supports TinyMath functions, which perform complex math calculations.

A * denotes a required argument.

A † denotes an argument can be passed multiple times.

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

Returns true if all of the conditions are met. See also any.

Expression syntax

all {neq "foo"} {neq "bar"} {neq "fizz"}
all condition={gt 10} condition={lt 20}

Code example

kibana
| selectFilter
| demodata
| math "mean(percent_uptime)"
| formatnumber "0.0%"
| metric "Average uptime"
  metricFont={
    font size=48 family="'Open Sans', Helvetica, Arial, sans-serif"
      color={
        if {all {gte 0} {lt 0.8}} then="red" else="green"
      }
      align="center" lHeight=48
  }
| render

This sets the color of the metric text to "red" if the context passed into metric is greater than or equal to 0 and less than 0.8. Otherwise, the color is set to "green".

Accepts: null

Returns: boolean

Converts between core types, including string, number, null, boolean, and date, and renames columns. See also mapColumn, mathColumn, and staticColumn.

Expression syntax

alterColumn "cost" type="string"
alterColumn column="@timestamp" name="foo"

Code example

kibana
| selectFilter
| demodata
| alterColumn "time" name="time_in_ms" type="number"
| table
| render

This renames the time column to time_in_ms and converts the type of the column’s values from date to number.

Accepts: datatable

Returns: datatable

Returns true if at least one of the conditions is met. See also all.

Expression syntax

any {eq "foo"} {eq "bar"} {eq "fizz"}
any condition={lte 10} condition={gt 30}

Code example

kibana
| selectFilter
| demodata
| filterrows {
    getCell "project" | any {eq "elasticsearch"} {eq "kibana"} {eq "x-pack"}
  }
| pointseries color="project" size="max(price)"
| pie
| render

This filters out any rows that don’t contain "elasticsearch", "kibana" or "x-pack" in the project field.

Accepts: null

Returns: boolean

Creates a datatable with a single value. See also getCell.

Expression syntax

as
as "foo"
as name="bar"

Code example

kibana
| selectFilter
| demodata
| ply by="project" fn={math "count(username)" | as "num_users"} fn={math "mean(price)" | as "price"}
| pointseries x="project" y="num_users" size="price" color="project"
| plot
| render

as casts any primitive value (string, number, date, null) into a datatable with a single row and a single column with the given name (or defaults to "value" if no name is provided). This is useful when piping a primitive value into a function that only takes datatable as an input.

In the example, ply expects each fn subexpression to return a datatable in order to merge the results of each fn back into a datatable, but using a math aggregation in the subexpressions returns a single math value, which is then cast into a datatable using as.

Accepts: string, boolean, number, null

Returns: datatable

Retrieves Canvas workpad asset objects to provide as argument values. Usually images.

Expression syntax

asset "asset-52f14f2b-fee6-4072-92e8-cd2642665d02"
asset id="asset-498f7429-4d56-42a2-a7e4-8bf08d98d114"

Code example

image dataurl={asset "asset-c661a7cc-11be-45a1-a401-d7592ea7917a"} mode="contain"
| render

The image asset stored with the ID "asset-c661a7cc-11be-45a1-a401-d7592ea7917a" is passed into the dataurl argument of the image function to display the stored asset.

Accepts: null

Returns: string

Configures the axis of a visualization. Only used with plot.

Expression syntax

axisConfig show=false
axisConfig position="right" min=0 max=10 tickSize=1

Code example

kibana
| selectFilter
| demodata
| pointseries x="size(cost)" y="project" color="project"
| plot defaultStyle={seriesStyle bars=0.75 horizontalBars=true}
  legend=false
  xaxis={axisConfig position="top" min=0 max=400 tickSize=100}
  yaxis={axisConfig position="right"}
| render

This sets the x-axis to display on the top of the chart and sets the range of values to 0-400 with ticks displayed at 100 intervals. The y-axis is configured to display on the right.

Accepts: null

Returns: axisConfig

Builds a case, including a condition and a result, to pass to the switch function.

Expression syntax

case 0 then="red"
case when=5 then="yellow"
case if={lte 50} then="green"

Code example

math "random()"
| progress shape="gauge" label={formatnumber "0%"}
  font={
    font size=24 family="'Open Sans', Helvetica, Arial, sans-serif" align="center"
      color={
        switch {case if={lte 0.5} then="green"}
          {case if={all {gt 0.5} {lte 0.75}} then="orange"}
          default="red"
      }
  }
  valueColor={
    switch {case if={lte 0.5} then="green"}
      {case if={all {gt 0.5} {lte 0.75}} then="orange"}
      default="red"
  }
| render

This sets the color of the progress indicator and the color of the label to "green" if the value is less than or equal to 0.5, "orange" if the value is greater than 0.5 and less than or equal to 0.75, and "red" if none of the case conditions are met.

Accepts: any

Returns: case

Clears the context, and returns null.

Accepts: null

Returns: null

Outputs the input in the console. This function is for debug purposes

Expression syntax

clog

Code example

kibana
| demodata
| clog
| filterrows fn={getCell "age" | gt 70}
| clog
| pointseries x="time" y="mean(price)"
| plot defaultStyle={seriesStyle lines=1 fill=1}
| render

This prints the datatable objects in the browser console before and after the filterrows function.

Accepts: any

Returns: Depends on your input and arguments

Includes or excludes columns from a datatable. When both arguments are specified, the excluded columns will be removed first.

Expression syntax

columns include="@timestamp, projects, cost"
columns exclude="username, country, age"

Code example

kibana
| selectFilter
| demodata
| columns include="price, cost, state, project"
| table
| render

This only keeps the price, cost, state, and project columns from the demodata data source and removes all other columns.

Accepts: datatable

Returns: datatable

Compares the context to specified value to determine true or false. Usually used in combination with <<if_fn>> or case. This only works with primitive types, such as number, string, boolean, null. See also eq, gt, gte, lt, lte, neq

Expression syntax

compare "neq" to="elasticsearch"
compare op="lte" to=100

Code example

kibana
| selectFilter
| demodata
| mapColumn project
  fn={getCell project |
    switch
      {case if={compare eq to=kibana} then=kibana}
      {case if={compare eq to=elasticsearch} then=elasticsearch}
      default="other"
  }
| pointseries size="size(cost)" color="project"
| pie
| render

This maps all project values that aren’t "kibana" and "elasticsearch" to "other". Alternatively, you can use the individual comparator functions instead of compare.

Accepts: string, number, boolean, null

Returns: boolean

Creates an object used for styling an element’s container, including background, border, and opacity.

Expression syntax

containerStyle backgroundColor="red"’
containerStyle borderRadius="50px"
containerStyle border="1px solid black"
containerStyle padding="5px"
containerStyle opacity="0.5"
containerStyle overflow="hidden"
containerStyle backgroundImage={asset id=asset-f40d2292-cf9e-4f2c-8c6f-a504a25e949c}
  backgroundRepeat="no-repeat"
  backgroundSize="cover"

Code example

shape "star" fill="#E61D35" maintainAspect=true
| render containerStyle={
    containerStyle backgroundColor="#F8D546"
      borderRadius="200px"
      border="4px solid #05509F"
      padding="0px"
      opacity="0.9"
      overflow="hidden"
  }

Accepts: null

Returns: containerStyle

Returns whatever you pass into it. This can be useful when you need to use context as argument to a function as a sub-expression.

Expression syntax

context

Code example

date
| formatdate "LLLL"
| markdown "Last updated: " {context}
| render

Using the context function allows us to pass the output, or context, of the previous function as a value to an argument in the next function. Here we get the formatted date string from the previous function and pass it as content for the markdown element.

Accepts: any

Returns: Depends on your input and arguments

Creates a datatable with a list of columns, and 1 or more empty rows. To populate the rows, use mapColumn or mathColumn.

Expression syntax

createTable id="a" id="b"
createTable id="a" name="A" id="b" name="B" rowCount=5

Code example

var_set
name="logs" value={essql "select count(*) as a from kibana_sample_data_logs"}
name="commerce" value={essql "select count(*) as b from kibana_sample_data_ecommerce"}
| createTable ids="totalA" ids="totalB"
| staticColumn name="totalA" value={var "logs" | getCell "a"}
| alterColumn column="totalA" type="number"
| staticColumn name="totalB" value={var "commerce" | getCell "b"}
| alterColumn column="totalB" type="number"
| mathColumn id="percent" name="percent" expression="totalA / totalB"
| render

This creates a table based on the results of two essql queries, joined into one table.

Accepts: null

Returns: datatable

Creates a datatable from CSV input.

Expression syntax

csv "fruit, stock
  kiwi, 10
  Banana, 5"

Code example

csv "fruit,stock
  kiwi,10
  banana,5"
| pointseries color=fruit size=stock
| pie
| render

This creates a datatable with fruit and stock columns with two rows. This is useful for quickly mocking data.

Accepts: null

Returns: datatable

Returns the current time, or a time parsed from a specified string, as milliseconds since epoch.

Expression syntax

date
date value=1558735195
date "2019-05-24T21:59:55+0000"
date "01/31/2019" format="MM/DD/YYYY"

Code example

date
| formatdate "LLL"
| markdown {context}
  font={font family="Arial, sans-serif" size=30 align="left"
    color="#000000"
    weight="normal"
    underline=false
    italic=false}
| render

Using date without passing any arguments will return the current date and time.

Accepts: null

Returns: number

A sample data set that includes project CI times with usernames, countries, and run phases.

Expression syntax

demodata
demodata "ci"
demodata type="shirts"

Code example

kibana
| selectFilter
| demodata
| table
| render

demodata is a mock data set that you can use to start playing around in Canvas.

Accepts: filter

Returns: datatable

Executes multiple sub-expressions, then returns the original context. Use for running functions that produce an action or a side effect without changing the original context.

Accepts: any

Returns: Depends on your input and arguments

Configures a dropdown filter control element.

Expression syntax

dropdownControl valueColumn=project filterColumn=project
dropdownControl valueColumn=agent filterColumn=agent.keyword filterGroup=group1

Code example

demodata
| dropdownControl valueColumn=project filterColumn=project
| render

This creates a dropdown filter element. It requires a data source and uses the unique values from the given valueColumn (i.e. project) and applies the filter to the project column. Note: filterColumn should point to a keyword type field for Elasticsearch data sources.

Accepts: datatable

Returns: render

Returns an embeddable with the provided configuration

Accepts: filter

Returns: embeddable

Returns whether the context is equal to the argument.

Expression syntax

eq true
eq null
eq 10
eq "foo"

Code example

kibana
| selectFilter
| demodata
| mapColumn project
  fn={getCell project |
    switch
      {case if={eq kibana} then=kibana}
      {case if={eq elasticsearch} then=elasticsearch}
      default="other"
  }
| pointseries size="size(cost)" color="project"
| pie
| render

This changes all values in the project column that don’t equal "kibana" or "elasticsearch" to "other".

Accepts: boolean, number, string, null

Returns: boolean

Query Elasticsearch for the number of hits matching the specified query.

Expression syntax

escount index="logstash-*"
escount "currency:"EUR"" index="kibana_sample_data_ecommerce"
escount query="response:404" index="kibana_sample_data_logs"

Code example

kibana
| selectFilter
| escount "Cancelled:true" index="kibana_sample_data_flights"
| math "value"
| progress shape="semicircle"
  label={formatnumber 0,0}
  font={font size=24 family="'Open Sans', Helvetica, Arial, sans-serif" color="#000000" align=center}
  max={filters | escount index="kibana_sample_data_flights"}
| render

The first escount expression retrieves the number of flights that were cancelled. The second escount expression retrieves the total number of flights.

Accepts: filter

Returns: number

Query Elasticsearch for raw documents. Specify the fields you want to retrieve, especially if you are asking for a lot of rows.

Expression syntax

esdocs index="logstash-*"
esdocs "currency:"EUR"" index="kibana_sample_data_ecommerce"
esdocs query="response:404" index="kibana_sample_data_logs"
esdocs index="kibana_sample_data_flights" count=100
esdocs index="kibana_sample_data_flights" sort="AvgTicketPrice, asc"

Code example

kibana
| selectFilter
| esdocs index="kibana_sample_data_ecommerce"
  fields="customer_gender, taxful_total_price, order_date"
  sort="order_date, asc"
  count=10000
| mapColumn "order_date"
  fn={getCell "order_date" | date {context} | rounddate "YYYY-MM-DD"}
| alterColumn "order_date" type="date"
| pointseries x="order_date" y="sum(taxful_total_price)" color="customer_gender"
| plot defaultStyle={seriesStyle lines=3}
  palette={palette "#7ECAE3" "#003A4D" gradient=true}
| render

This retrieves the first 10000 documents data from the kibana_sample_data_ecommerce index sorted by order_date in ascending order, and only requests the customer_gender, taxful_total_price, and order_date fields.

Accepts: filter

Returns: datatable

Queries Elasticsearch using Elasticsearch SQL.

Expression syntax

essql query="SELECT * FROM "logstash*""
essql "SELECT * FROM "apm*"" count=10000

Code example

kibana
| selectFilter
| essql query="SELECT Carrier, FlightDelayMin, AvgTicketPrice FROM   "kibana_sample_data_flights""
| table
| render

This retrieves the Carrier, FlightDelayMin, and AvgTicketPrice fields from the "kibana_sample_data_flights" index.

Accepts: kibana_context, null

Returns: datatable

Creates a filter that matches a given column to an exact value.

Expression syntax

exactly "state" value="running"
exactly "age" value=50 filterGroup="group2"
exactly column="project" value="beats"

Accepts: filter

Returns: filter

Filters rows in a datatable based on the return value of a sub-expression.

Expression syntax

filterrows {getCell "project" | eq "kibana"}
filterrows fn={getCell "age" | gt 50}

Code example

kibana
| selectFilter
| demodata
| filterrows {getCell "country" | any {eq "IN"} {eq "US"} {eq "CN"}}
| mapColumn "@timestamp"
  fn={getCell "@timestamp" | rounddate "YYYY-MM"}
| alterColumn "@timestamp" type="date"
| pointseries x="@timestamp" y="mean(cost)" color="country"
| plot defaultStyle={seriesStyle points="2" lines="1"}
  palette={palette "#01A4A4" "#CC6666" "#D0D102" "#616161" "#00A1CB" "#32742C" "#F18D05" "#113F8C" "#61AE24" "#D70060" gradient=false}
| render

This uses filterrows to only keep data from India (IN), the United States (US), and China (CN).

Accepts: datatable

Returns: datatable

Aggregates element filters from the workpad for use elsewhere, usually a data source. filters is deprecated and will be removed in a future release. Use kibana | selectFilter instead.

Expression syntax

filters
filters group="timefilter1"
filters group="timefilter2" group="dropdownfilter1" ungrouped=true

Code example

filters group=group2 ungrouped=true
| demodata
| pointseries x="project" y="size(cost)" color="project"
| plot defaultStyle={seriesStyle bars=0.75} legend=false
  font={
    font size=14
    family="'Open Sans', Helvetica, Arial, sans-serif"
    align="left"
    color="#FFFFFF"
    weight="lighter"
    underline=true
    italic=true
  }
| render

filters sets the existing filters as context and accepts a group parameter to opt into specific filter groups. Setting ungrouped to true opts out of using global filters.

Accepts: null

Returns: filter

Create a font style.

Expression syntax

font size=12
font family=Arial
font align=middle
font color=pink
font weight=lighter
font underline=true
font italic=false
font lHeight=32

Code example

kibana
| selectFilter
| demodata
| pointseries x="project" y="size(cost)" color="project"
| plot defaultStyle={seriesStyle bars=0.75} legend=false
  font={
    font size=14
    family="'Open Sans', Helvetica, Arial, sans-serif"
    align="left"
    color="#FFFFFF"
    weight="lighter"
    underline=true
    italic=true
  }
| render

Accepts: null

Returns: style

Formats an ISO8601 date string or a date in milliseconds since epoch using MomentJS. See https://momentjs.com/docs/#/displaying/.

Expression syntax

formatdate format="YYYY-MM-DD"
formatdate "MM/DD/YYYY"

Code example

kibana
| selectFilter
| demodata
| mapColumn "time" fn={getCell time | formatdate "MMM 'YY"}
| pointseries x="time" y="sum(price)" color="state"
| plot defaultStyle={seriesStyle points=5}
| render

This transforms the dates in the time field into strings that look like "Jan ‘19", "Feb ‘19", etc. using a MomentJS format.

Accepts: number, string

Returns: string

Formats a number into a formatted number string using the Numeral pattern.

Expression syntax

formatnumber format="$0,0.00"
formatnumber "0.0a"

Code example

kibana
| selectFilter
| demodata
| math "mean(percent_uptime)"
| progress shape="gauge"
  label={formatnumber "0%"}
  font={font size=24 family="'Open Sans', Helvetica, Arial, sans-serif" color="#000000" align="center"}
| render

The formatnumber subexpression receives the same context as the progress function, which is the output of the math function. It formats the value into a percentage.

Accepts: number

Returns: string

Fetches a single cell from a datatable.

Accepts: datatable

Returns: Depends on your input and arguments

Returns whether the context is greater than the argument.

Accepts: number, string

Returns: boolean

Returns whether the context is greater or equal to the argument.

Accepts: number, string

Returns: boolean

Retrieves the first N rows from the datatable. See also tail.

Accepts: datatable

Returns: datatable

Performs conditional logic.

Accepts: any

Returns: Depends on your input and arguments

Displays an image. Provide an image asset as a base64 data URL, or pass in a sub-expression.

Accepts: null

Returns: image

Concatenates values from rows in a datatable into a single string.

Accepts: datatable

Returns: string

Gets kibana global context

Accepts: kibana_context, null

Returns: kibana_context

Find your current location using the Geolocation API of the browser. Performance can vary, but is fairly accurate. See https://developer.mozilla.org/en-US/docs/Web/API/Navigator/geolocation. Don’t use location if you plan to generate PDFs as this function requires user input.

Accepts: null

Returns: datatable

Returns whether the context is less than the argument.

Accepts: number, string

Returns: boolean

Returns whether the context is less than or equal to the argument.

Accepts: number, string

Returns: boolean

Returns an object with the center coordinates and zoom level of the map.

Accepts: null

Returns: mapCenter

Adds a column calculated as the result of other columns. Changes are made only when you provide arguments.See also alterColumn and staticColumn.

Accepts: datatable

Returns: datatable

Adds an element that renders Markdown text.

Accepts: datatable, null

Returns: render

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

Returns: Depends on your input and arguments

Adds a column by evaluating TinyMath on each row. This function is optimized for math and performs better than using a math expression in mapColumn.

Accepts: datatable

Returns: datatable

Displays a number over a label.

Accepts: number, string, null

Returns: render

Returns whether the context is not equal to the argument.

Accepts: boolean, number, string, null

Returns: boolean

Creates a color palette.

Accepts: null

Returns: palette

Configures a pie chart element.

Accepts: pointseries

Returns: render

Configures a chart element.

Accepts: pointseries

Returns: render

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.

Accepts: datatable

Returns: datatable

Turn a datatable into a point series model. Currently we differentiate measure from dimensions by looking for a TinyMath expression. See canvas-tinymath-functions.md. If you enter a TinyMath expression in your argument, we treat 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

Returns: pointseries

Configures a progress element.

Accepts: number

Returns: render

Removes filters from context

Accepts: kibana_context

Returns: kibana_context

Renders the context as a specific element and sets element level options, such as background and border styling.

Accepts: render

Returns: render

Configures a repeating image element.

Accepts: number

Returns: render

Uses a regular expression to replace parts of a string.

Accepts: string

Returns: string

Configures an image reveal element.

Accepts: number

Returns: render

Uses a MomentJS formatting string to round milliseconds since epoch, and returns milliseconds since epoch.

Accepts: number

Returns: number

Returns the number of rows. Pairs with ply to get the count of unique column values, or combinations of unique column values.

Accepts: datatable

Returns: number

Selects filters from context

Accepts: kibana_context

Returns: kibana_context

Creates an object used for describing the properties of a series on a chart. Use seriesStyle inside of a charting function, like plot or pie.

Accepts: null

Returns: seriesStyle

Creates a shape.

Accepts: null

Returns: Depends on your input and arguments

Sorts a datatable by the specified column.

Accepts: datatable

Returns: datatable

Adds a column with the same static value in every row. See also alterColumn, mapColumn, and mathColumn

Accepts: datatable

Returns: datatable

Concatenates all of the arguments into a single string.

Accepts: null

Returns: string

Performs conditional logic with multiple conditions. See also case, which builds a case to pass to the switch function.

Accepts: any

Returns: Depends on your input and arguments

Configures a table element.

Accepts: datatable

Returns: render

Retrieves the last N rows from the end of a datatable. See also head.

Accepts: datatable

Returns: datatable

Creates a time filter for querying a source.

Accepts: filter

Returns: filter

Configures a time filter control element.

Accepts: null

Returns: render

Uses Timelion to extract one or more time series from many sources.

Accepts: filter

Returns: datatable

An object that represents a span of time.

Accepts: null

Returns: timerange

Explicitly casts the type of the context from one type to the specified type.

Accepts: any

Returns: Depends on your input and arguments

Returns a UI settings parameter value.

Accepts: any

Returns: Depends on your input and arguments

Retrieves a URL parameter to use in an expression. The urlparam 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

Returns: string

Updates the Kibana global context.

Accepts: any

Returns: Depends on your input and arguments

Updates the Kibana global context.

Accepts: any

Returns: Depends on your input and arguments