Skip to content

Filtering and filters

Jump to bottom
Olena Orobei edited this page Jul 13, 2021 · 6 revisions

Filters are responsible for filtering data received from the loader.

List of content:

Filters

Available filters Description
base The base filter supports a complex configuration that allows filtering data by different fields with AND, OR, IS, IS NOT, IN, NOT IN conditions.

Base

Options Required Default Description
name false base Name of the filter
level false - To what level apply filter. For more details level explanation
conditions true - List of conditions. See conditions list and condition item

Example:

{ 
   "name": "base",
   "level": "crossreference",
   "conditions": [
      {
         "where": "organization",
         "condition": "not in",
         "value": ["organization-name-1", "organization-name-2"]
      }
   ]
}

Conditions list

List of conditions that will be applied to the data item. This property can be represented as a list of objects or arrays, depending on the use case. They applied one by one, starting from the most likely conditions to improve performance. If you use OR condition, it should be declared as a list of arrays.

Example:

  "conditions": [
    [
      {
        "where": "state",
        "condition": "is",
        "value": "MERGED"
      }
    ],
    [
      {
        "where": "type",
        "condition": "is",
        "value": "issue"
      }
    ]
  ]

In this example, we use OR condition. Using this configuration plugin returns data where the state property is MEREGED OR data type is issue. (If data type is issue the data will be selected whatever the state property is).

If you need AND then a list of objects should be used.

  "conditions": [
    {
      "where": "state",
      "condition": "is",
      "value": "MERGED"
    },
    {
      "where": "type",
      "condition": "is",
      "value": "pullrequest"
    }

In this example AND condition comes into play. The data will be selected ONLY in the case when state is MERGED AND type is pullrequest.

And of course AND and OR conditions can be combined.

Example:

  "conditions": [
    [
      {
        "where": "state",
        "condition": "is",
        "value": "MERGED"
      },
      {
        "where": "type",
        "condition": "is",
        "value": "pullrequest"
      }
    ],
    [
      {
        "where": "type",
        "condition": "is",
        "value": "issue"
      }
    ]
  ]

In this example OR and AND conditions are used together. In this case, data will be selected if data state is MERGED AND type is pullrequest OR data type is issue.

Condition item

{
    "where": "type",
    "condition": "is",
    "value": "issue"
}
Options Description
where Data object property name
condition One of the condition operators. See condition operators.
value Value that should match data object property (that declared as where) value. Supports boolean values. If the property will be declared as boolean, the data object property value will be converted to boolean automatically

Condition operators

Operator Description
is Values exactly match
is not Values don't match
in Data object property exactly one of the values from provided list
not in Data object property don't match any values from provided list

Examples:

  • is
{
    "where": "type",
    "condition": "is",
    "value": "issue"
}

Will be true if the data object type property is issue.

  • is not
{
    "where": "type",
    "condition": "is not",
    "value": "issue"
}

Will be true if the data object type property is not an issue.

  • in
{
    "where": "type",
    "condition": "in",
    "value": ["issue", "pullrequest"]
}

Will be true if the data object type property is one of value from the array (issue or pullrequest).

  • not in
{
    "where": "type",
    "condition": "not in",
    "value": ["issue", "pullrequest"]
}

This will be true if the data object type property is not any of the values from the array (issue or pullrequest).

Level property explanation

Sometimes we need to filter nested properties from the data objects, for that application configuration supports level property. Let's imagine that we have the following data object:

{
    type: 'issue',
    labels: [],
    number: 324,
    repository: 'repository-name',
    organization: 'organization-name',
    crossreference: [
        {
            repository: 'repo-1',
            organization: 'org-1',
            number: 213
        },
        {
            repository: 'repo-2',
            organization: 'org-2',
            number: 214
        }
    ]
}

and we want to filter all crossreferences where the repository is not repo-1. To do it we need the following configuration:

{
    "level": "crossreference",
    "conditions": [
        {
            "where": "repository",
            "condition": "is",
            "value": "repo-1"
        }
    ]
}

As result we will receive a data object:

{
    type: 'issue',
    labels: [],
    number: 324,
    repository: 'repository-name',
    organization: 'organization-name',
    crossreference: [
        {
            repository: 'repo-1',
            organization: 'org-1',
            number: 213
        }      
    ]
}

Custom filters

  • Create a new <custom_name>.js file under the src/filters folder.
  • Create a new class implementing src/api/filter-interface interface. Note: The name of the file will be used as a filter name.
  • Use your custom filter name and configuration for loader.config.exclude config option.
  • To support condition mechanism in custom filters use src/services/filter-condition service

Clone this wiki locally