Splunk Cloud Platform

Splunk Dashboard Studio

Dynamic options syntax formatting functions

Dynamic options syntax (DOS) is the programming syntax used in Dashboard Studio for visualization options and dynamic menu options for inputs. You can use formatting functions in DOS to transform and map the data into a desired format. See Dynamic options in Dashboard Studio to learn more about dynamic options.

Dynamic options syntax structure

Dynamic Options Syntax (DOS) structure has several parts, each separated by a pipe ( | ).

DOS Part What it does Required?
Data Source An originating data source, which can be a visualization data source such as a primary data source or visualization options such as sparklineValues. The location of your data sources, searches, and options for each search you create in the visual editor. Yes
Selector functions Identifies the data from the data source associated with the visualization. A dynamic option can have one or multiple selector functions. No
Formatting function Formats the selected data. Optional unless additional data formatting is needed.

A typical DOS structure looks like the following:

Option: "> [data source] | [selector functions] | [formatting function]"

Formatting functions

You can use formatting functions to configure your selected data.

formatByType()

Select Expand to see a description, an example, and an example result for the formatting function formatByType():

Description

You can use the formatByType() function to compose a value based on the provided configuration and that value's type, such as a number or string.

Example code syntax

The following code example uses formatByType() to add a $ symbol to the beginning of all values in the Revenue column. Additionally, formatByType() applies a precision of 2 to each number value, determining the number of digits displayed after a decimal point.

{
   "type": "splunk.table",
   "dataSources": {
       "primary": "ds_most_purchased_games_1"
   },
   "title": "Most Purchased Games",
   "options": {      
       "columnFormat": {
           "Revenue": {
               "data": "> table | seriesByName(\"Revenue\") | formatByType(RevenueColumnFormatEditorConfig)"
           }
       }
   },
   "context": {
       "RevenueColumnFormatEditorConfig": {
           "number": {
               "thousandSeparated": true,
               "unitPosition": "before",
               "unit": "$",
               "precision": 2
           }
       }
   }
}

Example result

The following table shows the result of using formatByType() to add a $ symbol to all values in the Revenue column. A table with three columns, Game, Purchases, and Revenue. All the number values in the Revenue column start with a dollar symbol.

frame()

Select Expand to see a description, an example, and an example result for the formatting function frame():

Description

The frame() function can combine arguments into a new DataFrame. For more details about DataFrame, DataSeries, and DataPoint selectors, see Dynamic options syntax selector functions.

Example code syntax

The following code example uses frame() to combine the data in the Game and Revenue columns and use the result as a data source for the table.

{
   "type": "splunk.table",
   "dataSources": {
       "primary": "ds_most_purchased_games_1"
   },
   "title": "Most Purchased Games",
   "options": {    
       "table" : "> frame(Game, Revenue)"
   },
   "context": {
       "Game": "> primary | seriesByName(\"Game\")",
       "Revenue": "> primary | seriesByName(\"Revenue\")"      
   }
}

Example result

The following table shows the result of using frame() to combine the data in the Game and Revenue columns and use the result as a data source for the table.

A table has two columns. The column titled Games has the name of the games, and the column titled Revenue shows the profit each game made.

gradient()

Select Expand to see a description, an example, and an example result for the formatting function gradient():

Description

You can use the gradient() function to map values to a color. Define your values as stops and your colors as colors. If no config is specified, the default colors are ['rgba(123,86,219,0.4)', 'rgba(123,86,219,1)']. The default stops are dependent on the DataSeries provided.

If a DataSeries has n values, you can configure the stops between a minimum and maximum. The minimum and maximum map to rgba(123,86,219,0.4) and rgba(123,86,219,1), respectively.

For more details about DataFrame, DataSeries, and DataPoint selectors, see Dynamic options syntax selector functions.

Example code syntax

The following code example uses gradient() to create a color gradient scheme for a column with number values.

