Dynamic options syntax selector 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 selector functions in DOS to specify which aspects of your data you want to reference for your visualization options configurations. See Dynamic options in Dashboard Studio to learn more about dynamic options.

Dynamic options syntax structure

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]"

Table visualization with dynamic coloring example

The example syntax and results for each of the described selectors will reference this table example that uses the dynamic options syntax (DOS) to color values within columns. The following image is an example of a table used to display the names of games, number of purchases for each game, and total revenue from each game.

Source code example

The following is a source code example of a table visualization using DOS to dynamically color the table's columns. Notice the different selector functions such as seriesByName(\"Revenue\") and seriesByIndex(0).

Select Expand to see the full source code example.

{
    "type": "splunk.table",
    "dataSources": {
        "primary": "ds_most_purchased_games_1"
    },
    "title": "Most Purchased Games",
    "options": {
        "count": 8,
        "columnFormat": {
            "Revenue": {
                "data": "> primary | seriesByName(\"Revenue\") | formatByType(RevenueColumnFormatEditorConfig)"
            },
            "Purchases": {
                "data": "> primary | seriesByName(\"Purchases\") | formatByType(PurchasesColumnFormatEditorConfig)",
                "rowColors": "> primary | seriesByName(\"Purchases\") | pick(PurchasesRowColorsEditorConfig)"
            },
            "Game": {
                "data": "> primary | seriesByName(\"Game\") | formatByType(GameColumnFormatEditorConfig)",
                "rowColors": "> primary | seriesByName(\"Purchases\") | rangeValue(PurchasesRowColorsEditorConfig)"
            }
        },
        "backgroundColor": "transparent",
        "tableFormat": {
            "rowBackgroundColors": "> primary | seriesByIndex(0) | pick(tableAltRowBackgroundColorsByBackgroundColor)",
            "headerBackgroundColor": "> backgroundColor | setColorChannel(tableHeaderBackgroundColorConfig)",
            "rowColors": "> rowBackgroundColors | maxContrast(tableRowColorMaxContrast)",
            "headerColor": "> headerBackgroundColor | maxContrast(tableRowColorMaxContrast)"
        }
    },
    "context": {
        "RevenueColumnFormatEditorConfig": {
            "number": {
                "thousandSeparated": true,
                "unitPosition": "before",
                "unit": "$",
                "precision": 2
            }
        },
        "PurchasesColumnFormatEditorConfig": {
            "number": {
                "thousandSeparated": false,
                "unitPosition": "after"
            }
        },
        "PurchasesRowColorsEditorConfig": [
            {
                "value": "#D41F1F",
                "to": 3100
            },
            {
                "value": "#D94E17",
                "from": 3100,
                "to": 3200
            },
            {
                "value": "#CBA700",
                "from": 3200,
                "to": 3400
            },
            {
                "value": "#669922",
                "from": 3400,
                "to": 3600
            },
            {
                "value": "#118832",
                "from": 3600
            }
        ]
    },
    "showProgressBar": false,
    "showLastUpdated": false
}

DataFrame selectors

A DataFrame is a two dimensional dataset, similar to a search result with multiple columns, where each column is a field in your DataFrame. You can use the DataFrame selector getField() to return the name of every column in the search result.

getField()

Select Expand to see a description, an example, and an example result for the DataFrame selector getField():

Description

Get the names of all DataSeries in the DataFrame. For example, you can use getField() to return the name of every column in the Most Purchased Games table example.

Example syntax

> primary | getField()

Example result

["Game", "Purchases", "Revenue"]

getType()

Select Expand to see a description, an example, and an example result for the DataFrame selector getType():

Description

Get the data type of each DataSeries in the DataFrame. For example, you can use getType() to return the data type of every column in the Most Purchased Games table example.

Example syntax

> primary | getType()

Example result

["string", "number", "number"]

max()

Select Expand to see a description, an example, and an example result for the DataFrame selector max():

Description

