Partilhar via

A identidade hierárquica filtra a API nos visuais do Power BI

  • Artigo

A API de filtro de Identidade de Hierarquia permite que elementos visuais que usam o Mapeamento de DataView de Matriz filtrem dados em vários campos de cada vez com base em pontos de dados que usam uma estrutura hierárquica.

Essa API é útil nos seguintes cenários:

  • Hierarquias de filtragem com base em pontos de dados
  • Visuais personalizados que usam modelos semânticos com grupo em teclas

Nota

A API de filtro de identidade de hierarquia está disponível na API versão 5.9.0

A interface do filtro é mostrada no código a seguir:

interface IHierarchyIdentityFilter<IdentityType> extends IFilter {
    target: IHierarchyIdentityFilterTarget;
    hierarchyData: IHierarchyIdentityFilterNode<IdentityType>[];
}

  • $schema: https://powerbi.com/product/schema#hierarchyIdentity (herdado do IFilter)

  • filterType: FilterType.HierarchyIdentity (herdado do IFilter)

  • target: Matriz de colunas relevantes na consulta. Atualmente, apenas uma única função é suportada; portanto, o destino não é necessário e deve estar vazio.

  • hierarchyData: os itens selecionados e não selecionados em uma árvore de hierarquia onde cada IHierarchyIdentityFilterNode<IdentityType> um representa uma única seleção de valor.

type IHierarchyIdentityFilterTarget = IQueryNameTarget[]

interface IQueryNameTarget {
    queryName: string;
}
  • queryName: nome da consulta da coluna de origem na consulta. Vem do DataViewMetadataColumn
interface IHierarchyIdentityFilterNode<IdentityType> {
    identity: IdentityType;
    children?: IHierarchyIdentityFilterNode<IdentityType>[];
    operator: HierarchyFilterNodeOperators;
}

  • identity: A identidade do nó em DataView. O IdentityType Deve ser CustomVisualOpaqueIdentity

  • crianças: Lista de crianças do nó relevantes para a seleção atual

  • operador: O operador para objetos únicos na árvore. O operador pode ser uma das seguintes três opções:

    type HierarchyFilterNodeOperators = "Selected" | "NotSelected" | "Inherited";

    • Selecionado: o valor é explicitamente selecionado.

    • NotSelected: valor não está explicitamente selecionado.

    • Herdados: a seleção de valor é de acordo com o valor pai na hierarquia, ou padrão se for o valor raiz.

Tenha em mente as seguintes regras ao definir seu filtro de identidade hierárquica:

  • Pegue as identidades do DataView.
  • Cada caminho de identidade deve ser um caminho válido no DataView.
  • Cada folha deve ter um operador de Selected ou NotSelected.
  • Para comparar identidades, use a ICustomVisualsOpaqueUtils.compareCustomVisualOpaqueIdentities função.
  • As identidades podem mudar após alterações de campos (por exemplo, adicionar ou remover campos). O Power BI atribui as identidades atualizadas ao filter.hierarchyData existente.

Como usar a API de filtro de identidade Hierarchy

O código a seguir é um exemplo de como usar a API de filtro de identidade de hierarquia em um visual personalizado:

import { IHierarchyIdentityFilterTarget, IHierarchyIdentityFilterNode, HierarchyIdentityFilter } from "powerbi-models"

const target: IHierarchyIdentityFilterTarget = [];

const hierarchyData: IHierarchyIdentityFilterNode<CustomVisualOpaqueIdentity>[] = [
    {
        identity: {...},
        operator: "Selected",
        children: [
            {
                identity: {...},
                operator: "NotSelected"
            }
        ]
    },
    {
        identity: {...},
        operator: "Inherited",
        children: [
            {
                identity: {...},
                operator: "Selected"
            }
        ]
    }
];

const filter = new HierarchyIdentityFilter(target, hierarchyData).toJSON();

Para aplicar o filtro, use a chamada de applyJsonFilter API:

this.host.applyJsonFilter(filter, "general", "filter", action);

Para restaurar o filtro JSON ativo, use a jsonFilters propriedade encontrada em "VisualUpdateOptions":

export interface VisualUpdateOptions extends extensibility.VisualUpdateOptions {
   //...
   jsonFilters?: IFilter[];
}

