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

Visual Dataset Binding

Visual Dataset Binding

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.

Any data you add to the visual's Values data role is automatically bound to an internal dataset named dataset in the Vega or Vega-Lite view. This will update dynamically as you add or remove columns and measures, or the number of rows in the dataset changes (e.g. filter context).

Linking Visual Data in A Specification

Even though this is passed through from Power BI, a specification needs to contain a reference to the named dataset, otherwise the values cannot be encoded when the specification is parsed. You should always ensure that a specification contains the following for this to work:

Vega-Lite
{
...
"data": { "name": "dataset" }
...
}
Vega
{
...
"data": [
{ "name": "dataset" }
]
...
}

The visual's starter templates all follow this approach, so if in doubt, create a new specification using the [empty] template as a boilerpate.

Grain / Row Context

Internally, the visual handles its dataset in much the same way as a core table, i.e. the number of rows in the dataset is equivalent to the combination of all unique values across all columns and measures added.

Let's say that we have the following data in our visual:

simple-data-table.png

If you're used to working with JSON, a representation similar to the following JSON output is patched into the specification when it is parsed:

{
"dataset": [
{ "City": "Auckland", "Mean Temperature": 14.62 }
{ "City": "Christchurch", "Mean Temperature": 9.49 }
{ "City": "Dunedin", "Mean Temperature": 6.83 }
{ "City": "Hamilton", "Mean Temperature": 13.27 }
{ "City": "Lower Hutt", "Mean Temperature": 12.12 }
{ "City": "North Shore", "Mean Temperature": 14.62 }
{ "City": "Tauranga", "Mean Temperature": 12.99 }
{ "City": "Waitakere", "Mean Temperature": 14.62 }
{ "City": "Wellington", "Mean Temperature": 12.12 }
]
}

Referencing Columns and Measures

Wherever you need to reference a column or a measure in your specification, you should use its display name from the Values rather than those from the data model as illustrated in the above section). If you rename or remove a column or measure, please remember to update your specification accordingly.

'Special Characters' in Column and Measure Names

You might use all kinds of characters in your data model when naming columns or measures. However, Vega and Vega-Lite (and JSON) have some specific considerations to make with certain characters in field binding and expressions, notably ., [, ], \ and ".

In these cases, Deneb will replace occurrences of these characters with an underscore (_) when they are passed into the visual dataset. By doing this, we avoid placing the onus on you, the author to remember how to escape them using the rules in the linked documentation above.

To further illustrate, let's assume we have this measure:

measure-with-dot.png

Using this in a specification's field encoding would need to look like this:

{
...
"x": {
"field": "$ Sales_Current",
"type": "quantitative"
}
...
}

It is recommended that if you're passing in measures or columns containing special characters and do not wish for this behavior to occur, then rename them in the Values data role so that they are not passed through to the dataset.

Augmenting Other Datasets

In the case of a Vega specification, you can potentially add further data objects to the array, but bear the following in mind:

  • At this stage, we're working towards the production of a visual that will ideally be certified in AppSource, and certified visuals are not permitted to bring in data or resources from external locations.

    • To this end, loading external files is not permitted in the visual.
    • It is envisaged that further down the line, this feature will be enabled, albeit in a separately published version of the visual that will not be eligible for certification (or, if the core visual cannot be certified, we'll just switch it on 😉)
  • As such, it is recommended that you regard the named "dataset" source as where all data for your specification should come from.

Considerations for Transforming Data

Both Vega and Vega-Lite support the concept of transforms, which ultimately mutate the data from its initial state. Whilst this approach may be necessary to produce particular types of visual, this changes the row context and some features may no longer be available (particularly those that leverage interactivity). Please refer to the pages in the Interactivity Features section for more details.

Data Row Limits

In order to try and keep performance usable for most cases, the visual caps the row count at 10,000 by default.

It is however possible to override this if you so wish, but the number of rows returned will be subject to resource limits and entirely up to Power BI. If you wish to override this, you can find the Data Limit Options menu in the properties pane:

data-limit-options-initial.png

Switching on the Override Row Limit property, will ask Power BI to load more rows into the dataset, in batches of 10,000, e.g.:

data-limit-override-enabled.png

Because there's a lot to consider when enabling this property, the Show Data Loading Notes property is enabled by default, and this is intended to provide creators or developers a bit more detail around the caveats around using this feature in a condensed space. Whist the information can probably be seen in the screenshot, the important details are listed here too:

  • Power BI will cause the visual's data to reload when:

    • You add or remove columns or measures from the Values data role.
    • The visual's filter context is changed.
    • Values in the properties pane are modified.
  • Most operations in the visual editor will not trigger this behavior, so with the exception of doing anything above, there should be minimal disruption in terms of Power BI reloading the dataset.

  • However editing a specification with a lot of data can usually have negative performance implications. Refer to the Performance Considerations page for further details on potential risks and mitigation approaches.

When you're sufficiently used to the behavior of this feature (or when ready to publish and you don't want your users to see them), you can turn off the Show Data Loading Notes property to de-clutter this:

data-loading-notes-off.png

Edit this page on GitHub