Using tokens in an EQL query

The EQL queries for a Custom Visualization Component support token replacement in the EQL query. Tokens are simply variables in an EQL query that correspond to user-interface controls in the Visualization Settings panel the component. Controls include attributes (metrics or dimensions), views, data views and sorts. For example, a sort token in an EQL query creates an ASC or DSC sort control in the component configuration for a project user to select. A dimension token creates a drop down menu of attributes for a project user to select.

In EQL query, tokens are strings enclosed by percentage signs (%), for example, %metric_1%. Here is an example EQL statement that contains five tokens (%metric_1%, %groupby_1%, %dataview%, %sort%, %num_recs%):

RETURN data AS SELECT
%metric_1% AS metric,
%groupby_1% AS groupby
FROM "%dataview%"
GROUP BY groupby
ORDER BY metric %sort%
PAGE(0,%num_recs%);

Studio replaces the tokens with a value based on the user configuration in the Visualization Settings panel the component. That value is used when Studio runs the query to generate results for the component.

Token types

Tokens are distinguished by the type of data the token represents and by how the component acquires the token's value. The following table shows each token type and explains how Studio replaces the token with a value before running the EQL query.

Token type	Value	Example replacement value
Attribute (metric or dimension sub-types)	Attribute tokens represent either a metric or a dimension. A metric token represents menus of metric and aggregation functions. During component configuration, you select a data type for the metric token to determine which attributes are available for a project user to select. Similarly, during component configuration, you also select aggregation functions (e.g. SUM) to determine which attributes are available for a project user to select. A metric token is replaced when a project user selects an attribute and aggregation function from the Visualization Settings panel of the component. A dimension token represents a drop-down menu of attributes for a project user to select. During component configuration, you select a data type for the dimension token to determine which attributes are available for a project user to select. For example, if you select data type of string, only string attributes are available for selection. A dimension token is replaced when a user selects an attribute from the Visualization Settings panel of the component. Both types of metric and dimension tokens are associated with a View token that dictates which data view the attributes are taken from to populate the user-interface menus. Attribute token values may also be set with the JavaScript API.	SUM(p_price)
View	A view token represents a drop-down menu of data views for a project user to select. The token is replaced when a user selects a data view from the Visualization Settings panel of the component. View token values may also be set with the JavaScript API.	p_price
Sort	A sort token represents an ASC or DESC sort control in the component configuration for a project user to select. The token is replaced when a user selects a sort direction (ASC or DESC) from the Visualization Settings panel of the component. ASC is the default value. Sort token values may also be set with the JavaScript API.	ASC
Data	Data token values must be set with the JavaScript API.

For additional details about tokens, see the Custom Visualization Component JavaScript API Reference.

Token substitution example

Here is an example EQL query with tokens:

RETURN data AS SELECT
%metric_1% AS metric,
%groupby_1% AS groupby
FROM "%dataview%"
GROUP BY groupby
ORDER BY metric %sort%
PAGE(0,%num_recs%);

Here is the same EQL query with values substituted for the tokens:

RETURN data AS SELECT
SUM(p_price) AS metric,
p_color AS groupby
FROM "wine_dataset"
GROUP BY groupby
ORDER BY metric ASC
PAGE(0,20);