This pages provides a detailed guide to building visualizations using Views.

Guide to building visualizations with Views

kdb Insights Enterprise Views enable you to build visualizations that help you to understand complex data. This page follows on from the quickstart guide and provides more detailed instructions on setting up Views.

The following sections explain how to:

• Create a View and add a component
• Share a View with other users
• Configure the properties for your View
• Configure the data source for your components
• Add up to 40 different components to your View
• Configure view states to store values and states
• Configure highlight rules

Views & Dashboards

In the context of kdb Insights Enterprise UI the terms Dashboards and Views are synonymous.

Create a View and add a component

1. Before you can create a View you must deploy the following:

   • a pipeline that ingests the data used by your View. See pipeline for details.
   • a database that stores the data used by your View. See database for details

2. Create a new View in one of the following ways:

   • click + on the ribbon menu and then click on View
   • click the + beside Views on the left hand panel
   • click Visualize on the Overview page, as shown below.

   Each of these methods opens a new View workspace.

   
   

3. Click Design on the top of the workspace to design and edit your view.

4. Click-and-drag a component into the central workspace. A Data Grid is a good component to start with, as shown here.

   

   Breadcrumbs at the top of the workspace indicate the selected item. For example Data Grid.

5. With the new component selected, Click to populate Data Source to open the data editor.

   For this example choose API and select a table generated by a pipeline. Define the date range of the data with startTS and endTS.

   !!! note
   
       "The **startTS** and **endTS** range are from the _Timestamp_ column as set in the table schema."
   

   See here for full details on data source configuration.

6. Continue to build your view by adding more components, defining data sources, and arranging the workspace as required.

7. Click Preview, at the top of the workspace to interact with your dashboard.

8. Click Save Dashboard in the top left-hand corner of the workspace and name the View. The undo icon beside it can be used to revert any changes.

   Saved Views

   Saved Views persist across sessions, but any required update reset all changes.

Share a View

You can share any of the Views you have created with colleagues.

1. Click on the additional actions three dots on the left-hand menu and click on Share as shown here.

1. You can copy the link displayed or open the link in a new tab. Anyone you share with must have read access to view the Views you share with them.

Configure the properties for your View

When no component is selected in the workspace, the properties of the view are displayed in the right-hand panel. These are referred to as dashboard properties, as shown below.

The dashboard properties are divided into the following settings. Click one of the following links to find out more about these properties.

• Basics
• Style
• Popups
• Shortcuts
• Notifications
• Screens

Basics

These are the basic properties for the dashboard. You can define a name for the dashboard and then link and setup the workspace area using the properties described in the following table.

item	description
Hash	Name of dashboard view.
Link	URL reference for the view.
Hostname(s) access	List of hostnames (comma separated) permissioned to access the view; if not set, all hostnames have view access.
Enable "Share Dashboard"	Not used by kdb Insights Enterprise.
Share Viewer State	When enabled, the current view states are saved for use in the next decision. If disabled, default view state values are used.
Unsaved Viewer Prompt	Not used by kdb Insights Enterprise.
Fill Height	When enabled, view scales to height of browser. When disabled, view height is Column Count * Row Count in pixels.
Floatable	When enabled, components can be locked anywhere in the workspace grid. When disabled, components lock from top-down of workspace.
Column Count	Defines the number of column anchor points.
Row Count	Defines the number of row anchor points.

Click here to learn more dashboards basic properties.

Style

The style properties allow you to set border colors, background color and spacing between components on the dashboard.

item	description
Dashboard Theme	Defines whether the view is to be a Light or Dark Theme.
Theme Switchable	Check if you want to be able to switch between light and dark themes; uncheck to lock color to selected Dashboard Theme.
Widgets Spacing	Set distance between components in pixels.
Widget Shadow	Enable for component shadow.
Background Color	Defines the background color of a component.
Transparent Background	Check to enable transparency; uncheck to use Background Color.
Border Size	Sets the width of border in pixels.
Border Color	Sets the color of border.
Border Rounding	Applies a rounding to border corners; 0 for no rounding.
Border Spacing	Defines the amount of space between components; set in pixels.
Worksheet Padding	The padding in pixels around each component.
Show Loading Indicators	When Checked the dashboard shows a loading icon when components are accessing data.
Advanced CSS	Any Advanced CSS component can be used to define the CSS for any component in a dashboard. See here for details.
CSS Classes	CSS Classes can be used to style components. See here for details.

