Configure data fields

  • Article

When you create a visualization, the visual is rendered according to the assigned data fields. This article shows how to use Power BI report authoring APIs to interact with data fields and assign them to data roles. To determine what data roles a visual has, use the getCapabilities method.

Add a data field

To add a data field to a visual data role, call the addDataField method of the visual.

addDataField(dataRole: string, dataField: models.IBaseTarget, index?: number): Promise<models.IError>

This method has the following variables:

  • dataRole - The name of the data role to which the data field should be assigned. The dataRole parameter is equivalent to the data role name property. To retrieve the available data roles and names, use the getCapabilities method.
  • dataField - The data field to add to the data role. The data field is a target object, which can be a column, column with aggregation, measure, hierarchy, or hierarchy with aggregation. For more information about targets, see Use targets to select which data field to act on.
  • index (optional) - The index at which the data field should be added. The default behavior is for the field to be added last.

For example:

const dataField = {
  $schema: "http://powerbi.com/product/schema#column",
  table: "Store",
  column: "Name"
};

await visual.addDataField('Category', dataField);

Get data fields

To get a list of the data fields that are defined in a data role, call the getDataFields method of the visual.

getDataFields(dataRole: string): Promise<models.IBaseTarget>

This method has the dataRole variable, which is the name of the data role from which to retrieve the data fields.

For example:

let dataField = await visual.getDataFields('Category');

Remove data fields

To remove a data field that's applied on a data role, call the removeDataField method of the visual.

removeDataField(dataRole: string, index: number): Promise<models.IError>

This method has the following parameters:

  • dataRole - The name of the target data role to which the data field is associated.
  • index - The index of the data field to delete.

For example:

await visual.removeDataField('Category', 2);

To get the index of the data field, you can use the index of the target in the getDataFields results array.

Next steps

Embed a report visual

Create a visual

Get the capabilities of a visual