{   
  "type": "splunk.table",
     "dataSources": {
         "primary": "ds_most_purchased_games_1"
   },
   "title": "Most Purchased Games",
   "options": {
       "columnFormat": {
           "Revenue": {
               "rowBackgroundColors": "> table | seriesByName(\"Revenue\") | gradient(gradientConfig)"
           }
       }
   },
   "context": {
       "gradientConfig":{     
           "stops": [
               0,
               50000,
               100000
           ],      
            "colors": [
               "red",
               "yellow",
               "green"
           ]
       }
   }
}

Example result

The following table shows the result of using gradient() to color the profits in the Revenue column, ranging from the lowest revenue in red to the highest revenue in dark green.

A table with three columns, Game, Purchases, and Revenue. All the number values in the Revenue column are colored in a gradient scale showing a range from the lowest revenue in red to the highest revenue in dark green.

matchValue()

Select Expand to see a description, an example, and an example result for the formatting function matchValue():

Description

You can use the matchValue() function to map potential matches to corresponding default values. For example, you can match the number 234 to the color green. Each time 234 appears on a table, its font is green.

Example code syntax

The following code example uses matchValue() to add color to values depending on whether the value matches true, false, or some other known value.

{
   "type": "splunk.table",
   "dataSources": {
       "primary": "ds_most_purchased_games_1"
   },
   "title": "Most Purchased Games",
   "options": {
       "columnFormat": {
           "Game": {
               "rowBackgroundColors": "> table | seriesByName(\"Game\") | matchValue(matchConfig)"
           }
       }
   },
   "context": {
       "matchConfig": [
         {
               "match": "SIM Cubicle",
               "value": "#FF0000"
           },
           {
               "match": "Dream Crusher",
               "value": "#00FF00"
           }  
       ]
   }
}

Example result

The following table shows the result of using matchValue() to add color to SIM Cubicle and Dream Crusher.

A table with three columns, Game, Purchases, and Revenue. The value SIM Cubicle is colored red, and the value Dream Crusher is colored green.

multiFormat()

Select Expand to see a description, an example, and an example result for the formatting function multiFormat():

Description

You can use the multiFormat() function to format multiple fields. The formatting function accepts a config object containing a map of field specific formatters which is used to evaluate each fields' corresponding values. The following three fields are required:

  • nameField designates the list of keys with custom formatters to be applied against
  • valueField designates the field to derive the values from
  • formatter1 is an object that requires the configuration required for the specified formatter and the name of the formatter, such as "rangeValue" or "matchValue"

Example code syntax

The following code example uses multiFormat() to format multiple columns depending on the column's name.

{
    "type": "splunk.choropleth.svg",
    "options": {
        "svg": "https://splunkudftest.s3-us-west-1.amazonaws.com/campus.svg",
        "areaIds": "> primary | seriesByIndex(0)",
        "areaValues": "> primary | seriesByIndex(1)",
        "areaColors": "> primary | multiFormat(areaColorsConfig)"
    },
    "dataSources": {
        "primary": {
            "requestParams": {
                "offset": 0,
                "count": 20
            },
            "data": {
                "fields": [
                    {
                        "name": "buildings"
                    },
                    {
                        "name": "values"
                    }
                ],
                "columns": [
                    [
                        "ATX-270-B",
                        "N-224",
                        "VM-203",
                        "RF-380"
                    ],
                    [
                        "10000",
                        "55000",
                        "90000",
                        "75000"
                    ]
                ]
            },
            "meta": {
                "totalCount": 100
            }
        }
    },
    "context": {
        "areaColorsConfig": {
            "nameField": "buildings",
            "valueField": "values",
            "formatters": {
                "ATX-270-B": {
                    "type": "matchValue",
                    "config": [
                        {
                            "match": 10000,
                            "value": "#00FF00"
                        },
                        {
                            "match": 20000,
                            "value": "#FF0000"
                        }
                    ]
                },
                "N-224": {
                    "type": "gradient",
                    "config": {
                        "colors": [
                            "#FF7152",
                            "#FFEBA8"
                        ]
                    }
                },
                "VM-203": {
                    "type": "rangeValue",
                    "config": [
                        {
                            "from": 80000,
                            "value": "#4B4BFF"
                        },
                        {
                            "to": 20000,
                            "value": "#FF0000"
                        }
                    ]
                },
                "RF-380": {
                    "type": "rangeValue",
                    "config": [
                        {
                            "from": 80000,
                            "value": "#4BEBA8"
                        },
                        {
                            "from": 60000,
                            "to": 80000,
                            "value": "#F4DF7A"
                        },
                        {
                            "from": 20000,
                            "to": 60000,
                            "value": "#FC9850"
                        },
                        {
                            "to": 20000,
                            "value": "#FF0000"
                        }
                    ]
                }
            }
        }
    }
}

