Widgets & Datasets

A Dataset is a logical grouping of data (typically the results of a query).

A Widget is a visualization on a dataset. One or more widgets can point to the same dataset.

A dataset and widget is automatically created by Knowi for a query.


Widgets and Datasets can be created in the following ways:

  1. Results of queries against your datasources, from the UI or via the Agent.
  2. Using our Push Data API.

To create a widget from an existing dataset, go to the widget listing menu or the Add Widget to Dashboard menu to create and point to an existing dataset.

Add Widget

Widgets can also be cloned from other widgets with its own filters and data manipulation.

Query, Dataset and Widget Mapping

To see a visual mapping of how widgets are related to datasets and their associated queries, click on Data Config on the widget settings.

You can preview visualizations, edit the query directly from the diagram as well as zoom into any derived datasets.

Data Management

The diagrams are also accessible the query listing page.

Widget Settings

Widget settings can be accessed from the options menu of a widget in a dashboard.


Widget Settings

Field Interpretation
Visualization Type Visualization Type
Visualization title Name for this Widget
Category List of categories to associate the widget to. Categories list dropdown can be found within the widget listing menu. To add a new category, type it in. To add multiple, hit enter after each.
Ignore Fields Ignore one or more fields from the visualization
Max Records Maximum Number of records to run the analysis on. Leave it empty to profile all data for this dataset
Live Data Check the box and specify a frequency for in-dashboard widget auto update (when displayed on a TV screen for example)
Description "If set, display a popover description via an info icon on the widget which also supports HTML format, hence, providing you with further abilities like adding hyperlinks, changing text color, changing font style, and much more"
Footnote A footnote to display at the bottom of the widget
Select Widgets Select up to 3 widgets (Available only in InstantSights Visualization)

Chart Configuration

