NIP-50

Search Capability

draft optional relay

Abstract

Many Nostr use cases require some form of general search feature, in addition to structured queries by tags or ids. Specifics of the search algorithms will differ between event kinds, this NIP only describes a general extensible framework for performing such queries.

`search` filter field

A new search field is introduced for REQ messages from clients:

{
  // other fields on filter object...
  "search": <string>
}

search field is a string describing a query in a human-readable form, i.e. "best nostr apps". Relays SHOULD interpret the query to the best of their ability and return events that match it. Relays SHOULD perform matching against content event field, and MAY perform matching against other fields if that makes sense in the context of a specific kind.

A query string may contain key:value pairs (two words separated by colon), these are extensions, relays SHOULD ignore extensions they don't support.

Query Expression Extensions

Relays MAY support query expressions with boolean operators and filter attributes. When supported, this MUST be advertised in NIP-11:

{
  "supported_nips": [50],
  "nip50_search": {
    "boolean_operators": true,
    "filter_attributes": ["limit", "since", "until"]
  }
}

When boolean_operators is true, relays SHOULD support:

Terms split by whitespace (implicit AND)
Double quotes for phrase matching: "hello world"
Boolean operators: AND, OR (uppercase, case-sensitive)
Parentheses for grouping: (cat AND dog) OR bird
Operator precedence: AND binds tighter than OR

Examples:

hello world → both terms required (implicit AND)
hello OR world → either term matches
cat AND (dog OR bird) → "cat" plus either "dog" or "bird"

When filter_attributes is present, relays SHOULD support filter attributes in the query string:

limit:<number> - limit number of results (e.g., limit:50)
since:<unix timestamp> - filter events after timestamp (e.g., since:1609459200)
until:<unix timestamp> - filter events before timestamp (e.g., until:1640995200)

Examples:

nostr limit:50 → search "nostr" and return up to 50 results
bitcoin since:1609459200 → search "bitcoin" for events after the specified time
cats OR dogs limit:100 since:1640995200 → combined query with filters

Results SHOULD be returned in descending order by quality of search result (as defined by the implementation), not by the usual .created_at. The limit filter SHOULD be applied after sorting by matching score.

Clients may specify several search filters, i.e. ["REQ", "", { "search": "orange" }, { "kinds": [1, 2], "search": "purple" }]. Clients may include kinds, ids and other filter field to restrict the search results to particular event kinds.

Clients SHOULD use the supported_nips field to learn if a relay supports search filter. Clients MAY send search filter queries to any relay, if they are prepared to filter out extraneous responses from relays that do not support this NIP.

Clients SHOULD query several relays supporting this NIP to compensate for potentially different implementation details between relays.

Clients MAY verify that events returned by a relay match the specified query in a way that suits the client's use case, and MAY stop querying relays that have low precision.

Relays SHOULD exclude spam from search results by default if they support some form of spam filtering.

Extensions

Relay MAY support these extensions:

include:spam - turn off spam filtering, if it was enabled by default
domain:<domain> - include only events from users whose valid nip05 domain matches the domain
language:<two letter ISO 639-1 language code> - include only events of a specified language
sentiment:<negative/neutral/positive> - include only events of a specific sentiment
nsfw:<true/false> - include or exclude nsfw events (default: true)

3.9 KiB Raw Permalink Blame History