Deneb - Declarative visualization in Power BI, using the Vega language

Creating from a Template (or: Let's Make A Vega-Lite Bar Chart)

Creating from a Template (or: Let's Make A Vega-Lite Bar Chart)

Deneb is currently in public preview and lots of things are still being actively developed. This site is under construction and the information in this page may be subject to frequent change, so please check often to ensure that you're up-to-date.

In the following pages, we'll create a simple bar chart, using the visual, some data, an inbuilt template and Vega-Lite. For reference, here's the finished product:

    Download this workbook

Sample Data

From the sample workbook, we'll use a single column and measure. Here's how they look as a table:

simple-data-table.png

Here, the [City] column represents a nominal category, and [Mean Temperature] is a simple measure that calculates the average temperature value for the given row context.

Adding the Visual

If you've added the visual to your report, you should see it in the Visualizations pane, eg.:

viz-added.png

You can then click the visual to add it to the report canvas, e.g.:

viz-landing.png

Adding the Data

We'll now add the [City] column and [Mean Temperature] measure to Deneb's Values data role, e.g.:

viz-needs-spec.png

The visual's output now changes to indicate that a specification is required. This is required to tell Vega-Lite (or Vega) how your visualization should be rendered.

Opening the Editor

We can now open the Visual Editor by selecting the visual header (...) and then Edit, e.g.:

opening-editor.png

This will display the Visual Editor in focus mode, and the Create New Specification dialog will be shown, e.g.:

create-new-spec.png

If you accidentally dismiss the dialog, or it doesn't show, you can bring it up by clicking on the New Specification button on the command bar, or using [Ctrl + Alt + N]

Selecting the Template

Using Vega or Vega-Lite requires a specification to be written using JSON. You can either select the [empty] template to begin editing with a bare-minimum specification with the dataset bound to it, or use a predefined template.

Let's choose the Simple Bar Chart template by clicking on it. Note that we now get some additional details about the template, as well as some required placeholders:

bar-chart-template-initial.png

Assigning Placeholders

This template expects two placeholders: one for the the category axis and another for the measure axis. As we've already added our data, we can see these are already available in the dropdown lists, e.g.:

category-placeholder.png

Note that Mean Temperature is disabled. This is because the placeholder specifies a column be added here. We'll choose City.

The visual only knows about columns or measures added to it, so you can add or swap out a column or measure if it's not the one you want and the dropdown list will update accordingly.

Next, we'll click on the Measure placeholder:

measure-placeholder.png

Similarly, as this placeholder specifies a measure, notice that City is disabled here. We'll choose Mean Temperature to complete our requirements.

Creating the Initial Specification

Now that all placeholders have been filled, the Create button is enabled:

create-button-enabled.png

We can click this and the visual specification will be present in the editor, e.g.:

created-from-template.png

Reviewing Generated Specification

In our editor's Specification tab, we'll now have the following Vega-Lite JSON specification:

{
"data": {
"name": "dataset"
},
"mark": {
"type": "bar",
"tooltip": true
},
"encoding": {
"y": {
"field": "City",
"type": "nominal"
},
"x": {
"field": "Mean Temperature",
"type": "quantitative"
}
}
}

Here, we can see that:

  • There's a data object, which has a mapping of "dataset".

    • This is required for the specification, instructs that our visual's dataset should be used and should be left as-is.
    • Refer to the Visual Dataset Binding page for more details on how this works.
  • We're using a bar mark for our data point and we're displaying a tooltip for this mark.

  • The encoding for the visual maps our data as follows:

    • City is mapped to the y-axis.
    • Mean Temperature is mapped to the x-axis.

This is a simple single view specification, so once you're comfortable with the syntax, you should be able to move onto layered, concatenated or faceted views in no time 😉

We also have some other stuff going on in the editor's Config tab, thanks to our template...

Reviewing Generated Config

In our editor's Config tab, we'll have the following Vega-Lite JSON configuration:

{
"autosize": {
"type": "fit",
"contains": "padding"
}
}

This is a nice feature of Vega-Lite that provides automatic sizing for simpler (single or layered) views, so has been included in this template by default.

You can extend the config significantly to customize many parts of your visual, so it's worth diving into the documentation for this when you're ready.

You can include your config in the specification JSON if you like at the top-level, but the intention here is to separate the cosmetic aspects of the visual away from its logical ones, so we have a separate tab in the editor for this for thos who wish to adopt this approach.

Tooltips

Our template enables tooltips by default, so we can hover over a data point in our visual and this will display a default tooltip, e.g.:

standard-tooltip.png

Super-Charging Tooltips

If we were to set up a tooltip page that included one of the columns from our visual, like this one (which displays the mean temperature over time, which is a bit more useful):

tooltip-page-setup.png

Then, the visual can resolve this, providing that you specify to use a report page tooltip instead of a default one, e.g.:

canvas-tooltip.png

Note that report page tooltips will only work if your data point hasn't been transformed or mutated from the row context passed-into your visual's dataset. In the cases where data points cannot be reconciled back to the data model, the visual will display a default tooltip instead. Please refer to the Interactivity Features or Tooltips pages for further details.

Adding Further Config

It's possible to make our visual look a bit more at home by adding or modifying its configuration, so let's select the Config tab and update this as follows (changes highlighted):

{
"autosize": {
"type": "fit",
"contains": "padding"
},
"view": {
"stroke": "transparent"
},
"font": "Segoe UI",
"bar": {
"color": "#CE6C47"
},
"axis": {
"domain": false,
"labelColor": "#605E5C",
"labelFontSize": 12,
"labelPadding": 5,
"ticks": false,
"tickCount": 5,
"titleFontSize": 14,
"titleFontWeight": "bold",
"titleColor": "#605E5C",
"gridDash": [1, 5],
"gridColor": "#605E5C"
}
}

We can apply our changes by clicking the Apply command, or pressing [ Ctrl + Enter ]:

apply-command.png

Note that the Auto-Apply command can be used to ensure changes are applied as you type rather than manually, although this isn't recommended for complex specifications or ones that use a large number of data points.

Once we've applied the changes, our visual updates as follows:

config-applied.png

Viewing the Finished Product

When you're finished, click on Back to report to bring you back out of focus mode and to the report canvas. Our visual will now be 'regular sized', thanks to the autosize configuration we applied earlier on:

regular-sized-bar.png

Where Next?

We've used one of the inbuilt templates to produce a simple example, and add some integration features in the form of tooltips, and customized its appearance using config. A simple visual like this is just the tip of the iceberg and the way ahead is quite broad and expansive.

The purpose of this site is to provide detail on how to make the visual work for you within Power BI, rather than repeating the wealth of great documentation that's already out there. To learn more about some of the additional things the visual can offer (or understand some of its limitations) then please continue to read on or use the menu to explore further.

If you're hungry for more examples or further inspiration, then a good place to start is Vega-Lite's own gallery, or even Vega's gallery.

Edit this page on GitHub