Field Interpretation
Field containing Size/Count Size mapping of the text field
Field containing text Select the field that contains the text to analyze
Minimal angle Control the text angle display
Max angle Control the text angle display
Plot Data/Y-Axis Numeric Y-axis field to use. Leave it empty if for multiple Y-axis fields.
Pie and donut charts will automatically sum the rows in your dataset by the selected grouping and value fields. The user must manually transform their data to aggregate by avg, min, max, etc. with C9QL or in the analyze tab.
Y-Axis Categories Categories displayed vertically for a grid heatmap
Sub Categories Sub Categories for each parent category
Minimum color Color name range minimum
Middle Color Mid range color
Max Color Color name range maximum
Quick Picker X-Axis Quickly change value of X-axis from widget top
Quick Picker Y-Axis Quickly change value of Y-axis from widget top
Max Y-Axis Items Max number of items to display on Y-axis
Max X-Axis Items Max number of items to display on X-axis
Enable Y-Axis Scroll To avoid overcrowding
Enable X-axis Scroll To avoid overcrowding
Baseline Value Custom baseline value
Median Median of the box
Lower quartile Lower quartile
Upper quartile Upper quartile
Low whisker Low whisker
High whisker High whisker
Theoretical mean Theoretical mean
Invert Axes To invert the axes
Grouping/Legend Legend/series field if a column contains the fields.
X-Axis X-axis field if applicable.
X-Axis Ordering Optional X-axis data ordering if applicable.
X-Axis Type Set to date/time for a time series chart.
Show Total When checked, the total sum across the entire series will be displayed at the end
Bubble Size Field Denotes the size of the bubble
Intermediate sum When this property is set, the points act as a summary column for the values added or subtracted since the last intermediate sum
Y-Axis Max Optional max Y-axis value. Use it in conjunction with the tick interval to set the Y-axis labels.
Y-Axis Tick Interval Optional Y-axis tick interval to set the Y-axis labels.
Target Line Optional value for the target line only applies to the primary Y-axis.
Historical/Current Value Set the field with historical/current values
Y-Axis Min Set the Y-axis minimum values
Projections Set the field with projected values
Lower boundary Lower boundary field name
Upper boundary Higher boundary field name
X-Axis Sub Groups (Beta) To create multiple X-axis sub groups
Y-Axis Logarithmic Scale Axis For log scale, enter logarithmic
Y-Axis Values in Reverse Order Check to reverse the axis so that the highest number is closest to the origin
Enable Stacking Enable stacking for bar chart
Anomaly Algorithm Anomaly forecasting algorithm
Anomaly Deviation Mean absolute percentage threshold setting
Max Value Goal value
Min Value Start value
Start Color Enter color name or code
Color - Mid Point Enter color for the mid point of the gauge
End Color Color stop at the end of the scale
First Range Value Numeric stop value for the first range
Second Range Value Numeric stop value for the second range
Third Range Value Numeric stop value for the last range
First Range Color Color stop value for the first range
Second Range Color Color stop value for the second range
Third Range Color Color stop value for the third range
Center Latitude Map center latitude
Center Longitude Map center longitude
Zoom Level Map zoom level
Marker Pin Text To display the text on the marker when clicked
Map Type Type of map
Tile Provider Geo tile provider for look and feel options
Point Styles Display points as cluster groups, simple pins, or heatmap
Count Field If you have lat/long points with a weighted number field
Marker Color Field Customize marker color, where the field selected contains the marker color to display
Radius The radius of influence for each data point
Max Opacity Ranges from 0 to 1 to control the look and feel of the heatmap
Min Opacity Ranges from 0 to 1 to control the look and feel of the heatmap
Blur Factor To control the gradient
Primary Region Set a region displaying on the map
Tooltip Tooltip display mode
Border Resolution The resolution of borders
Metric to Track Field to show
Previous Value Last value to compare to
Percent Change Percentage change calculation
Original Value Show/hide original value
Threshold Value Enter threshold value to check against
Color - Below/Equals Threshold Defaults to red
Color - Above Threshold Defaults to green
Metric Field Field to set threshold against
From Choose the field that represents from
To Choose the field that represents to
Counts/Values Choose the field that represents the counts
Ordering of nodes To set nodes
Step change angle Control the angle display step
Font To specify the font
Font size To specify the font size
Days on Screen Set the days on screen
Start Time Set the start time
End Time Set the end time
Group Field Group field
Event Type Label on the left hand side to group by items
Text code Enter text or HTML code
Web page link Enter webpages URL link here. It also allows the user to pass the URL from the dataset. Type the field name into the Web page link surrounded with two sets of curly brackets. For example: {{URL_field}}
Image URL Add image URL
X coordinate Represents X coordinate
Y coordinate Represents Y coordinate
Point Size Defaults to 1
Point Color Defaults to red
Bottom Left Zero Position Defaults to top left
Scale Coordinates Can be integer or decimal
Group By Select a field to group points by
Hover Fields Fields to show when hovering on points
Edges type Select which edges type to display
Integration type Determines how forces are applied on the particles
Max X-Axis Items Max number of items to display on the X-Axis
Enable X-axis Scroll (Controls scrollbar visibility) Enable X-Axix scroll to avoid overcrowding. Use the Max X-Axis items in conjunction with this property

Display & Formatting

Field Interpretation
Title Font Color Set the title font color of the widget
Title Font Size The default title font size is 14px.
Font size To set the size of the font
Font color To set the color of the font
Label font size To set the label font size
Label font color To set the label font color
Vertical Change orientation to vertical
Align content horizontally Align content horizontally
Align content vertically Align content vertically
Hide field names Do not display field names
Strong field names Use bold fonts for field names
Up caret color Defaults to green
Down caret color Defaults to red
Grid line thickness Grid line thickness value
Cell Padding Padding of cell content
Data Format Formatting for one or more fields
Display Theme Select a theme for chart types
Colors To set and add color for chart
Legend Alias Change legend display text
Background Color Change background of widget
Legend Ordering Legend ordering method, if applicable.
Percent Stack Type To display stacking as a percent
Display "Total" To show total
Legend Show/Hide Display legend when enabled
Legend font size Font size of the legend
Reverse Legends To reverse the order of the legend items
Fit To Widget Width To make columns shrink to fit widget width to eliminate horizontal scroll
Footer Font Size To set the font size of the footer
Footer Row Height To set the row height of the footer
Text Wrap Allow cells text to break on multiple lines
Single Row Representation collapse all nested rows to single row
Y-Axis Grid Line width Defaults to 1; set to 0 to hide grid lines
Enable Reverse Stacking To reverse stacking
Data labels around marker Allow data labels to follow marker's shape
Vertices radius Default to 10
Edges width Set edges line width
Vertices color Set color name for vertices color
Edges color Set color name for edges color
Data Labels Position Set data labels position relatively to vertices
Column (bar) width Set the width for columns or bars in pixels
Display Start / End Value (Gauge/Goal widget) This shows 'Display Start Value & Display End Value' to show the minimum and maximum value of the gauge on the widget. The color of the gauge can change depending on the value of the data shown.

