Overview

A widget is one query plus one visualisation. A dashboard is a saved arrangement of widgets. You build a widget in the Query Builder, save it, and then place it on a dashboard.

You can write a widget's query three ways: by picking fields on the Query tab, by writing it on the SQL tab, or by describing it to ZIN on the AI tab. All three feed the same live preview on the right of the screen.

This guide walks through every part of the Query Builder and then shows how to put the finished widget on a dashboard. For chart types and colours in depth, see How to Customize Widget Appearance & Colors in Interno. For everything about dashboards themselves (templates, filters, export and import), see How to Manage Dashboards (Templates, Filters, Export/Import).

Prerequisites

• At least one integration connected with data collected. Without data, the builder sends you to Admin → Integrations.
• defence:widget:create to open the Query Builder for a widget. Without it the builder shows an unauthorised screen.
• defence:dashboard:create to create a dashboard and defence:dashboard:update to arrange one.

Opening the Query Builder

There are three ways in. All open the same screen.

The screen has two panels. Query Builder on the left holds three tabs: Query, SQL and AI. Visualization on the right shows the result, with Reset and Create Widget buttons above it.

Switching between the Query, SQL and AI tabs clears what you have built on the current tab. Finish on one tab, or copy your query first.

Method 1: The Query Tab (No SQL Needed)

Navigation: Sidebar → Dashboard → Create → Widget → Query tab

1. In Source, choose the table your data lives in. This field is required. Hover over an option to see its readable name and, where it differs, the source it comes from.
2. To bring in a related table, click Join Data. Two more controls appear: a join type selector and Include related data. See Joining related tables below.
3. In Select, pick the fields you want in the result. See Picking fields below.
4. Click any of the buttons under the fields to add an optional block: Filter, Aggregation, Group, Order or Limit. Click the same button again to remove the block. Each block is described in the table below.
5. Click Preview. The result appears in the Visualization panel.

You must select at least one field or one aggregation. Otherwise Interno shows Unable to Proceed, please select at least one column or aggregation.

Changing the Source resets the rest of the query, because the fields belong to the table.

Picking fields

Every field picker in the builder shows each field with a readable label (for example Last Logon Time), the underlying TABLE.COLUMN name beneath it, and a small chip showing its type. Use the Group: toggle at the top of the list to group the fields by theme or by table. Type in the box to search.

The themes are Timestamps, Risk, Network, Identity, Identifiers, Status and Other. Interno assigns a theme from the words in the field's name.

The optional blocks

To remove a row from a block, click the delete icon at the end of the last row.

Filter operators

The operators offered depend on the type of the field.

Aggregations

The Apply Count hint

If you select only category-style fields and no aggregation, a chart would repeat the same values row after row. Interno offers a hint: You picked category fields. Add a Count so the chart shows totals per value instead of repeated rows.

• Click Apply Count to add a count and a matching group-by on the first field you selected.
• Click Dismiss to hide the hint.

Joining related tables

1. Choose a Source first. Join Data is greyed out until you do.
2. Click Join Data.
3. In the join type selector next to it, choose INNER, LEFT or RIGHT. INNER is the default.
4. In Include related data, tick the related tables to include. Only tables that Interno knows how to link to your source are listed.

The fields of the joined tables become available in every field picker. If you later untick a table, any fields, filters, groupings, orderings and aggregations that used it are removed from the query, and the rest is left as it was.

The Data Dictionary

The Data Dictionary is a searchable list of every field Interno holds for your organisation, across all tables. Use it when you know what you are looking for but not which table it is in.

Navigation: Sidebar → Dashboard → Create → Widget → Query tab → Browse data dictionary

1. Click Browse data dictionary (under the Select field). The Data Dictionary panel slides in.
2. Type in Search fields by name…. The search matches the readable label and the underlying TABLE.COLUMN name.
3. Use the Group: toggle to group the list by theme or by table. Each group heading shows how many fields it holds.
4. Read the row for a field: its readable label, its type chip, its TABLE.COLUMN name and its description. A field without a written description shows No description yet.
5. Click + Insert on a field. The button changes to Added.
6. Close the panel with the close icon at the top.

