Using filter IBasicFilterWithKeys

[john_m_dixon]

There is a filter seemingly available called IBasicFilterWithKeys. The main documentation for the filters api here does not mention it at all. I did see a reference to it on this page documented in the middle of 2019, so I assume it's supported. However I'm unable to find any documentation that references the usage of this filter.

Using this filter requires an IFilterKeyTarget, which has an additional 'keys' property of type string[], but I am unsure what the key in this context is:

const target: IFilterKeyTarget = {
    table: source.queryName.substr(0, source.queryName.indexOf('.')),
    column: source.displayName,
    keys: ? // type here is string[]
}

The IBasicFilterWithKeys object also has an additional property called 'keyValues' of type string[][], and again I'm not sure what this key refers to:

let filter: IBasicFilterWithKeys = {
    target: target,
    $schema: "http://powerbi.com/product/schema#basic",
    values: ["myValue"], // is this property still relevant?
    keyValues: ?, // type here is string[][]
    filterType: 1,
    operator: "In",
}

The IBasicFilterWithKeys is an extension of the IBasicFilter with some additional properties. The code assumes that the schema for IBasicFilterWithKeys is the same as IBasicFilter, as well as the other properties like filter type and operator. The extension does some checking to ensure that there is a value in keyValues for every key in the IFilterKeyTarget.

The thing that is losing me is the context of what a "key" is, and how the api will act upon it when it receives this type of filter. I've tried using the ISelectionId key that is produced from ISelectionBuilder, as well as just the identity index of the value, but no luck on either of these. 

My (unconfirmed) assumption is that each value in a column has an identity value which corresponds to the identity index property of a selection. Describing the key for that value would be {"table.column":[{"identityIndex":1}]}[], i.e. what is generated by the selection builder. But I can't input these values in a way that works with IBasicFilterWithKeys.