@@ -6,6 +6,10 @@ and this project adheres to
 
 ## [Unreleased]
 
+### Changed
+
+- ⚡️(backend) search users through the trigram indexes instead of a full scan
+
 ## [v6.0.3] - 2026-10-23
 
 ### Added
 
@@ -18,7 +18,7 @@
 from django.core.exceptions import ValidationError
 from django.core.files.storage import default_storage
 from django.core.validators import URLValidator
-from django.db import DatabaseError, transaction
+from django.db import DatabaseError, connection, transaction
 from django.db import models as db
 from django.db.models.expressions import RawSQL
 from django.db.models.functions import Greatest, Left, Length
@@ -104,6 +104,21 @@
 
 # pylint: disable=too-many-ancestors
 
+# Minimum trigram similarity between a user search and an email or a full name
+USERS_SEARCH_SIMILARITY_THRESHOLD = 0.2
+
+
+def set_trigram_similarity_threshold(threshold):
+    """
+    Set the threshold of the trigram `%` operator for the current transaction only,
+    so that it never leaks to the next users of a pooled connection.
+    """
+    with connection.cursor() as cursor:
+        cursor.execute(
+            "SELECT set_config('pg_trgm.similarity_threshold', %s, true)",
+            [str(threshold)],
+        )
+
 
 class NestedGenericViewSet(viewsets.GenericViewSet):
     """
@@ -233,94 +248,89 @@ def get_queryset(self):
 
         filter_data = filterset.form.cleaned_data
         query = remove_accents(filter_data["q"])
+        if not query:
+            return []
 
-        # For emails, match emails by Levenstein distance to prevent typing errors
+        limit = settings.API_USERS_LIST_LIMIT
+
+        # The trigram indexes of migration 0027 are built on these two expressions:
+        # only a `%` filter on them uses the indexes, any other condition on the
+        # user table (a similarity score, the raw columns) scans all the users.
+        queryset = queryset.alias(
+            unaccented_email=db.Func(
+                "email", function="f_unaccent", output_field=db.TextField()
+            ),
+            unaccented_full_name=db.Func(
+                "full_name", function="f_unaccent", output_field=db.TextField()
+            ),
+        )
+
+        # For emails, match emails by Levenstein distance to prevent typing errors,
+        # among the users that the trigram index finds close enough to the query
         if "@" in query:
-            return (
-                queryset.annotate(
-                    distance=RawSQL(
-                        "levenshtein(unaccent(email::text), %s::text)", (query,)
+            with transaction.atomic():
+                set_trigram_similarity_threshold(USERS_SEARCH_SIMILARITY_THRESHOLD)
+                return list(
+                    queryset.filter(unaccented_email__trigram_similar=query)
+                    .annotate(
+                        distance=RawSQL(
+                            "levenshtein(unaccent(email::text), %s::text)", (query,)
+                        )
                     )
+                    .filter(distance__lte=3)
+                    .order_by("distance", "email")[:limit]
                 )
-                .filter(distance__lte=3)
-                .order_by("distance", "email")[: settings.API_USERS_LIST_LIMIT]
-            )
 
-        # Use trigram similarity for non-email-like queries
-        # For performance reasons we filter first by similarity, which relies on an
-        # index, then only calculate precise similarity scores for sorting purposes.
+        # Use trigram similarity for non-email-like queries.
         #
-        # Additionally results are reordered to prefer users "closer" to the current
-        # user: users they recently shared documents with, then same email domain.
-        # To achieve that without complex SQL, we build a proximity score in Python
-        # and return the top N results.
-        # For security results, users that match neither of these proximity criteria
+        # Results are ordered to prefer users "closer" to the current user: users
+        # they recently shared documents with, then users of the same email domain.
+        # For security reasons, users that match neither of these proximity criteria
         # are not returned at all, to prevent email enumeration.
         current_user = self.request.user
         shared_map = users_sharing_documents_with(current_user.id)
+        shared_ids = list(shared_map)
+        user_email_domain = get_domain_from_email(current_user.email)
 
-        user_email_domain = get_domain_from_email(current_user.email) or ""
-
-        candidates = list(
-            queryset.annotate(
-                sim_email=TrigramSimilarity("email", query),
-                sim_name=TrigramSimilarity("full_name", query),
+        similar_users = queryset.filter(
+            db.Q(unaccented_email__trigram_similar=query)
+            | db.Q(unaccented_full_name__trigram_similar=query)
+        ).annotate(
+            similarity=Greatest(
+                TrigramSimilarity("unaccented_email", query),
+                TrigramSimilarity("unaccented_full_name", query),
             )
-            .annotate(similarity=Greatest("sim_email", "sim_name"))
-            .filter(similarity__gt=0.2)
-            .order_by("-similarity")
         )
 
-        # Keep only users that either share documents with the current user
-        # or have an email with the same domain as the current user.
-        filtered_candidates = []
-        for u in candidates:
-            candidate_domain = get_domain_from_email(u.email) or ""
-            if shared_map.get(u.id) or (
-                user_email_domain and candidate_domain == user_email_domain
-            ):
-                filtered_candidates.append(u)
-
-        candidates = filtered_candidates
-
-        # Build ordering key for each candidate
-        def _sort_key(u):
-            # shared priority: most recent first
-            # Use shared_last_at timestamp numeric for secondary ordering when shared.
-            shared_last_at = shared_map.get(u.id)
-            if shared_last_at:
-                is_shared = 1
-                shared_score = int(shared_last_at.timestamp())
-            else:
-                is_shared = 0
-                shared_score = 0
-
-            # domain proximity
-            candidate_email_domain = get_domain_from_email(u.email) or ""
+        with transaction.atomic():
+            set_trigram_similarity_threshold(USERS_SEARCH_SIMILARITY_THRESHOLD)
 
-            same_full_domain = (
-                1
-                if candidate_email_domain
-                and candidate_email_domain == user_email_domain
-                else 0
+            # Bounded by the number of users the current user shares documents with
+            shared_users = (
+                list(similar_users.filter(id__in=shared_ids)) if shared_ids else []
             )
 
-            # similarity fallback
-            sim = getattr(u, "similarity", 0) or 0
-
-            return (
-                is_shared,
-                shared_score,
-                same_full_domain,
-                sim,
-            )
+            # A domain can count many users: only fetch the ones that can still fit
+            domain_users = []
+            if user_email_domain and len(shared_users) < limit:
+                domain_users = list(
+                    similar_users.filter(email__endswith=f"@{user_email_domain}")
+                    .exclude(id__in=shared_ids)
+                    .order_by("-similarity")[: limit - len(shared_users)]
+                )
 
-        # Sort candidates by the key descending and return top N as a queryset-like
-        # list. Keep return type consistent with previous behavior (QuerySet slice
-        # was returned) by returning a list of model instances.
-        candidates.sort(key=_sort_key, reverse=True)
+        # Most recently shared first, then same domain, then the closest match
+        shared_users.sort(
+            key=lambda user: (
+                shared_map[user.id],
+                bool(user_email_domain)
+                and get_domain_from_email(user.email) == user_email_domain,
+                user.similarity,
+            ),
+            reverse=True,
+        )
 
-        return candidates[: settings.API_USERS_LIST_LIMIT]
+        return (shared_users + domain_users)[:limit]
 
     @drf.decorators.action(
         detail=False,
 
@@ -2,6 +2,8 @@
 Test users API endpoints in the impress core app.
 """
 