Example result

The following image shows the result of using multiFormat() to color different buildings within a map based on the number of network connections in that building.

A map of different buildings with several buildings colored based on the number of network connections within them. Building ATX-270-B is colored green, which indicates it has 100,000 or more network connections. Building N-224 is colored yellow, indicating around 50,000 network connections.

objects()

Select Expand to see a description, an example, and an example result for the formatting function objects():

Description

You can use the objects() function to convert a DataPrimitive into an array of objects. A DataPrimitive is either a DataFrame, DataSeries, or DataPoint. For more details about DataFrame, DataSeries, and DataPoint selectors, see Dynamic options syntax selector functions.

Example code syntax

The following code example uses objects() to define custom static options.

{
   "context": {
       "staticOptions": [
           [
               "All Users"
           ],
           [
               "*"
           ]
       ],
       "field1": "> primary | seriesByName(\"users\") | renameSeries(\"label\")",
       "field2": "> primary | seriesByName(\"ids\") | renameSeries(\"value\")"
   },
   "options": {
       "items": "> frame(field1, field2) | prepend(staticOptions) | objects()"
   },
   "dataSources": {
       "primary": "ds_search1"
   },
   "title": "Multiselect Input Title",
   "type": "input.multiselect"
}

Example result

The following image shows the result of using objects() to populate a multiselect input with the names of users.

A dropdown list showing the names of different users that can be selected as values for an input.

pick()

Select Expand to see a description, an example, and an example result for the formatting function pick():

Description

You can pass a map or array config through the pick() function.

If a map is provided, it will use the DataPoint's field name to pick the corresponding entry in the config.

For example, if the config contains 2 elements and the DataSeries includes 10 elements, pick() loops through the config 5 times, alternating between which element is appended to the output. For more details about DataFrame, DataSeries, and DataPoint selectors, see Dynamic options syntax selector functions.

Example code syntax for providing an array

The following code example uses pick() to color odd rows with red text and even rows with blue text.

{
   "type": "splunk.table",
   "dataSources": {
       "primary": "ds_most_purchased_games_1"
   },
   "title": "Most Purchased Games",
   "options": {
       "tableFormat": {
           "rowColors": "> table | pick(rowTextColor)"
       }
   },
   "context": {
       "rowTextColor": ["#FF0000", "#0000FF"]
   }
}

Example result for providing an array

The following table shows the result of using pick() to rotate between the colors red and blue and apply color for each row of the table.

A table with three columns, Game, Purchases, and Revenue. The rows of the table rotate between the colors red and blue. The first row is red, the second row is blue, and so on.

Example code syntax for providing a map

The following code example uses pick() to align the columns "Game", "Purchases" and "Revenue" to "left", "center" and "right" using a map config.

{
   "type": "splunk.table",
   "dataSources": {
       "primary": "ds_most_purchased_games_1"
   },
   "title": "Most Purchased Games",
   "options": {
       "tableFormat": {
           "align": "> table | pick(mapConfig)"
       }      
   },
   "context": {
       "mapConfig": {
           "Game": "left",
           "Purchases": "center",
           "Revenue": "right"
       }
   }
}

Example result for providing a map

The following table shows the result of using pick() to align the values of the columns "Game", "Purchases", and "Revenue" to "left", "center", and "right".

A table with three columns, Game, Purchases, and Revenue. The Game column is aligned left, the Purchases column values are aligned in the center, and the Revenue column values are aligned right.

prefix()

Select Expand to see a description, an example, and an example result for the formatting function prefix():

