User Parameters (Variables)

Parameters allow for user-input without the user requiring the ability to modify or alter the queries and dashboards. Parameters can be created using a question mark prefix, support default values for automated contexts like triggers and scheduled searches, and offer special syntax for handling multi-value inputs in dashboard implementations.

User-configurable parameters can be added to a query to allow for the user to specify a value in place of a fixed value within the query. The user-configurable value can also be integrated with dashboards and saved searches.

To create a user-supplied parameter, use the ? character in front of the parameter name within the query. For example: ?parameter. The expression can be embedded in the query and will be interpreted by dashboards and saved searches automatically, providing a prompt for user-input:

logscale
matchstring := ?searchtext

In the above example, the named parameter will be searchtext.

The parameter will automatically be identified and extracted when the query is used as part of a dashboard.

More complex parameters can be quoted:

logscale
matchstring := ?"Matching String to Locate"

The parameter name will be used as the title of the parameter within the dashboard, using a quoted value allows for more descriptive parameter values.

For information on using parameters when using Dashboards, see Work with Dashboard Parameters.

For information on using parameters with saved searches, see Saved Searches (User Functions).

Using Common Parameters

When building a dashboard with multiple widgets and different queries, the parameters defined in each query will be extracted and then used to build all of the parameters for the dashboard.

To use the same parameter across multiple queries, use the same parameter definition in each query. For example, the following queries for different widgets on a single dashboard:

  • Detections

    logscale
    metadata.eventType=DetectionSummaryEvent 
| event.ComputerName=?ComputerName  AND metadata.customerIDString = ?cid

  • Computer List

    logscale
    metadata.eventType = DetectionSummaryEvent 
| event.ComputerName=?ComputerName

Would create two unique parameters in the dashboard that the user could use, and the same value for each parameter would be applied to both queries. This enables you to use common parameters across all the queries in a dashboard.

Default Parameter Values

For queries that execute in a automated context, for example Alerts or Scheduled Searches, a default value to a parameter can be defined to ensure that the parameter has a value and the query does not fail.

To specify a default value, use the following syntax in your query: 

?{PARAMETER=VALUE

Where:

  • PARAMETER

    The name of the parameter. Parameter names can be quoted to include spaces or non-alphanumeric characters.

  • VALUE

    The default value to be applied.

For example, this creates the parameter param with the default value default_value.

logscale
?{param=default_value}

Important

Default values are only supported for saved searches. Within the user interface or dashboards, the glob * value is used by default. Any default value configured in the parameter is ignored.

Using Parameters in Saved Searches

Saved searches can make use of user-defined parameters to enable values to be supplied to saved searches at the time of execution. For example, to create a saved search that executes a groupBy(), create a saved search called grouped():

logscale
groupBy(field=?{basefield="@host"})

This exposes the parameter basefield in the grouped() saved search, which can then be called using:

logscale
$grouped(basefield="@host")

Multi-Value Parameters Syntax for Dashboards

When using Multi-value Parameters in dashboards, multiple values can be added at the same time by using commas as a delimiter for user-inputs in the UI. To add multi-value parameters to your query for a dashboard, use the syntax as in the following examples:

User Input Parameter Value Options
cat, hat cat and hat
"cat, hat" cat, hat
\"cat, hat\" "cat and hat"
\"cat\", \"hat\" "cat" and "hat"