Column and Header Settings

Field Interpretation
Header Background Color Set the header background color; default to dark blue
Header Font Color Set the header font color; default to black
Header Font Size Set the header font size
Header Height To adjust the height of the header
Minimum Column Width To set the minimum grid width
Column Ordering column ordering
Column Sort Order Sorting order of column headers
Hide Last Header Row To hide the last header row
Total Column Additional column with summary for each row
Hide Column To hide the column from the grid
Reset Column Width Reset each column width to default

Row Settings

Field Interpretation
Color of Odd Rows Default to white
Rows Font Color Set the font color of rows
Rows Font Size Set the font size of rows
Rows Background Color Default to white
Total Row Footer row with summary for each column
Auto Collapse Rows Shows all rows initially collapsed
Color of Even Rows Default to white
Row Height The height of each row in the grid

Aggregation and Grouping

Field Interpretation
Aggregation Aggregation for group
Grouping Grouping by some parameters
Aggregation on top Check to show aggregation on top

Widget Labels

Field Interpretation
Label - Display as Percent Convert display label values to percentage
Label - Display value Display the series name and associated values
Display Y-Axis Title Display Y-axis title; enabled by default
Y-Axis Label Display Hide/show Y-axis labels
Y-Axis Title Text Title for Y-axis
X-Axis Title Title for X-axis
X-Axis Label Display Hide/show X-axis labels
X-Axis Label Rotation Degrees of rotation of X-axis labels; useful for long labels
X-Axis Date Formatter Override the default X axis date format. Only applicable for chart types with Date/time X axis. See formats here
X-Axis labels format as data units Bytes, KB, MB, GB, etc.
Stack Label Display Set false to turn off column total data label
Stack Label Font Size Stack label font size
Data Label Display Check to display value labels. Default is false
Data Label Font Size Enter font size, if the display label is set to true. Example: 15px. Defaults to 9px.
Data Label Formatter For formatting help, click here
Y-Axis Labels Formatter For formatting help, click here
Data Label Decimal Places Number of decimal places in data label
Symbol After Data Label Symbol to display after data label
Data Label Padding Set padding around data labels
Data Label Allow Overlap To allow data labels to overlap
Data Labels X Offset The X position offset of the label relative to the point in pixels
Hover Label Format For formatting help, click here
Data Labels Y Offset The Y position offset of the label relative to the point in pixels
Hover Decimal Places Number of decimal places to show on tooltip

Secondary Chart Configuration

Field Interpretation
Secondary Y-Axis Optional secondary Y-axis on the right-hand side of the chart.
Secondary chart type Chart type for the secondary chart
Secondary chart grouping Display a second stacking groups on the X-axis based on the string field selected
Synchronize Y-axis Ticks Align primary and secondary chart axis tick marks
Secondary Chart Send to Back Adjusts (z-index) to send the secondary chart behind the first.
Synchronize Y-Axis values Synchronizes the Y-axis primary and secondary to the same values.
Secondary Y-Axis Max Set the Y-axis max values for the secondary Y-axis. x-axis fields
Secondary Y-Axis Logarithmic Axis For log scale, enter logarithmic
Secondary Y-Axis Min Set the Y-axis min values for the secondary Y-axis

