From abe8b6016b3436b6dd6ff04b867c1e18cbad60d2 Mon Sep 17 00:00:00 2001 From: Wayne Wollesen Date: Tue, 28 Jul 2026 11:50:45 -0500 Subject: [PATCH 1/4] Document that ES/OpenSearch user search does not match email address Elasticsearch and AWS OpenSearch-backed user search matches on username, nickname, and first and last name only. Email addresses aren't indexed, so enabling enterprise search silently removes email matching from user search. Add a fourth Enterprise search limitation covering the behavior, which user searches remain database-backed, and the Show email address dependency for non-admins. Scope the admin onboarding sentence to message search and link to the limitations list. Co-Authored-By: Claude Opus 5 (1M context) --- .../scale/common-configure-mattermost-for-enterprise-search.rst | 1 + source/administration-guide/upgrade/admin-onboarding-tasks.rst | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/source/administration-guide/scale/common-configure-mattermost-for-enterprise-search.rst b/source/administration-guide/scale/common-configure-mattermost-for-enterprise-search.rst index 0cf16c7d63d..78304b8e14c 100644 --- a/source/administration-guide/scale/common-configure-mattermost-for-enterprise-search.rst +++ b/source/administration-guide/scale/common-configure-mattermost-for-enterprise-search.rst @@ -50,3 +50,4 @@ Enterprise search limitations 1. Elasticsearch and AWS OpenSearch uses a standard selection of "stop words" to keep search results relevant. Results for the following words will not be returned: "a", "an", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", and "with". 2. Searching stop words in quotes returns more results than just the searched terms (`ticket `__). 3. By default, search results are limited to a user's team and channel membership. This is enforced by the Mattermost server. The entities are indexed in Elasticsearch or AWS OpenSearch in a way that allows Mattermost to filter them when querying, so the Mattermost server narrows down the results on every Elasticsearch or AWS OpenSearch request applying those filters. From Mattermost v11.6, admins can :ref:`allow searching public channels without membership ` so that users can find messages in public channels they haven't joined, scoped to teams they belong to. +4. User search and autocomplete served by Elasticsearch or AWS OpenSearch match on username, nickname, and first and last name only. Email addresses aren't indexed, so users can't be found by email address. User searches served from the database continue to match on email address, including the **System Console > User Management > Users** list, and channel and team member searches. For users who aren't system admins, email address matching also requires :ref:`Show email address ` to be enabled. diff --git a/source/administration-guide/upgrade/admin-onboarding-tasks.rst b/source/administration-guide/upgrade/admin-onboarding-tasks.rst index 74f7adfd9a1..879451d0199 100644 --- a/source/administration-guide/upgrade/admin-onboarding-tasks.rst +++ b/source/administration-guide/upgrade/admin-onboarding-tasks.rst @@ -143,6 +143,6 @@ Then, enable batched email notifications by setting **System Console > Notificat **9. Enable Elasticsearch** -Mattermost Enterprise customers can enable :doc:`enterprise search ` for optimized search performance at enterprise-scale. Both Elasticsearch and AWS OpenSearch solve many known issues with full text database search, such as dots, dashes, and email addresses returning unexpected results. +Mattermost Enterprise customers can enable :doc:`enterprise search ` for optimized search performance at enterprise-scale. Both Elasticsearch and AWS OpenSearch solve many known issues with full text message search in the database, such as dots, dashes, and email addresses returning unexpected results. Before enabling, review the :ref:`enterprise search limitations `, as some user search behavior differs from database search. Enable Elasticsearch by setting **System Console > Elasticsearch > Enable Indexing** to **true**. See the :ref:`Elasticsearch ` configuration settings documentation for details. Enabling Elasticsearch requires :ref:`setting up an Elasticsearch server `. From 9236ddceb2dec787c6634635b5a474cf291d9db2 Mon Sep 17 00:00:00 2001 From: Wayne Wollesen Date: Tue, 28 Jul 2026 12:02:23 -0500 Subject: [PATCH 2/4] Fix subject-verb agreement in enterprise search limitations The subject "Elasticsearch and AWS OpenSearch" is plural, so item 1 takes "use" rather than "uses". Co-Authored-By: Claude Opus 5 (1M context) --- .../scale/common-configure-mattermost-for-enterprise-search.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/administration-guide/scale/common-configure-mattermost-for-enterprise-search.rst b/source/administration-guide/scale/common-configure-mattermost-for-enterprise-search.rst index 78304b8e14c..38a471836ff 100644 --- a/source/administration-guide/scale/common-configure-mattermost-for-enterprise-search.rst +++ b/source/administration-guide/scale/common-configure-mattermost-for-enterprise-search.rst @@ -47,7 +47,7 @@ Once the configuration is saved, new posts made to the database are automaticall Enterprise search limitations ------------------------------- -1. Elasticsearch and AWS OpenSearch uses a standard selection of "stop words" to keep search results relevant. Results for the following words will not be returned: "a", "an", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", and "with". +1. Elasticsearch and AWS OpenSearch use a standard selection of "stop words" to keep search results relevant. Results for the following words will not be returned: "a", "an", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", and "with". 2. Searching stop words in quotes returns more results than just the searched terms (`ticket `__). 3. By default, search results are limited to a user's team and channel membership. This is enforced by the Mattermost server. The entities are indexed in Elasticsearch or AWS OpenSearch in a way that allows Mattermost to filter them when querying, so the Mattermost server narrows down the results on every Elasticsearch or AWS OpenSearch request applying those filters. From Mattermost v11.6, admins can :ref:`allow searching public channels without membership ` so that users can find messages in public channels they haven't joined, scoped to teams they belong to. 4. User search and autocomplete served by Elasticsearch or AWS OpenSearch match on username, nickname, and first and last name only. Email addresses aren't indexed, so users can't be found by email address. User searches served from the database continue to match on email address, including the **System Console > User Management > Users** list, and channel and team member searches. For users who aren't system admins, email address matching also requires :ref:`Show email address ` to be enabled. From e77ff8dd546c9b341e3debf9bb08d0a4c1d892ef Mon Sep 17 00:00:00 2001 From: Wayne Wollesen Date: Tue, 28 Jul 2026 12:14:45 -0500 Subject: [PATCH 3/4] State the system admin email matching exemption explicitly Reframe the Show email address dependency so the system admin behavior is stated affirmatively rather than implied by a negative carve-out. Co-Authored-By: Claude Opus 5 (1M context) --- .../scale/common-configure-mattermost-for-enterprise-search.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/administration-guide/scale/common-configure-mattermost-for-enterprise-search.rst b/source/administration-guide/scale/common-configure-mattermost-for-enterprise-search.rst index 38a471836ff..9b0ed821ac1 100644 --- a/source/administration-guide/scale/common-configure-mattermost-for-enterprise-search.rst +++ b/source/administration-guide/scale/common-configure-mattermost-for-enterprise-search.rst @@ -50,4 +50,4 @@ Enterprise search limitations 1. Elasticsearch and AWS OpenSearch use a standard selection of "stop words" to keep search results relevant. Results for the following words will not be returned: "a", "an", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", and "with". 2. Searching stop words in quotes returns more results than just the searched terms (`ticket `__). 3. By default, search results are limited to a user's team and channel membership. This is enforced by the Mattermost server. The entities are indexed in Elasticsearch or AWS OpenSearch in a way that allows Mattermost to filter them when querying, so the Mattermost server narrows down the results on every Elasticsearch or AWS OpenSearch request applying those filters. From Mattermost v11.6, admins can :ref:`allow searching public channels without membership ` so that users can find messages in public channels they haven't joined, scoped to teams they belong to. -4. User search and autocomplete served by Elasticsearch or AWS OpenSearch match on username, nickname, and first and last name only. Email addresses aren't indexed, so users can't be found by email address. User searches served from the database continue to match on email address, including the **System Console > User Management > Users** list, and channel and team member searches. For users who aren't system admins, email address matching also requires :ref:`Show email address ` to be enabled. +4. User search and autocomplete served by Elasticsearch or AWS OpenSearch match on username, nickname, and first and last name only. Email addresses aren't indexed, so users can't be found by email address. User searches served from the database continue to match on email address, including the **System Console > User Management > Users** list, and channel and team member searches. System admins can always match on email address. For all other users, email address matching also requires :ref:`Show email address ` to be enabled. From 36a547d0227910209d6499da022d9c7f8e322576 Mon Sep 17 00:00:00 2001 From: Wayne Wollesen Date: Tue, 28 Jul 2026 14:01:46 -0500 Subject: [PATCH 4/4] Scope email matching claims to the backend that serves each search The sentence "System admins can always match on email address" sat after the Elasticsearch and AWS OpenSearch statements, implying system admins are exempt from the limitation. They aren't: the index has no email field, and the manage_system exemption is consumed only by the SQL store, so it cannot affect the Elasticsearch or AWS OpenSearch query path. Attach scope to each claim: no user matches on email under enterprise search, system admins and the Show email address setting apply to channel and team member searches, and the System Console user list is independent of that setting because it is served by the reporting API. Co-Authored-By: Claude Opus 5 (1M context) --- .../scale/common-configure-mattermost-for-enterprise-search.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/administration-guide/scale/common-configure-mattermost-for-enterprise-search.rst b/source/administration-guide/scale/common-configure-mattermost-for-enterprise-search.rst index 9b0ed821ac1..9573e9a5676 100644 --- a/source/administration-guide/scale/common-configure-mattermost-for-enterprise-search.rst +++ b/source/administration-guide/scale/common-configure-mattermost-for-enterprise-search.rst @@ -50,4 +50,4 @@ Enterprise search limitations 1. Elasticsearch and AWS OpenSearch use a standard selection of "stop words" to keep search results relevant. Results for the following words will not be returned: "a", "an", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", and "with". 2. Searching stop words in quotes returns more results than just the searched terms (`ticket `__). 3. By default, search results are limited to a user's team and channel membership. This is enforced by the Mattermost server. The entities are indexed in Elasticsearch or AWS OpenSearch in a way that allows Mattermost to filter them when querying, so the Mattermost server narrows down the results on every Elasticsearch or AWS OpenSearch request applying those filters. From Mattermost v11.6, admins can :ref:`allow searching public channels without membership ` so that users can find messages in public channels they haven't joined, scoped to teams they belong to. -4. User search and autocomplete served by Elasticsearch or AWS OpenSearch match on username, nickname, and first and last name only. Email addresses aren't indexed, so users can't be found by email address. User searches served from the database continue to match on email address, including the **System Console > User Management > Users** list, and channel and team member searches. System admins can always match on email address. For all other users, email address matching also requires :ref:`Show email address ` to be enabled. +4. User search and autocomplete served by Elasticsearch or AWS OpenSearch match on username, nickname, and first and last name only. Email addresses aren't indexed, so no user can be found by email address, including system admins. User searches served from the database continue to match on email address. For channel and team member searches, system admins always match on email address, and all other users also require :ref:`Show email address ` to be enabled. The **System Console > User Management > Users** list always matches on email address, independently of that setting.