saql Step Type PropertiesUse the saql step type for special cases when querying a Analytics dataset. With this step type, you can write a custom SAQL query to create derived fields in a values table. You can specify dimensions without groupings. Also, you can bind the dataset name or entire query. For example, you can bind this step type to a static step that provides different SAQL queries or datasets based on a selection.
| Field Name | Description |
|---|---|
type | Step type. Set to saql. |
label | Step label, which is primarily used for display in the dashboard designer user interface. |
query | The SAQL query used to retrieve results. For more information about SAQL queries, see Analytics SAQL Developer Guide. When you create a saql-type step, by default, no limit is set in the query. When a limit isn’t set, a step can return up to 10,000 results. To return more results, set the limit attribute accordingly. The higher you increase the limit, the longer the query takes. Limit only impacts the number of records returned for display. The limit doesn’t impact calculations across all records in the dataset. For instance, a query groups by Account Name and there are one million Account Names in a dataset. When the limit is 20, Analytics returns 20 records for display. But the summary row provides a total for the one million records. You can bind a saql step type to dynamically set the dataset used in the query or change the entire query based on a selection in another step. For example, you can create a toggle based on a static step that allows the dashboard viewer to select a query. Each toggle option contains a valid SAQL query. Each query can be based on different datasets. (See the JSON example at the end of this section.) |
broadcastFacet | Controls whether the step’s selections are broadcasted as facets. Faceting is when a selection in a widget filters other steps in the dashboard. Default is true. |
receiveFacetSource | Controls whether the step in the receiving query listens for broadcasted facets and applies them as filters. The mode can be “all”, “none”, “include”, or “exclude”. Use steps to list which steps to include or exclude. Default is all. |
useGlobal | Indicates whether to apply global filters to this step (true) or not (false). If the step is in SAQL form, you must also set autoFilter to true to apply the global filters. By default, the global filter widget filters compact-form steps only. |
selectMode | Determines the selection interaction. The options for charts are: none, single, and singlerequired. The options for list, range, and toggle selectors are: single, singlerequired, multi, and multirequired. selectMode doesn’t apply to number, values table, compare table, date, and global filter widgets. |
start | The initial selections that are applied to the step when the dashboard first opens. A widget with a saql-type step can return up to 10,000 results, by default. If Analytics doesn’t find the initial value in those results, it ignores this setting. |
strings | Flags the specified fields as non-grouping dimensions. For example, you can flag a field as a dimension for a values table in which no groupings are allowed. If you use a binding to determine the field, specify the binding here as well. |
numbers | Flags the specified fields as measures. If you use a binding to determine the field, specify the binding here as well. |
groups | Flags the specified fields as groupings. For example, you can flag a field as a grouping for a pivot table or chart. If you use a binding to determine the field, specify the binding here as well. |
Single-selection example start:
1"start": [ "06 - Proposal/Price Quote" ]Multi-selection example start:
1"start": [
2 "06 - Proposal/Price Quote",
3 "01 - Prospecting"
4]1"steps": {
2 "Amount_1": {
3 "type": "saql",
4 "query": "q = load \"DTC_Opportunity_SAMPLE\";\nq = group q by 'Account_Name';\nq = foreach q generate 'Account_Name' as 'Account_Name', count() as 'count';\nq = order q by 'Account_Name' desc;\nq = limit q 1000;",
5 "useGlobal": true,
6 "numbers": [],
7 "groups": [],
8 "strings": [],
9 "visualizationParameters": {
10 "type": "chart",
11 "parameters": {
12 "visualizationType": "hbar",
13 "autoFitMode": "keepLabels",
14 "theme": "wave",
15 "title": {
16 "label": "",
17 "fontSize": 14,
18 "subtitleLabel": "",
19 "subtitleFontSize": 11,
20 "align": "center"
21 },
22 "showValues": true,
23 "axisMode": "multi",
24 "binValues": false,
25 "bins": {
26 "breakpoints": {
27 "low": 0,
28 "high": 100
29 },
30 "bands": {
31 "low": {
32 "label": "",
33 "color": "#B22222"
34 },
35 "medium": {
36 "label": "",
37 "color": "#ffa500"
38 },
39 "high": {
40 "label": "",
41 "color": "#008000"
42 }
43 }
44 },
45 "dimensionAxis": {
46 "showAxis": true,
47 "showTitle": true,
48 "title": "",
49 "customSize": "auto",
50 "icons": {
51 "useIcons": false,
52 "iconProps": {
53 "column": "",
54 "fit": "cover",
55 "type": "round"
56 }
57 }
58 },
59 "measureAxis1": {
60 "sqrtScale": false,
61 "showAxis": true,
62 "customDomain": {
63 "showDomain": false
64 },
65 "showTitle": true,
66 "title": ""
67 },
68 "measureAxis2": {
69 "sqrtScale": false,
70 "showAxis": true,
71 "customDomain": {
72 "showDomain": false
73 },
74 "showTitle": true,
75 "title": ""
76 },
77 "legend": {
78 "show": true,
79 "showHeader": true,
80 "inside": false,
81 "descOrder": false,
82 "position": "right-top",
83 "customSize": "auto"
84 },
85 "tooltip": {
86 "customizeTooltip": false,
87 "showDimensions": true,
88 "dimensions": "",
89 "showMeasures": true,
90 "measures": "",
91 "showPercentage": true,
92 "showNullValues": true,
93 "showBinLabel": true
94 },
95 "trellis": {
96 "enable": false,
97 "showGridLines": true,
98 "flipLabels": false,
99 "type": "x",
100 "chartsPerLine": 4,
101 "size": [
102 100,
103 100
104 ]
105 },
106 "applyConditionalFormatting": true,
107 "showActionMenu": true
108 }
109 },
110 "label": "Amount_1",
111 "selectMode": "single",
112 "broadcastFacet": true,
113 "receiveFacetSource": {
114 "mode": "all",
115 "steps": []
116 }
117 }
118 },1"query": "{{cell(static_1.selection, 0, \"query\").asString()"The static_1 step looks like this:
1values: [
2{query: "q = load \"opp\"; ..."}
3{query: "q = load \"account\"; ..."}
4]Every dataset referenced in a binding of a saql step must be referenced by another step in the dashboard. If not, Analytics removes the dataset from the datasets attribute in the dashboard JSON. As a result, widgets based on the saql step display an error because it can’t find the dataset.
Tip
j