mirror of
https://github.com/nostr-protocol/nips.git
synced 2026-01-24 19:19:07 +00:00
95 lines
3.9 KiB
Markdown
95 lines
3.9 KiB
Markdown
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:
|
|
```jsonc
|
|
{
|
|
// 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:
|
|
|
|
```json
|
|
{
|
|
"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)
|