Click here to learn more about dashboard styling properties.

Popups

You can create a popup and then edit it to add content into the popup element.

Click here to learn more about popups.

Shortcuts

You can assign a keyboard key to the data source and execute when pressed.

Click here to learn more about shortcuts.

Notifications

You can specify whether notification messages, for example a failed login attempt, appear on the screen.

Click here to learn more about notifications.

Screens

Each dashboard has a main screen; other screens can be added and linked using the Button component.

Click here to learn more about screens.

Components

There are over 40 components available which can be added to Views. When you click on a component in the workspace, its configurable properties are displayed on the right-hand panel. A selected component has a light-blue border.

To add a component to your view:

1. Click-and-drag a component from the left-hand menu into the workspace. When dragging a component into a workspace, be careful not to drop it on top of another as this replaces the underlying component. Any such change (or others) can be undone by clicking the undo action in the report menu bar next to the save icon.

Component	Description
Data Grid	Tabular data display and handling.
Pivot Grid	OLAP drilldown data display.
ChartGL	Hardware accelerated charts using WebGL; supports line, bar, bubble, waterfall, bounds, candlestick, heatmap and baseline charts.
Pie Chart	Circular statistical graphic.
Radar Chart	2D multivariate data graphic.
Canvas Chart	Basic line, bar, bubble, candlestick, violin, boxplot, and waterfall charts.
3D Chart	3D charting (with highlight rule support for 4D); dot, surface, bar, grid, and line charts.
Gauge	Display a single value of quantitative value.
Layout Panel	Container for components.
Flex Panel	Flexible, two-component container.
Tab Control	Tabbed component container.
Accordion	Collapsible component container.
Overlay Panel	A container to overlay components.
Data Form	Input display for query parameters; text, dropdown, and date picker selectors.
Form Builder	Create a custom form for users.
Drop Down List	Single or multi-select dropdown component.
Button	Single button supporting multi-action select.
Text Input	A text input component.
Text	WYSIWYG text editor with HTML support.
Selection Controls	Radio or check-box selection control.
Date Picker	Date or date-time input.
Navigation Menu	A navigation bar.
Breadcrumbs	Navigation element for OLAP data.
Tree View	A tree-view navigation selection component.
Data Filter	User generated queries; text and dropdown filters (no coding required).
Visual Query Builder	Graph-based visual query builder; support for multi-data sources with update, group-by, join, filter and custom functions.
Editable List	A custom dropdown menu.
Range Slider	A data range selector; interval or time.
Playback	A multi-control stream player suitable for video content, interval, or time sequence data playback.
Upload	File transfer to/from server.
Map	Map component featuring Google maps.
Mapbox	Map component with 3D overlay driven by Mapbox.
Treemap	Treemap or heatmap data graphic.
Sunburst	Sunburst (ring/doughnut) chart for hierarchical data.
Graph	Network/Flow relationship map.
Sankey	A flow diagram where the width is proportional to the rate.
Bipartite Chart	A chart of two independent data sets, with relationship connections between the data sets.
Vega Chart	Support for Visualization Grammar charts.
Financial Chart	International financial charting component; OHLC, Line, Candlestick, Mountain, Heikin Ashi, Kagi, and over 20 technical indicators and user annotation support.
ChartIQ	Integration of chartIQ financial charts; separate license requried.)
Trade	Add a Forex trade panel with TWAP and VWAP support and tick updates.
Contour	Add a contour graphic; plotting 3D data in 2D.
Blob Download	Download files from byte array in database.
Bitmap	Bitmap generated chart.
Video	Add video content to a dashboard.
Analyst Visual	Embed a KX Developer graphic into a chart.
Scatter	Add a quartet or matrix graphic.
External Content	Embed web page content.
Code Editor	Embeddable code editor with support for json, plaintext, handlebars, html, java, javascript, markdown, python, r, sql, typescript, xml, and q.

Configure the data source for a component

Each component on your View must have a data source from which data taken to be displayed. The following sections describe how to:

• Setup a data source using each of the methods; API, SQL, kdb/q, Streaming and Virtual
• Setup the subscription type
• Verify results of the data source queries

Set up a data source for Views