What + Insert does depends on your query so far:

If the search finds nothing, the panel reads No fields match "…". Try a field or table name.

For how tables and system fields are organised, see Interno Data Sources & Fields (Data Dictionary).

Method 2: The SQL Tab

Navigation: Sidebar → Dashboard → Create → Widget → SQL tab

1. Click the SQL tab.
2. Write your query in the SQL Query editor. The editor suggests table and column names as you type.
3. To look up names, click View Schema. See The Table Relationship panel below. Click Close Schema to bring the preview back.
4. Click Preview, or press Ctrl + Enter (⌘ + Enter on a Mac), to run the query.

Rules for the SQL you write:

• Write a SELECT query. Statements that change structure or permissions (CREATE, DROP, ALTER, TRUNCATE, GRANT, REVOKE) are refused.
• Use table names on their own, without a schema prefix. Interno points the query at your organisation's own data for you.
• The query is required and is limited to 4,096 words.

The Table Relationship panel

View Schema replaces the preview with the Table Relationship panel.

1. Choose a table in the selector (Please select a source.).
2. The panel lists the table's columns and the tables it is related to.
3. Click the copy icon next to the table name (Copy table name) or next to a column (Copy column name) to copy it for pasting into your query.
4. Click the eye icon next to a column (View Distinct Values) to see the different values that column holds. Use Search Distinct Values to narrow the list, and the copy icon (Copy column value) to copy one.

Method 3: The AI Tab

The AI tab is offered when you are building a widget. It is not shown when you build an alert or an evidence query.

Navigation: Sidebar → Dashboard → Create → Widget → AI tab

1. Click the AI tab.
2. In Prompt, describe what you want, for example show the ten endpoints with the most open vulnerabilities. The prompt is required and is limited to 4,096 words.
3. Click Preview. ZIN writes the query, shows it under Generated Query: and runs it. The result appears in the Visualization panel.
4. To reuse the query elsewhere, click the copy icon at the end of it (Copy query). Interno confirms with Query copied to clipboard.
5. If the result is close but not right, change the prompt and click Preview again.

The AI tab produces one query per prompt. To hand-edit a generated query, copy it, switch to the SQL tab and paste it there.

Choosing the Visualisation

When the query returns rows, the Visualization panel shows them as a table and offers the display controls above the result.

A new query starts as a table, with the first column as the x-axis and the second as the y-axis. If the chart type you choose does not fit the fields you selected, the preview shows why, for example Pie chart requires exactly 1 Y-axis metric.

The full list of chart types, what each needs, and how to change colours are covered in How to Customize Widget Appearance & Colors in Interno.

Saving the Widget

1. Click Create Widget above the preview. The button reads Checking... while Interno looks for an existing widget with a similar query.
2. If a similar widget exists, the Duplicate Widget Detected window lists the matching widgets with who created them and when. Click Continue Anyway to carry on, or cancel and use the existing widget instead.
3. The Create widget form opens. Fill in the fields in the table below.
4. Click Create. The button reads Creating... while it saves.

Interno confirms that the widget was created and takes you to the Widget tab of the Query Library, where the new widget is at the top of the list.

Reset, next to Create Widget, clears the query and the preview so you can start again.

A widget is not placed on any dashboard when you save it. Add it to a dashboard as described below.

Linking a Widget to a Detail Widget

A Linked Widget connects a summary widget to a second widget that holds the detail behind it, for example a count card linked to the full table.

1. In the Create widget form (or the Update widget form when editing), open Linked Widget.
2. Search for the detail widget by name and select it. A widget cannot be linked to itself.
3. Save the widget.

On a dashboard and in the Query Library preview, a widget that has a link shows a View link icon in its toolbar. Clicking it opens a Linked Widget page showing the detail widget on its own.

To let users click a bar or a slice and see the rows behind that one value, set up a drilldown instead. See How to Use the Query Library.

Editing an Existing Widget