Secondary Chart Display

Field Interpretation
Secondary Y-Axis Title Display Display secondary Y-axis; enabled by default
Secondary Data Label Display Display secondary value labels; default is false
Secondary Y-Axis Title Text Title for secondary Y-axis
Secondary Data Label Formatter For formatting help, click here
Secondary Y-Axis Labels Formatter For formatting help, click here
Secondary Y-Axis Symbol Before Data Label Symbol to display before data label for secondary Y-axis
Secondary Y-Axis Symbol After Data Label Symbol to display after data label for secondary Y-axis
Secondary Data Label Decimal Places Number of decimal places in data label for secondary Y-axis
Secondary Data Labels X Offset The X position offset of the label relative to the point in pixels
Secondary Y-Axis Value in Reverse Order Click to reverse the axis so that the highest number is closest to the origin
Secondary Data Labels Y Offset The Y position offset of the label relative to the point in pixels

Widget Menu

Field Interpretation
Show Title Show Title on Widget
Analyze Show Analyze menu
Alerts Show Alert icon
Filters Show Filter icon
Drilldowns Show Drilldowns menu
Query Show Query menu
Data/Export Show Data/Export menu
Data Diagram Show Data Diagram
Share Show Share menu
Refresh Show Refresh menu
Maximize Show Maximize menu
Remove from Dashboard Show Remove from Dashboard menu
InstantSights Show InstantSights

Advanced Configuration

Field Interpretation
Animation Animation of chart, ON by default
Time Series Navigator Enable/Disable time series navigator at the bottom of a time series chart; enabled by default
Polar To transform cartesian charts like line, spline, area and column into the polar coordinate system
Use UTC for Time Series Charts Disable auto browser conversion of Timezone for the time series charts and show UTC timestamps
X-Axis Ordinal Points are equally spaced in the chart regardless of the actual time or x distance between them
Use GPU Translations in Boost Mode When in boost mode, GPU translations are faster than regular JS translations
Scroll Limit Scroll paging; default is 1000 records
Internal Sparkline Charts Allows you to create charts within cells to see trends
Enable Pivot Configuration Displays the configure button for pivot tables for non-viewer roles
Reset Pivot Structure Clear all rows, columns, values, and filters
Change Dataset Change to a different dataset
On Click Event Handler Define custom javascript behavior when a point is clicked


Field Interpretation
Custom Tile Provider Custom tile provider URL
Custom WMS Custom layers URL
Custom Map Layers Layers names
GeoJSON URL Optional GeoJSON for additional layering
GeoJSON Code Optional GeoJSON for additional layering
Custom Javascript Handler Optional Javascript for additional handling

Search Bar on Settings Area

Now you can search any field on the search bar related to the settings area of your visualizations. The search bar will allow you to focus on that particular field you are searching for and you can configure the value of that field directly.

For example, If you want to set/change the font size, font color, or header height then you can type any field in the search bar and it will suggest and fetch the related fields on your settings area panel.

Search bar on setting area


  • Basic filtering can be used to set filtering on the data.
  • Cloud9QL can be used to further manipulate the data in advanced ways. See Cloud9QL documentation for more details.

Knowi widget filters have the same functionality as their dashboard counterparts with the added benefit of also being able to incorporate Knowi's highly flexible cloud9QL function to further manipulate the data contained in a particular widget.

