Power BI ビジュアルの階層 ID フィルター API
階層 ID フィルター API を使用すると、マトリックス DataView マッピングを使用するビジュアルで、階層構造を使用するデータ ポイントに基づいて複数のフィールドのデータを一度にフィルター処理できます。
この API は、次のようなシナリオで役立ちます。
- データ ポイントに基づく階層のフィルター処理
- キーでグループ化されたセマンティック モデルを使用するカスタム ビジュアル
Note
階層 ID フィルター API は、API バージョン 5.9.0 から入手できます
そのフィルター インターフェイスは次のコードで示すとおりです。
interface IHierarchyIdentityFilter<IdentityType> extends IFilter {
target: IHierarchyIdentityFilterTarget;
hierarchyData: IHierarchyIdentityFilterNode<IdentityType>[];
}
$schema:
https://powerbi.com/product/schema#hierarchyIdentity(IFilter から継承)filterType: FilterType.HierarchyIdentity (IFilter から継承)
target: クエリ内の関連する列の配列。 現在サポートされているロールは 1 つだけです。そのため、target は必須ではなく、空にする必要があります。
hierarchyData: 階層ツリー内の選択された項目と選択されていない項目。各
IHierarchyIdentityFilterNode<IdentityType>は単一の値の選択を表します。
type IHierarchyIdentityFilterTarget = IQueryNameTarget[]
interface IQueryNameTarget {
queryName: string;
}
- queryName: クエリ内のソース列のクエリ名。
DataViewMetadataColumnから取得されます
interface IHierarchyIdentityFilterNode<IdentityType> {
identity: IdentityType;
children?: IHierarchyIdentityFilterNode<IdentityType>[];
operator: HierarchyFilterNodeOperators;
}
identity: DataView のノード ID。
IdentityTypeはCustomVisualOpaqueIdentityである必要がありますchildren: 現在の選択に関連するノードの子の一覧
operator: ツリー内の単一オブジェクトの演算子。 演算子には、次の 3 つのオプションのいずれかを指定できます。
type HierarchyFilterNodeOperators = "Selected" | "NotSelected" | "Inherited";Selected: 値が明示的に選択されています。
NotSelected: 値が明示的に選択されていません。
Inherited: 値の選択は、階層内の親の値、またはルート値の場合は既定値に従います。
階層 ID フィルターを定義するときは、次のルールに留意してください。
- DataView から ID を取得します。
- 各 identity パスは、DataView 内の有効なパスである必要があります。
- すべてのリーフには、Selected または NotSelected の演算子が必要です。
- ID を比較するには、
ICustomVisualsOpaqueUtils.compareCustomVisualOpaqueIdentities関数を使用します。 - ID は、フィールドの変更 (フィールドの追加または削除など) に応じて変更される可能性があります。 Power BI は、更新された ID を既存の filter.hierarchyData に割り当てます。
階層 ID フィルター API の使用方法
次のコードは、カスタム ビジュアルで階層 ID フィルター API を使用する方法の例です。
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();
フィルターを適用するには、applyJsonFilter API 呼び出しを使用します。
this.host.applyJsonFilter(filter, "general", "filter", action);
アクティブな JSON フィルターを復元するには、"VisualUpdateOptions" にある jsonFilters プロパティを使用します。
export interface VisualUpdateOptions extends extensibility.VisualUpdateOptions {
//...
jsonFilters?: IFilter[];
}
階層関連フィールドの検証 (省略可能)
HierarchyIdnetity フィルターは、階層的に関連しているフィールドでのみサポートされます。 既定では、Power BI では、フィールドが階層的に関連しているかどうかは検証されません。
階層的に関連する検証をアクティブにするには、capabilities.json ファイル内の関連するロール条件に "areHierarchicallyRelated" プロパティを追加します。
"dataViewMappings": [
{
"conditions": [
{
"Rows": {
"min": 1,
"areHierarchicallyRelated": true <------ NEW ------>
},
"Value": {
"min": 0
}
}
],
...
}
]
次の条件が満たされる場合、フィールドは階層的に関連しています。
含まれるリレーションシップ エッジが、多対多のカーディナリティでも
ConceptualNavigationBehavior.Weakでもない。フィルター内のすべてのフィールドがパスに存在する。
パス内のすべてのリレーションシップが、同じ方向または双方向である。
リレーションシップの方向が、1 対多または双方向のカーディナリティと一致する。
階層リレーションシップの例
たとえば、次のようなエンティティのリレーションシップがあるとします。
- A、B は階層的に関連している: 真
- B、C は階層的に関連している: 真
- B、C は階層的に関連している: 真
- A、C、E は階層的に関連している: 真 (A --> E --> C)
- A、B、E は階層的に関連している: 真 (B --> A --> E)
- A、B、C、E は階層的に関連している: 真 (B --> A --> E --> C)
- A、B、C、D は階層的に関連している: 偽 (ルール #3 に違反)
- C、D は階層的に関連している: 真
- B、C、D は階層的に関連している: 偽 (ルール #3 に違反)
- A、C、D、E は階層的に関連している: 偽 (ルール #3 に違反)
Note
これらの検証が有効で、フィールドが階層的に関連していない場合、ビジュアルはレンダリングされず、エラー メッセージが表示されます。
これらの検証が無効で、階層的に関連していないフィールドに関連するノードを含むフィルターがフィルター ビジュアルに適用されている場合、メジャーの使用中に他のビジュアルが正しくレンダリングされない可能性があります。
新しい選択後に階層データ ツリーを更新するコードの例
次のコードは、新しい選択後に hierarchyData ツリーを更新する方法を示しています。
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();
}
考慮事項と制限事項
このフィルターは、マトリックス dataView マッピングでのみサポートされます。
ビジュアルには、データのグループ化ロールを 1 つだけ含める必要があります。
階層 ID フィルターの種類を使用するビジュアルでは、この種類のフィルターを 1 つだけ適用する必要があります。