1. Open the data editor by doing one of the following:

   • Click on Click to populate Data Source in the component on the workspace.

   • Select Data Source in Basics Properties for the component, as shown below.

     

2. Click New to add a new data source.

3. Next click on the relevant radio button to select the type of query you are adding. The following query options are available:

   • API - an API (getData)
   • SQL - an SQL query
   • kdb/q - a kdb/q query
   • Streaming - a pipeline setup to subscribe to streaming data. BETA - for evaluation and trial only
   • Virtual - a query using javascript

   The configuration for each of these query methods is described in the following tabs.

APISQLkdb+/qStreamingVirtual

You can query data directly, without requiring code, using the API option.

• Select a table from the active data sets stored on your database.

Labels

You can query data with API Labels. Labels are defined in the database. You can use a label to select data from a particular table when data column names are shared across multiple tables.

• Define the startTS and endTS from the timestamp column in your table. It can be helpful to use the scratchpad to get the date range.

The full set of API properties are described in the following table.

parameters	description
table*	table name as referenced in the database
startTS*	Start time of returned data. If a preset date range is required for a View, set temporality property to slice and define the slice property for start time.
endTS*	End time of returned data; defaults to today's date. If a preset date range is required for a View, set temporality property to slice and define the slice property for end time.
filter	define by (function;columnname;parameter), for example >;valuecolumn;100 to filter "valuecolumn" to values above 100. Selected functions include >, = or < and can include text values; for example =;name;Jim will return rows of data where the "name" column contains 'Jim'.
groupBy	Select data column(s) for grouping data.
agg	Define columns to select: `price`size, an aggregation `col1`avg`price, or a dict(ionary) aggregation `col1`avg`price;`col2`sum`size.
sortCols	Sort results by selected column.
slice	Sets the time range for startTS and endTs when slice is set for temporality.
fill	How to handle nulls in the data. Select between zero to treat nulls as zeroes, or forward to carry forward a previous, non-null value.
temporality	Set to slice if data returned is between a defined startTS and endTs; use the slice property to set the date range. Set to snapshot for a continuous range of data.
labels	Where data columns are shared across different tables an (optional) label can be applied to restrict returned data. For example, table1 has a region property for 'north america' and table2 has a region property for 'europe', then a label of region:europe will return data from table2 only. Data can be returned from tables in different databases.

!!! "Required fields are denoted, in the table above, with *".

Use the code editor to write SQL queries. The following select query is illustrated in the screen below.

select * from tablename

Use the code editor to write q/sql

Querying data with the q editor. Use a simple "select from tablename" as a starter.

select from tablename

Beta - For evaluation and trial use only

Streaming to Views is currently in beta.

• Refer here for the standard terms related to beta features.

• We invite you to use this beta feature and to provide feedback using the portal available here.

• Refer here for known limitations of this beta feature.

A Streaming data source requires a pipeline that writes to a subscriber node (a generic named target that can be subscribed to later). The View component is then linked to this pipeline to listen to this subscriber and receive real-time data updates. The following screen shows the data source setup for streaming data.

The data source parameters you need to configure for streaming components are defined here.

parameters	description
pipeline	This field provides a list of running pipelines with subscriber nodes. Select the pipeline that contains the data you want to stream to your component.
table	This is a dropdown list of available tables. Select the table containing the data you want streamed to your component.
filters	You can filter streaming data, based on any keyed column, to show a subset of the data.

Current filter restrictions

• Filters must be defined using the JSON format: {"keyed_column":"value"}.
• Only one keyed column can be filtered on.
• Only one value can be applied to the keyed column.

• Click here for a guided walthrough on creating a View with streaming data.

Use the code editor to write Javascript to meld data from multiple data sources, view state parameters or text inserts. Virtual queries run against data stored on the client.

function (source, selectedName, callback) {
    var filtered = _.clone(source);
    filtered.rows = source.rows.filter(r => r.name === selectedName).map(r => _.cloneDeep(r));
    callback(filtered);
}

Use these links to find our more information about:

• View state parameters
• The getData API
• Writing q code
• SQL code

• Virtual queries

• Click Execute to generate results to the lower panel, as shown in the following screenshot.

  
  

  Results are described here.

• Click Apply to add data to the component. The following screenshot shows data displayed in a Data Grid component.

  
  

Subscription

The subscription type specifies whether the query subscribes to the database in one of the following methods:

• Static
• Polling

These settings are not relevant to the streaming query method.

These options, illustrated below, along with the Auto-execute and Force Reset are displayed at the bottom of the data source configuration screen.

Static

A static subscription involves a single request for data when you run the database query.

Polling

A polling subscription involves a client-side poll of the database when you execute the database query. When this is selected there are 2 parameters to be set as described in the following table:

option	effect
Interval	Set the time between each poll request (in seconds)
Key	Select which data source column to define subscription handling; for example, by column in situ, or by time for a streaming update.

Auto-execute

The Auto-execute option controls whether the query runs when there is a parameter change.

• When this is checked, the query runs whenever there is a parameter change or on load if data mapping is used. This is the default option.
• When this is unchecked, parameter changes don't run the query unless its associated with a component, e.g. a data grid or as an action tied to a button.

Force Reset

The Force Reset option specifies what happens to the existing dataset on each update.

• When this is checked, the existing dataset is cleared, on each update from the database, regardless of whether a parameter has changed or not. This is the default option.
• When this is unchecked, updates from the database merge with the existing dataset, unless a parameter is changed in which case the existing dataset is cleared.

Results

Once you have added a data source to a component as described here you click Execute. The results of the query are displayed in the main Results tab, at the bottom of the screen, with additional information in the following tabs:

• Mapping
• Input
• Raw output

Mapping

The Mapping tab takes a Value from a column, Key, and maps it to a View State as shown here.

Additional mapping actions can be added with by clicking the + icon.

Click the reset icon to create a map of values for all available keys.

Input

The Input tab shows the raw output of the query as shown in the following example.

{"table":"weather","startTS":"2022-12-05T00:00:00.000000000,"endTS":"2022-12-05T23:59:00.000000000"}

Raw output

The Raw Output tab shows the raw output of the results. This includes kdb+ type information.

{"primaryKey":"_rowIndex","columns":{"collection":[{"id":"timestamp","index":0,"kdbType":12},{"id":"sensor","index":1,"kdbType":11},{"id":"airtemp","index":2,"kdbType":9},{"id":"name","index":3,"kdbType":11},{"id":"borough","index":4,"kdbType":11},{"id":"longitude","index":5,"kdbType":9},{"id":"latitude","index":6,"kdbType":9},{"id":"color","index":7,"kdbType":11}],"reset":[{"id":"timestamp","index":0,"kdbType":12}

View states

View states are used to store dynamic values and states that can be used by components and queries. They can be used to store user preferences or pass values into queries.

The following section describe how to use view states in the data editor.

Using view states in data editor

In the code view of the data editor, view states are used to add variable inputs; for example, from a drop down, date picker or data form component.

To create a view state in the data editor:

1. Click on the generate view state icon in the relevant field of the data editor.
2. Click New to add a new view state. The following screen shot shows a Select View State dialog with properties that must be configured.

Hidden eyes

View states can also be assigned to properties where the generate view state icon is hidden; such properties will reveal the icon on rollover.

The following tabs provide examples of using view states for sql, q and virtual query methods.

SQLqVirtual

You can map view states with {{}}; for example:

select * from mytable where datavariable = {{viewstate}}

The following screenshot shows an example of adding a viewstate to an SQL query.

The following screenshot shows a mapped view state.

You can map view states as a q function; for example:

{[viewstate] select from mytable where datavariable = viewstate}

The following screenshot shows an example of adding a view state to a q query.

You can map view states with a Javascript function; for example:

function (source, selectedName, callback) {
var filtered = _.clone(source);
filtered.rows = source.rows.filter(r => r.name === selectedName).map(r => _.cloneDeep(r));
callback(filtered);
}

The following screenshot shows an example of adding a view state to a virtual query.

For further information about view states see:

• Selected Values
• View State Routing
• Component linking

Actions

An action is a common property set that you can use to configure a view state, run a query, or open an URL. For further information on actions see here.

Highlight rules

You can configure highlight rules, a common property utilizing color and/or icon markers, to notify users of value changes. Highlight rules are best used with real-time streaming, or polling data. For further information on highlight rules see here.

Further reading

• Views overview

• Quickstart guide to building Views

• Guided walkthrough on setting up Views

• Guided walkthrough on adding a Map component to a View

• Full guide to KX Dashboards