Refer to the following for more details: Dashboard Filters [Cloud9QL](docs/cloud9QL.html

Cloud9QL Widget Filtering

Ad hoc Analysis

Data associated to a widget can be analyzed using a drag & drop interface. See Ad Hoc Analysis section for more details.


Drilldowns enable powerful point and click drilldowns from one widget into another widget. Data from the parent widget can be used as keys into the drilldown widget to filter the data specifically for the point selected.



Cloning copies an existing widget with out without original data. Typically used in the following cases:

  • To create a new widget with the same settings as the existing data, but pointing to a new dataset.
  • To create a separate view of the same data.
  • To create a separate view of the different data by changing the dataset.


Filters and Cloud9QL can be applied to the new widget to further manipulate the cloned widget.


Share - Internal Users and Groups

A Widget can be shared with multiple internal users and groups within your organization. From the widget settings menu, 'Share' icon, check users and/or groups to share the Widget to.

User Groups can set in the Team settings in the User Settings menu.

You can also set one of following to user or group to define access:

  • View Only: The user will only be able to view and interact with the widget and will not be able to save, modify widget or widget settings.
  • Edit: Ability to edit the widget.
  • Admin: Ability to edit widget, plus being able to set Global filters and change widget level Cloud9QL.

Share - Public

A Widget can be shared in isolation (not as part of a dashboard) by selecting the 'Share' icon. This will generate a public URL for a widget.

Note: This makes the widget publicly accessible, without requiring a login. Do not use this option for sensitive data.

The widget shared in isolation will have no dashboard filters applied, so please always check how widget looks via url before sharing widget link to someone.

In addition, the embed code can also be used to embed the widget into your own portal/HTML pages.

To turn off a unique public URL, click on 'Disable Share URL'.

To add filter parameters to the share URL, pass in contentFilters parameter to the URL, where the value is in encoded JSON form.

Example: URL Parameter example: contentFilters=[{"fieldName":"opened","values":[1000],"operator":">"}]

Full URL, with the parameter and encoded JSON:

Sharing Widget Analytics

In additional to sharing widget, it is possible to share widget with analytics mode expanded. Use same widget sharing URL by appending ?analytics=true.

See Self Service Analytics for more info.


We provide a number of options for embedding, depending on the level of access required. See embed docs

Data Management

Data Management allows the user to configure additional settings for a given dataset. It can be accessed via the query listing screen by clicking the Data Management icon to the right of each query, or via a widget by navigating to More Settings > Data Diagram then selecting the gear icon of the widget (blue box).

Data Types

Allows you to view/edit the data type of existing fields in the dataset.


NLP Indexer

Defaults to ON. Turning it off will exclude the dataset from Search-based Analytics/NLP queries. Note that it may take a few minutes for the change to take effect.


Synonyms are useful for adding context awareness to your Search-based Analytics/NLP queries. For example, if you have a field in your dataset named customer, you can add a synonym "tag" to this field such as "shopper", "buyer", "clent", etc. So, when you type in a question like "total sent by client", it will recognize the term "client" as equivalent to the field "customer". Multiple synonyms can be added for each field.

Visualization Templates

Visualization templates allow the user to build pre-configured widgets that are produced when creating a widget from the dataset when specific metrics and dimensions are selected. This will show the same visualization with your predefined settings for similar questions you ask the data in NLP or transformations you make in the analyze mode.

Example: For the prompt Show me sent, bounced weekly by customer We can create a template where sent is displayed as a bar chart with bounced as a secondary line chart. Now for similar questions, like total sent, bounced by customer for Facebook weekly, the same chart template will be shown.

Visualization templates can be managed from the Visualization Templates panel on the dataset page.



Allows you to specify one or more index fields for commonly used filter attributes. Useful for larger datasets to help speed up results. For example, if the field date is a commonly used filter, setting this as an index will help speed up results when you filter by date.


Displays the raw dataset in tabular format. Date/Time of the last data upload/update for this dataset is listed at the bottom left of the dataset. Click on the Export button to export data in CSV form.

Dynamic Widget Names

Widgets can be dynamically named, based on parameters passed into the dashboard, or via data elements within the widget.

To dynamically pass in widget name via a runtime parameters, use the $c9$ syntax and pass the token in via contentFilters in the UI/embed mode, or using the filters. Example: _A widget for $c9orgname$. In this case, the $c9orgname$ token is dynamically populated. See Content Filters for more info.

To dynamically populate widget names driven by a field within the data, use the {{fieldname:n}} syntax where fieldname is the field to use and n is the row position of that field. Example A widget for {{orgId:1}}. In this case, the first item in the orgId field in the dataset is used to dynamically display the widget name.