+from django.db import connection
+from django.test.utils import CaptureQueriesContext
 from django.utils import timezone
 
 import pytest
@@ -430,6 +432,115 @@ def test_api_users_list_query_inactive():
     assert user_ids == [str(lennon.id)]
 
 
+def test_api_users_list_shared_users_before_more_similar_domain_users():
+    """
+    A user sharing documents with the current user should come first even if
+    enough users of the same domain match the query better to fill the response,
+    and the remaining places should go to the users of the same domain.
+    """
+    user = factories.UserFactory(
+        email="martin.bernard@anct.gouv.fr", full_name="Martin Bernard"
+    )
+
+    client = APIClient()
+    client.force_login(user)
+
+    shared = factories.UserFactory(
+        email="jp.dupont@beta.gouv.fr", full_name="Jean-Pierre Dupont-Martinez"
+    )
+    document = factories.DocumentFactory()
+    factories.UserDocumentAccessFactory(user=user, document=document)
+    factories.UserDocumentAccessFactory(user=shared, document=document)
+
+    same_domain = [
+        factories.UserFactory(email=f"pierre.{i}@anct.gouv.fr", full_name="Pierre")
+        for i in range(8)
+    ]
+
+    response = client.get("/api/v1.0/users/?q=Pierre")
+
+    assert response.status_code == 200
+    user_ids = [user["id"] for user in response.json()]
+    assert len(user_ids) == 5
+    assert user_ids[0] == str(shared.id)
+    assert set(user_ids[1:]) <= {str(other.id) for other in same_domain}
+
+
+@pytest.mark.parametrize(
+    "query,indexes",
+    [
+        (
+            "Bowman",
+            ["user_email_unaccent_trgm_idx", "user_full_name_unaccent_trgm_idx"],
+        ),
+        ("david.bowman@work.com", ["user_email_unaccent_trgm_idx"]),
+    ],
+)
+def test_api_users_list_query_uses_trigram_indexes(query, indexes):
+    """
+    Searching users should go through the trigram indexes on the unaccented email
+    and full name instead of scanning the whole user table.
+    """
+    user = factories.UserFactory(email="user@work.com")
+    dave = factories.UserFactory(
+        email="david.bowman@work.com", full_name="David Bowman"
+    )
+
+    client = APIClient()
+    client.force_login(user)
+
+    with CaptureQueriesContext(connection) as context:
+        response = client.get(f"/api/v1.0/users/?q={query}")
+
+    assert response.status_code == 200
+    assert [user["id"] for user in response.json()] == [str(dave.id)]
+
+    searches = [
+        captured["sql"]
+        for captured in context.captured_queries
+        if 'FROM "impress_user"' in captured["sql"] and query in captured["sql"]
+    ]
+    assert searches
+
+    with connection.cursor() as cursor:
+        # With so few users, a sequential scan would win even if an index can serve
+        cursor.execute("SET LOCAL enable_seqscan = off")
+        for search in searches:
+            cursor.execute(f"EXPLAIN {search}")
+            plan = "\n".join(row[0] for row in cursor.fetchall())
+            for index in indexes:
+                assert index in plan
+
+
+@pytest.mark.django_db(transaction=True)
+def test_api_users_list_similarity_threshold_does_not_leak():
+    """
+    The trigram similarity threshold set for a search should not stay on the
+    connection after the request, other requests share it through the pool.
+    """
+    user = factories.UserFactory(email="user@work.com")
+    dave = factories.UserFactory(
+        email="david.bowman@work.com", full_name="David Bowman"
+    )
+
+    client = APIClient()
+    client.force_login(user)
+
+    with connection.cursor() as cursor:
+        cursor.execute("SELECT show_limit()")
+        default_threshold = cursor.fetchone()[0]
+
+    for query in ["Bowman", "david.bowman@work.com"]:
+        response = client.get(f"/api/v1.0/users/?q={query}")
+
+        assert response.status_code == 200
+        assert [user["id"] for user in response.json()] == [str(dave.id)]
+
+        with connection.cursor() as cursor:
+            cursor.execute("SELECT show_limit()")
+            assert cursor.fetchone()[0] == default_threshold
+
+
 def test_api_users_retrieve_me_anonymous():
     """Anonymous users should not be allowed to list users."""
     factories.UserFactory.create_batch(2)