Description

You can use the prefix() function to add a given prefix to the beginning of the DataPoint. For example, you can return the string "bar100" if the number 100 is your DataPoint, and you pass "bar" as a parameter to prefix(). For more details about DataFrame, DataSeries, and DataPoint selectors, see Dynamic options syntax selector functions.

Example code syntax

The following code example uses prefix() to add the text "Label -" to the beginning of all data values in column "Game".

{
    "type": "splunk.table",
    "dataSources": {
        "primary": "ds_most_purchased_games_1"
    },
    "title": "Most Purchased Games",
    "options": {
        "columnFormat": {
            "Game": {
                "data": "> table | seriesByName(\"Game\") | prefix(\"Label - \")"
            }
        }
    }
}

Example result

The following image shows the result of using the prefix() function to add "Label -" to the beginning of each value in the Game column.

A table with three columns, Game, Purchases, and Revenue. All the values in the Game column start with the string "Label -".

prepend()

Select Expand to see a description, an example, and an example result for the formatting function prepend():

Description

You can use the prepend() function to add a DataFrame, DataSeries, or DataPoint to the beginning of an existing DataFrame or DataSeries with compatible types.

If prepending a DataFrame to another DataFrame, the DataFrames must have the same number of DataSeries. For example, a DataFrame with 3 series, such as [[1, 2], [3, 4], [5, 6]], cannot be prepended to a DataFrame with 2 series, such as [[7, 8], [9, 10]].

A DataPrimitive is either a DataFrame, DataSeries, or DataPoint. Only the same DataPrimitive type or a DataPrimitive's composite DataPrimitives can be prepended to the pre-existing DataPrimitive. A composite DataPrimitive is any DataPrimitive that makes another, such as multiple DataPoints making a DataSeries, or multiple DataSeries making a DataFrame.

For more details about DataFrame, DataSeries, and DataPoint selectors, see Dynamic options syntax selector functions.

Example code syntax

The following code example uses prepend() to add a dataFrame named "prependGames" to the "primary" dataFrame.

{
   "type": "splunk.table",
   "dataSources": {
       "primary": "ds_most_purchased_games_1"
   },
   "title": "Most Purchased Games",
   "options": {
       "table" : "> primary | prepend(prependGames)"
   },
   "context": {
       "prependGames" : [["foo", "bar"], [100, 200], [1000, 2000]]
   }
}

Example result

The following image shows the result of using prepend() to add the games "foo" and "bar" to the top of the table.

A table with three columns, Game, Purchases, and Revenue. The first two games are called "foo" and "bar" to indicate a difference from the other game names such as, "Fire resistance suit of provolone" and "World of Cheese".

rangeValue()

Select Expand to see a description, an example, and an example result for the formatting function rangeValue():

Description

You can use the rangeValue()) function to return a specific value from a range of different values. The rangeValue() function takes a list of ranges and a default value. If no range is available, the function returns the default value. If neither range or default value is present, the function returns the original value. For example, you can have a range of colors that correlate to different numbers. You can then use rangeValue() to take a separate value, find that value within the range of colors, and return the correlating color of that value.

A fitting describes how an input data value is mapped to a given set of ranges to derive the formatter function output. The range fitting follows this criteria: range.from is less than or equal to value which is less than range.to.

The following are different ways you can define a range:

  • Closed bound range
    { 
      "value": "#CBA700",
      "from": 50000,
      "to": 100000
     }
    
  • Open lower bound range
    {
      "value": "#D41F1F",
      "to": 25000
    }
    
  • Open upper bound range
    {
      "value": "#118832",
      "from": 100000
    }
    

Example code syntax

The following code example uses rangeValue() to apply a color range to numerical values in a column.

{
   "type": "splunk.table",
   "dataSources": {
       "primary": "ds_most_purchased_games_1"
   },
   "title": "Most Purchased Games",
   "options": {
       "columnFormat": {
           "Revenue": {             
               "rowColors": "> table | seriesByName(\"Revenue\") | rangeValue(RevenueRowColorsEditorConfig, \"purple\")"
           }
       }
   },
   "context": {      
       "RevenueRowColorsEditorConfig": [
           {
               "value": "#D41F1F",
               "to": 25000
           },
           {
               "value": "#CBA700",
               "from": 50000,
               "to": 100000
           },
           {
               "value": "#118832",
               "from": 100000
           }
       ]
   }
  }

