buzz/docs/profile-search.md

Profile name search

POST /profiles/search finds community members by profile name. It matches only the name and display_name string fields of each current global kind:0 profile and, where the community advertises NIP-FI verified profiles (federated_identity.public_profile.searchable in NIP-11), the display_name, username and full_name tags of each current kind:30382 verified profile signed by the relay key. It does not search picture (including data URLs), about, nip05, banner, or any other profile field. NIP-50 search over kind:0 matches the whole profile JSON, so it can return profiles whose avatar data or bio happens to contain the query text.

Apart from the fields it reads, the endpoint matches and pages like a NIP-50 kind:0 search with search_mode: "prefix". A client can switch from one to the other without a visible change in which people a query finds.

The endpoint requires NIP-98 authentication over the request body and relay membership, like other relay-owned member endpoints. A relay without the endpoint answers 404; clients fall back to NIP-50 search for that request.

Request:

{ "query": "wes", "limit": 20, "page": 1 }

• query: 1 through 100 characters after trimming. Required.
• limit: results per page, 1 through 100. Defaults to 20.
• page: 1-based page of limit results, 1 through 1000. Defaults to 1.
• Unknown fields are rejected with 400.

Response: a JSON array of signed events for one page of people, best match first. Each person contributes their current kind:0, when they have one, then their current relay-signed kind:30382, when verified profiles are advertised and they have one, whichever of the two matched. A page with fewer than limit people is the last page. Clients that read only kind:0 keep working; they also find people who match only by verified name.

Matching is the NIP-50 prefix rule, case-insensitive. The query is split on whitespace. Every word except the last must equal a word of name or display_name; the last word may be a word prefix. Words may appear in any order and may be split across the two fields, so "johnson wes" finds "Wes Johnson". A verified profile matches the same way over its three name tags, except that its last word must be at least three characters, as in NIP-50. The two sources match separately: a query whose words are split between a person's kind:0 and their verified profile does not match. Accents are not folded.

People are ordered by their best match across both sources:

1. a name equal to the query;
2. a name that starts with the query;
3. a name with a later word that starts with the query;
4. any other match.

For these tiers the query and the names are lower-cased, with whitespace runs collapsed to one space and trimmed, by the same database expression. Ties go by relevance of the query to the names alone (not the whole profile, as in NIP-50), then newest first, then pubkey, so pages do not overlap. Profile content that is not a JSON object, or a name field that is not a string, never matches. Content that PostgreSQL cannot read as jsonb (for example a \u0000 escape or very deep nesting) has no names, so it never matches and never makes the search fail (schema/functions/profile_name_fields.sql).

Deployment

Verified-name matching reads idx_nip_fi_profile_heads_names. Relay startup migration and buzz-admin migrate build it before migration 0081 under a one-second lock and five-second statement budget. Applied directly as SQL, 0081 builds it only while nip_fi_profile_heads is empty. A deployment that applies migrations out of band (auto-migration off) builds it first, outside a transaction:

CREATE INDEX CONCURRENTLY idx_nip_fi_profile_heads_names
    ON public.nip_fi_profile_heads USING GIN (
    to_tsvector('simple',
        COALESCE(jsonb_path_query_first(event, 'strict $.tags[*] ? (@[0] == "display_name")[1]', '{}', true) #>> '{}', '')
        || ' ' || COALESCE(jsonb_path_query_first(event, 'strict $.tags[*] ? (@[0] == "username")[1]', '{}', true) #>> '{}', '')
        || ' ' || COALESCE(jsonb_path_query_first(event, 'strict $.tags[*] ? (@[0] == "full_name")[1]', '{}', true) #>> '{}', ''))
);

If the build fails, drop the invalid index and build it again. The migration then checks that the index is valid and has this definition.