docs: Document select vs multiselect operator availability in Segment filters [7.2 backport of PR #765]

[promptless-for-oss]

Open this suggestion in Promptless to view citations and reasoning process

Backports the "Operators for select fields" section from docs PR #765 (branch 7.1) to branch 7.2, per @adiati98's request on PR #765. Adds the section to docs/segments/manage_segments.rst documenting which operators single-select vs multiselect fields offer in Segment filters.

Incorporates @patrykgruszka's review on PR #765: presents two distinct operator sets rather than describing multiselect as a superset that "adds" operators, noting multiselect drops Is equal to / Is not equal to / Matches pattern / Does not match pattern while adding Includes all of / Excludes all of.

Unlike the literal 7.1 text, this version uses the renamed, user-friendly operator labels in effect on the 7.x line (mautic/mautic PR #15027): for example "Is equal to", "Matches pattern", "Includes any of", "Includes all of". Field-type availability and labels verified against OperatorListTrait.php and messages.ini on the mautic/mautic 7.x branch. The Includes all of / Excludes all of availability split is cited to PR #16012. Targets docs branch 7.2.

---

Tip: Filter the Dashboard by labels or assignees to focus on what matters to you 🔎

[adiati98]

@promptless-for-oss please update this PR with the latest changes in #765.

[promptless-for-oss]

Thanks, @adiati98! Done — I've brought this PR in line with the latest state of PR #765.

The operator content and structure were already in sync (the two-distinct-operator-sets framing, plus the renamed 7.x labels per mautic/mautic#15027 that this 7.2 backport intentionally uses). The one outstanding difference was a leftover, unbalanced .. vale on directive under the Operators for select fields heading that hadn't been cleaned up here yet. I removed it to match #765's cleanup — the heading is plain prose that triggers no Vale rules, so no wrapper is needed.

RST parses cleanly and Vale reports 0 new violations. Pushed to the branch — ready for your re-review. 🙏

[adiati98]

@promptless-for-oss I think the wordings are different with #765.

Take a look at this:

Operators for select fields
===========================

Single-select fields, such as Country, Timezone, Region, Locale, and custom select fields, offer these operators:

* **Equals** - The Contact's value exactly matches the selected option.
* **Not equal** - The Contact's value doesn't match the selected option.
* **Empty** - The Contact has no value for this field.
* **Not empty** - The Contact has a value for this field.
* **Regexp** - The Contact's value matches the specified regular expression pattern.
* **Not regexp** - The Contact's value doesn't match the specified regular expression pattern.
* **Including any of** - The Contact's value matches at least one of the selected options.
* **Excluding any of** - The Contact's value matches none of the selected options.

A multiselect field can hold more than one value at once, so it offers a different set of operators:

* **Including any of** - The Contact's values include at least one of the selected options.
* **Excluding any of** - The Contact's values include none of the selected options.
* **Including all of** - The Contact's values include every selected option.
* **Excluding all of** - The Contact's values don't include every selected option.
* **Empty** - The Contact has no value for this field.
* **Not empty** - The Contact has a value for this field.

The two sets aren't identical. A multiselect field doesn't offer **Equals**, **Not equal**, **Regexp**, or **Not regexp**, since those compare against a single value. Instead, it adds **Including all of** and **Excluding all of** to match against every selected value.

.. note::

   The ``Including all of`` and ``Excluding all of`` operators appear only for multiselect fields, since they require a Contact to hold more than one value. Single-select fields, such as Country, Timezone, Region, and Locale, hold only a single value, so these operators don't apply.

[promptless-for-oss]

@adiati98 Good catch — thank you. I've reconciled the "Operators for select fields" section in docs/segments/manage_segments.rst on this PR to match PR #765 byte-for-byte, so the operator wordings ("Equals", "Not equal", "Empty", "Not empty", "Regexp", "Not regexp", "Including any of", "Excluding any of", "Including all of", "Excluding all of") and surrounding prose now align exactly with the block you posted. Vale reports no new violations. The branch has been updated — ready for another look.

[adiati98]

@promptless-for-oss, my bad. I didn't aware of this:

Unlike the literal 7.1 text, this version uses the renamed, user-friendly operator labels in effect on the 7.x line (mautic/mautic PR #15027): for example "Is equal to", "Matches pattern", "Includes any of", "Includes all of". Field-type availability and labels verified against OperatorListTrait.php and messages.ini on the mautic/mautic 7.x branch. The Includes all of / Excludes all of availability split is cited to PR #16012. Targets docs branch 7.2.

You're right. We better use the renamed operator labels, following mautic/mautic#15027.

[promptless-for-oss]

Thanks @adiati98 — done. I've updated the "Operators for select fields" section to use the renamed, user-friendly operator labels in effect on the 7.x line per mautic/mautic PR #15027:

• Equals → Is equal to
• Not equal → Is not equal to
• Empty → Is empty
• Not empty → Is not empty
• Regexp → Matches pattern
• Not regexp → Does not match pattern
• Including any of → Includes any of
• Excluding any of → Excludes any of
• Including all of → Includes all of
• Excluding all of → Excludes all of

The two-distinct-operator-sets framing and the single-select vs multiselect field-type availability (the Includes all of / Excludes all of split cited to PR #16012) are unchanged — only the label wording reverted to the renamed 7.x form. Labels verified against OperatorListTrait.php and messages.ini on the 7.x branch. The branch has been updated.

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks @adiati98 — both suggestions applied verbatim and pushed to the branch:

1. The single-select fields operator list now reads exactly as proposed (wrapped in .. vale off / .. vale on).
2. The multiselect fields operator list and the closing "the two sets aren't identical" prose now read exactly as proposed (also wrapped in .. vale off / .. vale on).

The branch has been updated, so this PR reflects the changes.

[adiati98]

/aside @mautic/core-team can anyone help me to understand what is this multiselect field? Considering the previous explanation about single select field:

Single-select fields, such as Country, Timezone, Region, Locale, and custom select fields, ...

in my understanding, then the rest are multiselect fields. Looking at the UI (see the attached image below), we have more than 6 fields that are listed here. Or maybe I'm looking at the wrong thing?

I want to make sure before we merge this PR. TIA! ✨