The complete Filter Engine
Learn Include, Exclude, ANY, ALL and every matcher in Stable 2.0.55, confirm the scope in the preview first, and only then let Home Assistant entities into a Matter bridge.
Turn "which entities get bridged" into a predictable rule
The Filter Engine decides whether an entity in the Home Assistant registry is eligible for a bridge to build a Matter endpoint from. It is not the room filter inside a controller, and it does not change the entities in Home Assistant itself; it only controls the candidate set for this one bridge. In a home with lights, diagnostic sensors, scripts and integrations from several brands, including every entity outright tends to push out items you do not need or that are not supported. In a small office you often need to split into several bridges by floor, by area or by label.
The right approach is to write the include conditions first, then the always-exclude conditions, and check the result in the preview last. An empty Include array means the candidates are not restricted; only a non-empty Include is evaluated against includeMode. Exclude always removes an entity as soon as any one rule matches. The final result can be written as: (Include is empty or Include evaluates true) and nothing in Exclude matches.
ANY, ALL, empty sets and precedence
| Where | How they combine | Result | When it fits |
|---|---|---|---|
| An empty Include array | No matcher runs | Every registered entity starts out included | A blocklist strategy driven by Exclude |
Include + any | OR | Any one Include matcher is enough | Including several domains, areas or labels |
Include + all | AND | Every Include matcher has to match | For example, requiring the light domain and a given area at the same time |
| Exclude | Always ANY / OR | Any one Exclude matcher removes the entity | Excluding diagnostic, test or sensitive-action entities |
| Include and Exclude both match | Exclude wins | The entity is not included | Include broadly first, then add safety guards |
includeMode applies to Include only; when it is omitted, the code defaults to any. Exclude calls the matcher test without a mode, so it defaults to any as well. ALL does not mean the several values of one matcher are ANDed together; each row still carries exactly one type and one value, and ALL requires every row to succeed.
Hidden entities are a second layer of the decision. Even when a matcher matches, an entity that Home Assistant marks as hidden is skipped by default; it comes in only when the bridge's includeHiddenEntities feature flag is on. An entity marked disabled in the mapping likewise should not be treated as a usable endpoint. Do not run the filter, the hidden flag and the Entity Mapping disable together as if they were one switch.
Every Stable 2.0.55 matcher at a glance
| type | Data matched | Exact behavior and caveats |
|---|---|---|
pattern | entity_id | A wildcard expands only * into an arbitrary string, and the whole value is anchored at both ends; every other regular-expression character is escaped. Example: light.demo_*. |
regex | entity_id | Builds a JavaScript RegExp directly and tests entity_id only; invalid syntax returns no match, and it never falls back to another field. Example: ^(light|switch)\.demo_.*. |
domain | The part of entity_id before the dot | An exact, case-sensitive match, for example light; it accepts neither a comma-separated list nor a wildcard. |
platform | Entity Registry platform | An exact match on the integration / platform string, for example the documented mqtt; the value Filter Reference displays is the authoritative one. |
label | The entity's own labels | Deprecated; it behaves exactly like entity_label. Old configurations still read, but new rules should migrate. |
entity_label | Entity labels | Includes only the entities that carry the label directly; it does not pull in the other entities on the same device. Enter either the display name or the label_id. |
device_label | Device labels | When a device label matches, every candidate entity under that device matches. Enter either the display name or the label_id. |
entity_label_regex | The slug and display name of every entity label | A match when any assigned label satisfies the RegExp; no labels, or an invalid RegExp, is no match. |
device_label_regex | The slug and display name of every device label | Any matching device label makes that device's entities match; good for managing a whole device through a label naming convention. |
any_field_regex | A single-line key=value haystack | Can check entity_id, domain, platform, area, entity_category, device_class, entity / device label slugs and names, device_name, product_name and manufacturer all at once. |
area | The entity area, otherwise the device area | Takes the entity's area_id first and falls back to the device's area_id; an exact match on the area slug. |
entity_category | Entity Registry category | An exact match, for example config or diagnostic; usually placed in Exclude. |
device_name | name_by_user → name → default_name | Without a * it is a case-insensitive substring; with a * it is a case-insensitive wildcard anchored across the whole value. |
product_name | model → default_model | The same case-insensitive substring, or an anchored wildcard when it contains *. |
manufacturer | manufacturer → default_manufacturer | The same case-insensitive substring or wildcard; no match when there is no device registry data. |
device_class | The current state's attributes.device_class | An exact match, for example temperature or motion; it is neither the entity domain nor the Matter device type. |
pattern a wildcard pattern and defines regex as an entity ID regex. The interface has no separate type named entityIdRegex; in v2.0.55, the entityIdRegex the requirements talk about is type: "regex".Regular expressions, label resolution and any-field
The exact label matchers first look the value up by display name, case-insensitively, and turn it into a label_id when they find one. When they do not, the code normalizes your input: it strips combining diacritics, lowercases, turns every non-alphanumeric character into an underscore and clears leading and trailing underscores. The most reliable route is still to copy the real label_id from Filter Reference in the sidebar (route /labels), so a renamed label cannot change what the rule does.
The haystack for any_field_regex is one line of key=value fields joined by spaces. You can express OR with alternation, and require one entity to satisfy several fields at once with positive lookahead, as the documentation illustrates with (?=.*domain=light)(?=.*area=demo_room). Label arrays are joined with commas, so test any boundary construct against your real slugs. The engine builds the rule with new RegExp(pattern) and adds no case-insensitive flag; cover the casing explicitly in the pattern when you need it, and the most stable option is still the raw value Filter Reference shows.
| Requirement | Recommended matcher | Why |
|---|---|---|
| A known set of entity_id prefixes | pattern | Easier to read than a regex, and anchored end to end. |
| The entity_id structure of two domains | regex | Alternation on entity_id only, so the scope is explicit. |
| One entity label | entity_label | It will not drag in a whole device by accident. |
| A whole device and all its entities | device_label | More stable in meaning than several entity_id rules. |
| domain and area both true | Two rows under Include ALL | Easier to maintain than an any-field lookahead. |
| Complex OR / AND across fields | any_field_regex | Only it sees the whole haystack inside a single matcher. |
Build and preview a filter in the field editor
Open the bridge edit page
Select the target bridge on Bridges and open Edit. Write down the current Include, Exclude and
includeModefirst, and do not change feature flags at the same time.Choose the Include Mode
Under Include or exclude entities, set Include Mode to any or all. ANY suits "any one of these categories"; ALL suits "all of these conditions at once".
Add Include rows one at a time
Use the Include add control, then pick a Type and fill in a Value for each row. Copy label, area and platform values from Filter Reference in the sidebar rather than guessing them from the displayed text.
Add Exclude guards
Put the categories you should not expose into Exclude, such as a category of
diagnosticor an explicit test entity pattern. A single Exclude match beats Include.Check Preview Matching Entities
Wait about 800 ms for the automatic refresh, or press Preview Matching Entities. Check the count, the domain chips, the names and the entity_ids; the preview lists at most the first 100 rows, and total is the real number of matches.
Save and verify
Press Save only when the preview matches what you expect and the form is valid. Then go back to Bridge / Devices to check the actual endpoints and the failed entities; do not make "the controller shows it immediately" your only success criterion.
Filter Preview runs the same matcher logic against the current Home Assistant entity, device, state and label registries, and sorts the result by entity_id. It also flags a large entity count, an unsupported domain or a vacuum situation; those hints are planning information and never rewrite the configuration on their own.
Maintainable rules for homes and offices
A room-specific bridge: set Include Mode to ALL, use area in the first row with the area slug the documentation uses, and domain in the second row limited to light. That is not the same thing as "area or light". If you want switches too, express light / switch with a single entity ID regex and put it under ALL together with the area, or reorganize the categories with entity or device labels.
A voice-device allowlist: in Home Assistant, put an entity label directly on the entities you are willing to hand to a voice controller, and use entity_label in Include. Use device_label only when you need every entity on a device. Do not build new configurations on the deprecated label.
Include broadly, exclude precisely: leave Include empty and add entity_category=config, entity_category=diagnostic and a test-naming pattern to Exclude. This strategy widens on its own as Home Assistant gains entities; look at the Preview again after every integration you add.
Splitting by brand or model: use manufacturer, product_name or device_name. All three do a case-insensitive substring match, and only switch to a whole-value match when they contain a wildcard. An entity whose device registry data is missing will not match, so use the Preview to find the gaps instead of assuming platform is the same as manufacturer.
Back out step by step when the filter result is wrong
Include ALL returns zero rows
Temporarily keep only one row at a time and look at the Preview, confirming that each row can match the same entity on its own. The most common causes are setting "area A or area B" to ALL by mistake, and invalid regex syntax.
A label brings in only one entity
Check that you are using
entity_label. If you want a whole device, assign the label to the device in Home Assistant and switch todevice_label; do not expect an entity label to propagate on its own.The area rule does not match
Copy the area slug from Filter Reference. The engine looks at the entity area first and only then at the device area; an entity that has been placed in another area overrides the device area.
It is in the Preview but not on the bridge
Check the hidden state,
includeHiddenEntities, the disabled flag in Entity Mapping, whether the domain and type are supported, and the bridge's failed entities. Filter Preview only proves the filter decision.Exclude did not block an item
Exclude is always ANY, so check first that the type points at the right field.
regexlooks at entity_id only; to check manufacturer or labels, switch to the dedicated matcher or to an any-field regex.The preview shows only 100 rows
That is the interface truncating, not a filter limit. Read total, narrow the rule or split the bridge, then preview again, so a healthy-looking first 100 rows does not hide what is at the end.
Filter Engine FAQ
Does leaving Include empty mean no entity is included?
Can Exclude be set to ALL as well?
includeMode only, and the backend uses the default ANY for Exclude. Any single Exclude match excludes the entity.Which of pattern and regex is case-insensitive?
* into a wildcard and anchors the value; regex is a JavaScript RegExp. Only device_name, product_name and manufacturer lowercase the values before comparing.Does Filter Reference change labels or areas?
If the controller does not show it, does that mean the matcher is wrong?
Stable 2.0.55 pinned-version sources
- home-assistant-filter.ts: the matcher and includeMode types
- bridge-config-schema.ts: field descriptions and validation
- matches-entity-filter.ts: the actual matching algorithm
- matter-api.ts: the Filter Preview API and Include / Exclude precedence
- FilterPreview.tsx: the preview, truncation and warning interface
- LabelsPage.tsx: the fields Filter Reference can look up
All of the above are pinned to the v2.0.55 commit; this chapter describes the Stable channel. The Filter Engine itself is a settled feature, and controller support plays no part in the matcher decision.