Data cube and dashboard query parameters reference

You can create a URL that links directly to a Pivot data cube or dashboard.

This topic contains a description of the query parameters you can use to define the view of the data cube or dashboard in the link.

URL structure

The URL contains the Pivot URL and the data cube or dashboard ID, followed by the query parameters that filter the view.

You can use the Pivot API to retrieve data cube and dashboard IDs. To locate the ID in the Pivot UI, go into the data cube or dashboard and click the Options icon, then select View essence.

info

You can only use URL parameters to query Pivot 2.0 data cubes, not classic data cubes.

The structure of PIVOT_URL differs for cloud and on-prem installations. The following example shows the PIVOT_URL for a cloud installation:

cloud.imply.io/p/CLUSTER_ID/pivot

The following examples show PIVOT_URL for an on-prem installation:

example.my-on-prem-imply-installation.net
example.my-on-prem-imply-installation.net/path/to/pivot

Data cube URL

https://PIVOT_URL/i/DATA_CUBE_ID?visualization=VISUALIZATION_TYPE&QUERY_PARAMETER=VALUE&...&QUERY_PARAMETER=VALUE

See Visualization for a list of visualization types.

The following link applies the table visualization with a dimension, measure, and filter to a data cube with ID wikipedia8e5e:

https://cloud.imply.io/p/d31f1215-c955-4ceb-a5e3-24eaa400c457/pivot/i/wikipedia8e5e?visualization=table&dimension=cityName&measure=sum_added&filter=cityName[in](London,Paris)

Dashboard URL

https://PIVOT_URL/c/DASHBOARD_ID?QUERY_PARAMETER=VALUE&...&QUERY_PARAMETER=VALUE

The following link filters a dashboard with ID 0b96 to show new events:

https://cloud.imply.io/p/0f5ea5af-9g2e-5ecd-b48e-90c62062aae2c/pivot/c/0b96?filter=isNew[eq]true

Reserved characters

Use URL encoding for reserved characters and spaces. For example, represent the hash character in #en.wikipedia as %23: filter=channel[eq]%23en.wikipedia.

See Percent-encoding for more information and a list of reserved characters.

Query parameters

You can use the following query parameters to construct a link to a data cube or dashboard.

Data cube parameters

The following query parameters apply to data cube URLs.

visualization

The visualization to apply to the data cube. You must set a visualization if you want to apply any of the other query parameters or a filter.

• Value: Visualization name—one of:
  bar_chart, bubble-chart, flat_table, gauge, geo-marks, geo-shade, heatmap, horizontal-bars, line-chart, line_chart (multi-axis line chart), overall, path-tree, pie-chart, records, records-table, sankey, sparkline, spot-matrix, stack-area-chart, street-map, sunburst, table, time_series, totals, treemap, vertical-bars

• Supports multiple: No

Example to set the visualization type to table: visualization=table

dimension

One or more dimensions to apply to the data cube.

• Value: Dimension ID
  Use the Pivot data cubes API or view dimension info in the Pivot UI to find dimension IDs.
• Supports multiple: Yes

Example to set dimensions to city name and channel: dimension=cityName&dimension=channel

pinnedDimensions

One or more dimensions to pin to the sidebar in a data cube.

• Value: Dimension ID
  Use the Pivot data cubes API or view dimension information in the Pivot UI to find dimension IDs.
• Supports multiple: Yes

Example to pin the country name and city name dimensions to the sidebar: pinnedDimensions=countryName&pinnedDimensions=cityName

measure

One or more measures to apply to the data cube.

• Value: Measure ID
  Use the Pivot data cubes API or view measure info in the Pivot UI to find measure IDs.
• Supports multiple: Yes

Example to set measures to comment length and added: measure=sum_commentLength&measure=sum_added

compare

Include a time comparison—for example, to compare current data with a previous period of time.

• Value: Date or duration
• Supports multiple: No

Example to compare data with the previous 6 months: compare=P6M

Dashboard parameters

The following query parameters apply to dashboard URLs.

page

Link to a specified dashboard page.

Before you use the page parameter, go to the dashboard options in the Pivot UI and make sure Pages is set to Show pages selector. See Dashboard pages for more information.

• Value: Dashboard page ID
  Pivot numbers dashboard pages 1, 2, 3, etc as they appear from top to bottom in the UI.
• Supports multiple: No

Example to display the second dashboard page: page=2

Filter parameters

You can add filter parameters to both data cube and dashboard URLs. Pivot supports the following filter parameter types:

String

• Operators:
  Equal to: eq
  Contains: contains
  In: in
  Not equal to: ne

Examples:

Filter for city name equal to "London": filter=cityName[eq]London
Filter for city name containing the characters "Lon": filter=cityName[contains]Lon
Filter for city name "London" or "New York": filter=cityName[in](London,New%20York)
Filter for city names not equal to "London" or "New York": filter=cityName[ne](London,New%20York)

Number

• Operators:
  Greater than: gt
  Less than: lt
  Greater than or equal to: gte
  Less than or equal to: lte
  Provide both upper and lower limits

Example to filter for comment length greater than 10 characters and less than 20 characters: filter=commentLength[gt]10[lt]20

Boolean

• Operator: eq

Example to filter for records with the "isNew" flag set to "true": filter=isNew[eq]true

Time

• Operators:
  Start date and time: start
  End date and time: end
  Latest interval: latest
  Previous interval: previous
  Current interval: current
  Provide both start and end to define a fixed time interval—you can't use these operators alone.
• Valid intervals:
  latest: 1hour, 6hours, 1day, 7days, 30days, 3months
previous: hour, day, month, quarter, year
current: hour, day, week, month, quarter, year

Examples:

Filter for records with timestamp between and including 2022-01-01 and 2022-01-02: filter=__time[start]2022-01-01[end]2022-01-02
Filter for records with timestamp set to the previous day: filter=__time[previous]day