O HierarchyIdnetity filtro é suportado apenas para campos hierarquicamente relacionados. Por padrão, o Power BI não valida se os campos estiverem hierarquicamente relacionados.

Para ativar a validação hierarquicamente relacionada, adicione a propriedade 'areHierarchicallyRelated' à condição de função relevante no arquivo capabilities.json:

"dataViewMappings": [
    {
         "conditions": [
             {
                  "Rows": {
                      "min": 1,
                      "areHierarchicallyRelated": true <------ NEW ------>
                  },
                  "Value": {
                  "min": 0
                  }
            }
        ],
        ...
    }
]

Os campos estão hierarquicamente relacionados se as seguintes condições forem atendidas:

  • Nenhuma borda de relacionamento incluída é muitas para muitas cardinalidade, nem ConceptualNavigationBehavior.Weak.

  • Todos os campos no filtro existem no caminho.

  • Cada relação no caminho tem a mesma direção ou bidirecional.

  • A direção do relacionamento corresponde à cardinalidade de um para muitos ou bidirecional.

Exemplo de relações hierárquicas

Por exemplo, dada a seguinte relação de entidade:

Diagrama mostrando a natureza bidirecional do filtro.

  • A, B estão hierarquicamente relacionados: true
  • B, C estão hierarquicamente relacionados: verdadeiro
  • A, B, C estão hierarquicamente relacionados: true
  • A, C, E estão hierarquicamente relacionados: true (A --> E --> C)
  • A, B, E estão hierarquicamente relacionados: true (B --> A --> E)
  • A, B, C, E estão hierarquicamente relacionados: true (B --> A --> E --> C)
  • A, B, C, D estão hierarquicamente relacionados: falso (regra #3 violada)
  • C, D estão hierarquicamente relacionados: true
  • B, C, D estão hierarquicamente relacionados: falso (regra #3 violada)
  • A, C, D, E estão hierarquicamente relacionados: falso (regra #3 violada)

Nota

  • Quando essas validações estiverem habilitadas e os campos não estiverem hierarquicamente relacionados, o visual não será renderizado e uma mensagem de erro será exibida:

    Captura de ecrã visual com validações ativadas ao falhar ao carregar porque os campos não estão hierarquicamente relacionados. A mensagem de erro diz

    Captura de ecrã da mensagem de erro quando as validações estão ativadas e os campos não estão hierarquicamente relacionados. A mensagem diz

  • Quando essas validações são desabilitadas e o filtro visual aplica um filtro que contém nós relacionados a campos não hierarquicamente relacionados, outros elementos visuais podem não renderizar corretamente quando as medidas estão em uso:

    Captura de ecrã visual com validações desativadas que não conseguem carregar porque os campos não estão hierarquicamente relacionados. A mensagem de erro diz

    Captura de ecrã da mensagem de erro quando as validações estão desativadas e os campos não estão hierarquicamente relacionados. A mensagem diz

Exemplo de código para atualizar a árvore de dados da hierarquia após nova seleção

O código a seguir mostra como atualizar a hierarchyData árvore após uma nova seleção:

type CompareIdentitiesFunc = (id1: CustomVisualOpaqueIdentity, id2: CustomVisualOpaqueIdentity) => boolean;
/**
* Updates the filter tree following a new node selection.
* Prunes irrelevant branches after node insertion/removal if necessary.
* @param path Identities path to the selected node.
* @param treeNodes Array of IHierarchyIdentityFilterNode representing a valid filter tree.
* @param compareIdentities Compare function for CustomVisualOpaqueIdentity to determine equality. Pass the ICustomVisualsOpaqueUtils.compareCustomVisualOpaqueIdentities function.
* @returns A valid filter tree after the update
*/

function updateFilterTreeOnNodeSelection(
   path: CustomVisualOpaqueIdentity[],
   treeNodes: IHierarchyIdentityFilterNode<CustomVisualOpaqueIdentity>[],
   compareIdentities: CompareIdentitiesFunc
): IHierarchyIdentityFilterNode<CustomVisualOpaqueIdentity>[] {
    if (!path) return treeNodes;
    const root: IHierarchyIdentityFilterNode<CustomVisualOpaqueIdentity> = {
        identity: null,
        children: treeNodes || [],
        operator: 'Inherited',
    };
    let currentNodesLevel = root.children;
    let isClosestSelectedParentSelected = root.operator === 'Selected';
    let parents: { node: IHierarchyIdentityFilterNode<CustomVisualOpaqueIdentity>, index: number }[] = [{ node: root, index: -1 }];
    let shouldFixTree = false;
    path.forEach((identity, level) => {
        const index = currentNodesLevel.findIndex((node) => compareIdentities(node.identity, identity));
        const isLastNodeInPath = level === path.length - 1
        if (index === -1) {
           const newNode: IHierarchyIdentityFilterNode<CustomVisualOpaqueIdentity> = {
               identity,
               children: [],
               operator: isLastNodeInPath ? (isClosestSelectedParentSelected ? 'NotSelected' : 'Selected') : 'Inherited',
           };
           currentNodesLevel.push(newNode);
           currentNodesLevel = newNode.children;
           if (newNode.operator !== 'Inherited') {
              isClosestSelectedParentSelected = newNode.operator === 'Selected';
           }
        } else {
            const currentNode = currentNodesLevel[index];
            if (isLastNodeInPath) {
               const partial = currentNode.children && currentNode.children.length;
               if (partial) {
                  /**
                   * The selected node has subtree.
                   * Therefore, selecting this node should lead to one of the following scenarios:
                   * 1. The node should have Selected operator and its subtree should be pruned.
                   * 2. The node and its subtree should be pruned form the tree and the tree should be fixed.
                   */
                   // The subtree should be always pruned.
                   currentNode.children = [];
                   if (currentNode.operator === 'NotSelected' || (currentNode.operator === 'Inherited' && isClosestSelectedParentSelected )) {
                      /**
                       * 1. The selected node has NotSelected operator.
                       * 2. The selected node has Inherited operator, and its parent has Slected operator.
                       * In both cases the node should be pruned from the tree and the tree shoud be fixed.
                       */
                      currentNode.operator = 'Inherited'; // to ensure it will be pruned
                      parents.push({ node: currentNode, index });
                      shouldFixTree = true;
                  } else {
                     /**
                      * 1. The selected node has Selected operator.
                      * 2. The selected node has Inherited operator, but its parent doesn't have Selected operator.
                      * In both cases the node should stay with Selected operator pruned from the tree and the tree should be fixed.
                      * Note that, node with Selected oprator and parent with Selector operator is not valid state.
                      */
                      currentNode.operator = 'Selected';
                  }
              } else {
                  // Leaf node. The node should be pruned from the tree and the tree should be fixed.
                  currentNode.operator = 'Inherited'; // to ensure it will be pruned
                  parents.push({ node: currentNode, index });
                  shouldFixTree = true;
                 }
             } else {
                 // If it's not the last noded in path we just continue traversing the tree
                 currentNode.children = currentNode.children || [];
                 currentNodesLevel = currentNode.children
                 if (currentNode.operator !== 'Inherited') {
                     isClosestSelectedParentSelected = currentNode.operator === 'Selected';
                     // We only care about the closet parent with Selected/NotSelected operator and its children
                     parents = [];
                  }
                  parents.push({ node: currentNode, index });
                }
           }
    });
    // Prune brnaches with Inherited leaf
    if (shouldFixTree) {
       for (let i = parents.length - 1; i >= 1; i--) {
           // Normalize to empty array
           parents[i].node.children = parents[i].node.children || [];
           if (!parents[i].node.children.length && (parents[i].node.operator === 'Inherited')) {
              // Remove the node from its parent children array
              removeElement(parents[i - 1].node.children, parents[i].index);
           } else {
               // Node has children or Selected/NotSelected operator
               break;
         }
      }
   }
   return root.children;
}
/**
* Removes an element from the array without preserving order.
* @param arr - The array from which to remove the element.
* @param index - The index of the element to be removed.
*/
function removeElement(arr: any[], index: number): void {
    if (!arr || !arr.length || index < 0 || index >= arr.length) return;
    arr[index] = arr[arr.length - 1];
    arr.pop();
}

Considerações e limitações

  • Este filtro é suportado apenas para mapeamento de dataView de matriz.

  • O visual deve conter apenas uma função de dados de agrupamento.

  • Um visual que usa o tipo de filtro de identidade Hierarchy deve aplicar apenas um único filtro desse tipo.