1. Open the widget for editing in one of two ways: in the Query Library, open the widget's row menu and choose Edit, then Confirm Edit; or on a dashboard in edit mode, click the edit icon on the widget card (Navigate to edit widget).
2. The Query Builder opens on the widget's query as SQL. The Query, SQL and AI tabs are not shown when editing; every saved widget is edited as SQL, whichever way it was first built.
3. Change the query and click Preview, or change only the visualisation controls.
4. Click Update Widget, adjust the Title, Description or Linked Widget if needed, and click Update.

Interno confirms with Widget updated successfully and returns you to where you came from. The change shows on every dashboard that uses the widget.

The standard widgets that ship with Interno cannot be edited or deleted.

Understanding Query Errors

When a preview fails, a red warning icon appears next to the Preview button. Hover over it to read the reason. Saving a widget runs the same checks, so a query that cannot run is refused before it is saved.

Building a Dashboard

Navigation: Sidebar → Dashboard → Create → Dashboard

1. In Title, type a name (required).
2. In Description, optionally describe the dashboard (up to 500 words).
3. Under Dashboard Type, choose Private Dashboard (only you see it) or Public Dashboard (everyone in your organisation who can view dashboards sees it).
4. On the right, click the My Widgets tab and select the widgets you built. Use Search my widgets... to find them. You can also select ready-made widgets on the Template Widgets tab.
5. Click Create dashboard.

Interno opens the new dashboard in edit mode.

Arranging the Grid

Navigation: Sidebar → Dashboard → open the dashboard → ⋮ → Edit Dashboard

Things to know:

• Moving and resizing work only on a wide browser window. On a narrow window edit mode shows Widen the window to rearrange widgets.
• Layout changes are saved only when you click Save Changes. If you try to leave with unsaved changes, an Unsaved changes window lets you choose Keep editing or Discard changes.
• Removing a widget from a dashboard does not delete the widget.

Each step is described in full in How to Manage Dashboards (Templates, Filters, Export/Import).

Working with a Widget on a Dashboard

In view mode, each chart widget has a small toolbar and responds to clicks.

Table widgets have their own toolbar: Search, Filter, Visibility (show or hide columns) and Export data, which downloads the rows as a CSV file.

Troubleshooting

The Query Builder shows an unauthorised screen → Building a widget needs defence:widget:create. Ask your administrator.

"Source required" → Choose a table in Source before clicking Preview.

"Unable to Proceed, please select at least one column or aggregation" → Pick at least one field in Select, or add an aggregation.

The preview says "No data found!" → The query ran but matched nothing. Loosen the filters, and check that the integration feeding the table has completed a scan.

The preview says "No visualization available!" → Nothing has been previewed yet, or the last preview failed. Build a query and click Preview, and hover over the red warning icon if one is shown.

A red warning icon appears next to Preview → Hover over it for the reason. See the query errors section above.

A table I expected is not in Source → Tables appear once the matching integration has collected data. See How to Configure Connectors/Integrations.

The table I want to join is not under Include related data → Only tables with a known link to your source can be joined. Choose the other table as the Source instead, or write the join on the SQL tab.

Count is not offered for the field I want → On the Query tab, count is offered for identifier fields and the host name. Use Apply Count when Interno offers it, or write the query on the SQL tab.

My chart repeats the same value over and over → You selected category fields without an aggregation. Click Apply Count, or add a Count aggregation and a Group by.

I only ever get 100 rows → Without a Limit block the result is capped at 100 rows. Click Limit and enter a higher number.

The AI tab produced nothing → ZIN could not turn the prompt into a query. Name the tool, the metric and the grouping you want, and try again.

The AI tab is missing → It is offered only when building a widget, and not when editing an existing one.

My work vanished when I changed tab → Switching between Query, SQL and AI clears the current tab. Rebuild the query on the tab you want to finish on.

"Duplicate Widget Detected" → A widget with a similar query already exists. Use the existing one, or click Continue Anyway to save yours as well.

"Description required" → A widget must have a description before it can be saved.

I saved a widget but it is not on my dashboard → Saving a widget adds it to the Query Library only. Open the dashboard in edit mode and add it with the Widgets: selector.

I changed a chart with Change Preview and it went back → Change Preview is temporary. To change a widget permanently, edit it in the Query Builder and click Update Widget.

Need more help? Contact support@zeron.one