nips/50.md

50 lines
2.1 KiB
Markdown
Raw Normal View History

2023-01-17 10:49:10 -05:00
NIP-50
======
2023-01-27 07:44:51 -05:00
Search Capability
-----------------
2023-01-17 10:49:10 -05:00
`draft` `optional` `author:brugeman` `author:mikedilger` `author:fiatjaf` `depends:01` `depends:11`
2023-01-17 10:49:10 -05:00
## 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
2023-01-27 07:43:06 -05:00
extensible framework for performing such queries.
2023-01-17 10:49:10 -05:00
## `search` filter field
2023-01-17 10:49:10 -05:00
2023-01-27 07:43:06 -05:00
A new `search` field is introduced for `REQ` messages from clients:
2023-01-17 10:49:10 -05:00
```json
{
2023-01-27 07:43:06 -05:00
...
"search": <string>
2023-01-17 10:49:10 -05:00
}
```
`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.
2023-01-27 07:43:06 -05:00
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.
2023-01-17 10:49:10 -05:00
A query string may contain `key:value` pairs (two words separated by colon), these are extensions, relays SHOULD ignore
2023-01-27 07:43:06 -05:00
extensions they don't support.
2023-01-17 10:49:10 -05:00
Clients may specify several search filters, i.e. `["REQ", "", { "search": "orange" }, { "kinds": [1, 2], "search": "purple" }]`. Clients may
2023-01-27 07:43:06 -05:00
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`
2023-01-27 07:43:06 -05:00
filter queries to any relay, if they are prepared to filter out extraneous responses from relays that do not support this NIP.
2023-01-17 10:49:10 -05:00
Clients SHOULD query several relays supporting this NIP to compensate for potentially different
2023-01-27 07:43:06 -05:00
implementation details between relays.
2023-01-17 10:49:10 -05:00
2023-01-27 07:43:06 -05:00
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.
2023-01-17 10:49:10 -05:00
2023-01-27 07:43:06 -05:00
Relays SHOULD exclude spam from search results by default if they supports some form of spam filtering.
2023-01-17 10:49:10 -05:00
2023-01-27 07:43:06 -05:00
## Extensions
2023-01-17 10:49:10 -05:00
2023-01-27 07:43:06 -05:00
Relay MAY support these extensions:
- `include:spam` - turn off spam filtering, if it was enabled by default