Get the global maximum value from all DataSeries in the DataFrame. For example, you can use max() to return the maximum value from table columns with a numerical data type, such as the Purchases and Revenue columns from the Most Purchased Games table example.

Example syntax

> primary | frameBySeriesNames("Purchases", "Revenue") | max()

Example result

134166

min()

Select Expand to see a description, an example, and an example result for the DataFrame selector min():

Description

Get the global minimum value from all DataSeries in the DataFrame. For example, you can use min() to return the minimum value from table columns with a numerical data type, such as the Purchases and Revenue columns from the Most Purchased Games table example.

Example syntax

> primary | frameBySeriesNames("Purchases", "Revenue") | min()

Example result

2998

frameBySeriesIndexes(<index1>, <index2>...)

Select Expand to see a description, an example, and an example result for the DataFrame selector frameBySeriesIndexes(<index1>, <index2>...):

Description

Filter a DataFrame by specifying the indexes of the DataSeries you would like to return. For example, you can use frameBySeriesIndexes(0,1) to return the first and second columns in the Most Purchased Games table example. You must specify at least one index.

Example syntax

> primary | frameBySeriesIndexes(0)

Example result

[["World of Cheese", "SIM Cubicle, ...]]

frameBySeriesIndexRange(<start>, <end>)

Select Expand to see a description, an example, and an example result for the DataFrame selector frameBySeriesIndexRange(<start>, <end>):

Description

Filter a DataFrame by specifying the index range (<start>, <end>) of the DataSeries you would like to return. <start> and <end> are series indexes. If no <end> index is specified, frameBySeriesIndexRange() will return the range of columns from the start till the end of the columns in a search result. For example, you can use frameBySeriesIndexRange(0) to return all columns in the Most Purchased Games table example. Or, you can use frameBySeriesIndexRange(0,7) to receive the first 7 columns in the Most Purchased Games table example. You must specify a starting index.

Example syntax

> primary | frameBySeriesIndexRange(0,2)

Example result

[["World of Cheese", "SIM Cubicle, ...],[3655, 3615...]]

frameBySeriesNames(...names)

Select Expand to see a description, an example, and an example result for the DataFrame selector frameBySeriesNames(...names):

Description

Filter a DataFrame by specifying the names of the DataSeries you would like to return. For example, you can use frameBySeriesNames("Game", "Purchases") to return only the columns named "Game" and "Purchases" from the Most Purchased Games table example. You must specify at least one series name.

Example syntax

> primary | frameBySeriesNames("Game", "Purchases")

Example result

[["World of Cheese", "SIM Cubicle, ...],[3655, 3615...]]

frameBySeriesNamesOrIndexes(...namesOrIndexes)

Select Expand to see a description, an example, and an example result for the DataFrame selector frameBySeriesNamesOrIndexes(...namesOrIndexes):

Description

Filter a DataFrame by specifying one or more names or indexes of a DataSeries you would like to return. For example, you can use frameBySeriesNames("Game", 1) to return the first and second columns' data in the Most Purchased Games table example. You must specify at least one name or index.

Example syntax

> primary | frameBySeriesNamesOrIndexes("Game", 1)

Example result

[["World of Cheese", "SIM Cubicle, ...],[3655, 3615...]]

frameBySeriesTypes(...types)

Select Expand to see a description, an example, and an example result for the DataFrame selector frameBySeriesTypes(...types):

Description

Filter a DataFrame by specifying one or more data types of DataSeries you would like to return. For example, you can use frameBySeriesTypes("string", "number") to return all string and number typed columns within the Most Purchased Games table example. You must specify at least one data type.

Example syntax

> primary | frameBySeriesTypes("number")

Example result

[[3655, 3615...],[91338, 72264...]]

frameWithoutSeriesNames(...names)

Select Expand to see a description, an example, and an example result for the DataFrame selector frameWithoutSeriesNames(...names):

Description

Filter a DataFrame by specifying the names of the DataSeries you would like to omit. For example, you can use frameWithoutSeriesNames(first_name, second_name) to omit values from the table columns first_name and second_name. You must specify at least one series name. The data columns of internal fields are automatically excluded from the result. Internal fields are metadata, such as _time, that Splunk Platform attaches to every search.

Example syntax

> primary | frameWithoutSeriesNames("Game")

Example result

[[3655, 3615...],[91338, 72264...]]

getRawValue()

Select Expand to see a description, an example, and an example result for the DataFrame selector getRawValue():

Description

Get all values in the DataFrame. For example, you can use getRawValue() to return all the values in the Most Purchased Games table example. getRawValue() excludes field names, such as column names.

Example syntax

> primary | getRawValue()

Example result

[["World of Cheese", "SIM Cubicle, ...],[3655, 3615...],[91338, 72264...]]

getValue()

Select Expand to see a description, an example, and an example result for the DataFrame selector getValue():

Description

Get all values and their types in the DataFrame. For example, you can use getValue() to return all the values and their types from the Most Purchased Games table example. getValue() excludes field names, such as column names.

Example syntax

> primary | getValue()

Example result

[[{ type: 'string',value: 'World of Cheese',...}] , [{ type: 'number',value: 3655,...}], [{ type: 'number',value: 91338}, ...]]

seriesByIndex(index)

Select Expand to see a description, an example, and an example result for the DataFrame selector seriesByIndex(index):

Description

Select a DataSeries by specifying the index of the series you want to return. For example, you can use seriesByIndex(0) to return the values in the first column of the Most Purchased Games table example.

Example syntax

> primary | seriesByIndex(0)

Example result

["World of Cheese", "SIM Cubicle, ...]

seriesByName(field)

Select Expand to see a description, an example, and an example result for the DataFrame selector seriesByName(field):

Description

Select a DataSeries by specifying the name of the DataSeries you would like to return. For example, you can use seriesByName(first_name) to return the column with the name "Purchases" in the Most Purchased Games table example.

Example syntax

> primary | seriesByName("Purchases")

Example result

[3655, 3615...]

seriesByPrioritizedTypes(...types)

Select Expand to see a description, an example, and an example result for the DataFrame selector seriesByPrioritizedTypes(...types):

Description

Select a DataSeries by specifying the prioritized types of the DataSeries you would like to return. The first DataSeries that matches the first type specified will be returned. If no DataSeries matches the first type specified, the first DataSeries that matches the second type will be returned, and so on. For example, you can use seriesByPrioritizedTypes("number", "string") and if there are no columns in the Most Purchased Games table example with number data types, then the first column with the string data type will be returned. seriesByPrioritizedTypes() accepts multiple types.

Example syntax

> primary | seriesByPrioritizedTypes("number", "string")

Example result

[3655, 3615...]

seriesByType(type)

Select Expand to see a description, an example, and an example result for the DataFrame selector seriesByType(type):

Description

Select a DataSeries by specifying the type of the DataSeries you would like to return. The first DataSeries that matches the first type specified will be returned. If no DataSeries matches the first type specified, no DataSeries will be returned. seriesByType() only accepts a single type. For example, you can use seriesByType(string) to return all the game names in the Most Purchased Games table example.

Example syntax

> primary | seriesByType("string")

Example result

["World of Cheese", "SIM Cubicle, ...]

seriesByTypes(...types)

Select Expand to see a description, an example, and an example result for the DataFrame selector seriesByTypes(...types):

Description

Select a DataSeries by specifying any type you would like to return. The first DataSeries that matches any of the types specified will be returned. If no DataSeries matches the type options specified, no DataSeries will be returned. For example, you can use seriesByTypes(string, array) and the first table column that has the data type string or array will be returned. After one table column is returned, no other table columns will be returned. For example, if a table column of strings is returned, a table column of arrays will not be returned.

Example syntax

> primary | seriesByTypes("number", "string")

Example result

["World of Cheese", "SIM Cubicle, ...]

setValue(v)

Select Expand to see a description, an example, and an example result for the DataFrame selector setValue(v):

Description

Set all values in the DataFrame to a static TypedValue. For example, you can use setValue(23) and all values in an entire table will be 23.

Example syntax

> primary | setValue(55)

Example result

No return value. Sets the table to [[55, 55, ...],[55, 55, ...],[55, 55, ...]]

DataSeries selectors

A DataSeries is a one dimensional dataset, such as a search result with a single column. That single column is the only field of the one dimensional dataset. You can use the DataSeries selector getField() to return the name of the single column in the search result.

getField()

Select Expand to see a description, an example, and an example result for the DataSeries selector getField():

Description

Returns the data source field which the series belongs to.

Example syntax

> primary | seriesByIndexes(0) | getField()

Example result

"Game"

getType()

Select Expand to see a description, an example, and an example result for the DataSeries selector getType():

Description

Returns the inferred data type of the series.

Example syntax

> primary | seriesByIndexes(0) | getType()

Example result

"string"

max()

Select Expand to see a description, an example, and an example result for the DataSeries selector max():

Description

Returns the maximum DataPoint in the series.

Example syntax

> primary | seriesByName("Purchases") | max()

Example result

3655

min()

Select Expand to see a description, an example, and an example result for the DataSeries selector min():

Description

Returns the minimum DataPoint in the series or undefined if no numbers in series.

Example syntax

> primary | seriesByName("Purchases") | min()

Example result

2998

delta(index)

Select Expand to see a description, an example, and an example result for the DataSeries selector delta(index):

Description

Finds the delta between the last point and point at the given index. A negative index can be used, indicating an offset from the end of the sequence.

Example syntax

> primary | seriesByName("Purchases") | delta(6)

Example result

-64

firstPoint()

Select Expand to see a description, an example, and an example result for the DataSeries selector firstPoint():

Description

Return first dataPoint in series.

Example syntax

> primary | seriesByName("Purchases") | firstPoint()

Example result

3655

lastPoint()

Select Expand to see a description, an example, and an example result for the DataSeries selector lastPoint():

Description

Return last dataPoint in series.

Example syntax

> primary | seriesByName("Purchases") | lastPoint()

Example result

2998

pointByIndex(index)

Select Expand to see a description, an example, and an example result for the DataSeries selector pointByIndex(index):

Description

Finds and returns the individual dataPoint at the given index.

Example syntax

> primary |  seriesByName("Purchases") | pointByIndex(1)

Example result

3615

pointsByIndexes(...indexes)

Select Expand to see a description, an example, and an example result for the DataSeries selector pointsByIndexes(...indexes):

Description

Finds dataPoint(s) in DataSeries by index(es).

Example syntax

> primary | seriesByName("Purchases") | pointsByIndexes(0,3,5)

Example result

[3655, 3355, 3148]

DataPoint selectors

A DataPoint is a single value within a dataset, such as a cell within a table chart.

getField()

Select Expand to see a description, an example, and an example result for the DataPoint selector getField():

Description

Returns the data source field which the point belongs to.

Example syntax

> primary | seriesByName("Purchases") | firstPoint() | getField()

Example result

"Purchases"

getType()

Select Expand to see a description, an example, and an example result for the DataPoint selector getType():

Description

Returns the inferred data type of the point.

Example syntax

> primary | seriesByName("Purchases") | firstPoint() | getType()

Example result

"number"

getValue()

Select Expand to see a description, an example, and an example result for the DataPoint selector getType():

Description

Returns the value and type of the point.

Example syntax

> primary | seriesByName("Revenue") | firstPoint() | getValue()

Example result

{type: 'number', value: 91338}

getRawValue()

Select Expand to see a description, an example, and an example result for the DataPoint selector getType():

Description

Returns the value and type of the point.

Example syntax

> primary | seriesByName("Revenue") | firstPoint() | getRawValue()

Example result

91338

setValue()

Select Expand to see a description, an example, and an example result for the DataPoint selector getType():

Description

Sets the value of a data point.

Example syntax

> primary | seriesByName("Revenue") | firstPoint() | setValue(25)

Example result

No return value. Sets the first data point of the Revenue column to 25.