Example result

The following image shows the result of using rangeValue() to apply a color range to the values in the Revenue column.

A table with three columns, Game, Purchases, and Revenue. All the number values in the Revenue column are colored either red, purple, yellow, or green.

type()

Select Expand to see a description, an example, and an example result for the formatting function type():

Description

You can use the type() function to return the data type for each element within a given DataSeries. For more details about DataFrame, DataSeries, and DataPoint selectors, see Dynamic options syntax selector functions.

Example code syntax

The following code example uses type() to display the type of each data point in the table.

{
   "type": "splunk.table",
   "dataSources": {
       "primary": "ds_most_purchased_games_1"
   },
   "title": "Most Purchased Games",
   "options": {
       "table": "> primary | type()"       
   }
 }

Example result

The following image shows the result of using type() to display the type of each data point in each column.

A table with three columns, Game, Purchases, and Revenue. All the values in the Game column display the word "string". All the values in the Purchases and Revenue column display the word "number".

maxContrast()

Select Expand to see a description, an example, and an example result for the formatting function maxContrast():

Description

You can use the maxContrast() function to pick the color assigned with the maximum contrast. maxContrast() leverages Chromajs.contrast to determine the contrast between color and values. For details, see "Chroma.js" on the GitHub pages website.

Example code syntax

The following code example uses maxContrast() to color each row's text with a contrast color based on the background's color. For example, if the background is white, the text color is red. If the background is black, then the text color is gray.

{
   "type": "splunk.table",
   "dataSources": {
       "primary": "ds_most_purchased_games_1"
   },
   "title": "Most Purchased Games",
   "options": {
       "tableFormat" : {
           "rowColors" : "> primary | pick(rowTextColors) | maxContrast(contrastConfig)"
       }
   },
   "context": {
       "contrastConfig" : {
           "colors" : ["red", "gray"]            
       },
       "rowTextColors": ["white", "black"]       


   }
}

Example result

The following image shows the result of using maxContrast() to color each row's text to contrast against the row's background color.

A table with three columns, Game, Purchases, and Revenue. Each row of the table alternates between a white or black background. Rows with a white background have red text, and rows with a black background have gray text.

setColorChannel()

Select Expand to see a description, an example, and an example result for the formatting function setColorChannel():

Description

You can use the setColorChannel() function to modify a given color's chromaticity. Chromaticity is a property that characterizes the quality of a color. setColorChannel() leverages Chromajs.contrast to determine the contrast between color and values. For details, see "Chroma.js" on the GitHub pages website.

Example code syntax

The following code example uses setColorChannel() to set chromaticity to 30 for the colors "skyblue" and "hotpink".

{
   "type": "splunk.table",
   "dataSources": {
       "primary": "ds_most_purchased_games_1"
   },
   "title": "Most Purchased Games",
   "options": {
       "tableFormat": {
           "rowBackgroundColors": "> primary | pick(rowColors) | setColorChannel(rowBGConfig)"           
       }
   },
   "context": {
       "rowBGConfig": {
            "channel": "lch.c",
            "value": "30"
        },
        "rowColors" : ["skyblue", "hotpink"]
   }
}

Example result

The following image shows the result of using setColorChannel() to set the chromaticity of the table's "skyblue" and "hotpink" colored rows. A chromaticity of 30 slightly mutes the colors "skyblue" and "hotpink".

A table with three columns, Game, Purchases, and Revenue. The rows of the table alternate between a muted blue and pink.

Last modified on 12 December, 2023
Dynamic options syntax selector functions   Default configuration options

This documentation applies to the following versions of Splunk Cloud Platform: 9.2.2406, 9.0.2305, 9.1.2308, 9.1.2312, 9.2.2403 (latest FedRAMP release)


Was this topic useful?







You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters