Share via

Configure data fields

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. The list will contain both hidden and visible fields.

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.

Set a data field's visibility

To control the visibility of data fields, use the setFieldHidden method on the visual. Only aggregated fields, measures, and visual calculations can be hidden or shown. This action is equivalent to toggling field visibility while in Visual Calculation Editing Mode.

setFieldHidden(dataRole: string, index: number, isHidden: boolean): 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 hide or unhide.
  • isHidden - Boolean value to determine where it should be hidden or not

For example:

await visual.setFieldHidden('Values', 0, /*isHidden*/ true);

Set a data field's format string

To format the displayed data from a particular field, call the setFieldFormatString method of the visual.

setFieldFormatString(dataRole: string, index: number, formatString: string): 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 set the format string
  • formatString - Expecting .NET format string

For example: If you want to every value in the field to have $ at beginning, do this:

await visual.setFieldFormatString('Values', 0, /*formatString*/ "$0.00");

Get a data field's format string

To retrieve the format string of a field, call the getFieldFormatString method of the visual.

getFieldFormatString(dataRole: string, index: number): Promise<string>

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 get the format string
let formatString = await visual.getFieldFormatString('Values', 0);

Get a data field's name

Every field in a visual has a unique name derived from its display name. This unique identifier is used to reference the field within DAX expressions when creating visual calculations. To retrieve this unique name, call the getDataFieldName method of the visual.

getDataFieldName(dataRole: string, index: number): Promise<string>

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 get the field name
let dataFieldName = await visual.getDataFieldName('Values', 0);
let visualCalcDax = `RUNNINGSUM([${dataFieldName}])`;

Related content

  • Last updated on