Search
Search provides full text searching across handouts and characters (including attributes). Search uses an Okapi BM25F+ search engine with Porter stemming and stop word removal to provide fast results after building initial indexes. Index construction occurs at API startup, in the background. The GM is notified when indexing is finished. Indexing can take a few minutes, but won't slow down any other processes due to a great deal of deferring of processing.
Search respects permissions on handouts and characters. GMs can search on all things, where as players can only search based on what they can see. Seeing a handout allows a player to search on it's
name and notes fields. Seeing a character allows a player to search on it's name and bio fields. Controlling a character allows searching on it's attributes as well. Only GMs can search on gmnotes.Commands
!search --help|--reindex|<query>The interface to searching.
--help-- Displays this help in game.--reindex-- Rebuilds the search index. This can take a minute or two and is only necessary when you've made changes (like permissions) (GM Only).<query>-- a collection of terms and modifiers to define what is important. See Search Query below for full details.
Search Query
At it's simplest, a Search Query is just a list of words you're interested in:!search sun blade
Terms
There are 6 basic ways to enter terms:
term-- Just a bare word will rank as normal.+term-- Prepending with+marks a word as important, and it will be weighted double.-term-- Prepending with-marks a word as detracting, and it's weight will be subtracted, lowering the document's score.*term-- Prepending with*marks a word as required, and a document will be rejected if it doesn't have a match.~term-- Prepending with~marks a word as prohibited, and a document with a match will be rejected.term^N-- Appending a^with a number will multiply the weight of a term by that number. Numbers can be proceeded by a - to make the term detract, and may have a decimal place. The leading zero may be omitted.
!search knight *king ~queen +prince -princess chamberlain^1.1 maid^-.3
This will search for knight, require a match for king, reject any document that matches queen, reduce the score of for matching princess, rank chamberlain 1.1 times higher than normal and reduce the score for matching maid at about 1/3 the weight.
Prepended modifiers can also be combine with direct weighting:!search *king^.5 throne
Must match king, but at half it's relative weight. throne is weighted normally.
Fields
You can specify search terms to apply only to a specific field using thein:<field> syntax:!search in:bio parents
Searches for parents in just the bio field.
The in:<field> syntax only applies to the next term listed.!search in:bio parents dragon
Searches for parents in jut the bio field, and dragon in any field.
If you want to search for multiple terms in a field, you can surround them in parenthsis:!search in:bio ( parents siblings brother sister )
Search for parents, siblings, brother, and sister in the bio field.
Anywhere you place terms, you can apply modifiers:!search in:bio ( parents siblings +brother sister^3 )
Additionally, you can apply the same modifiers to the field name to apply them to all the specified terms:!search in:bio^2 ( brother sister ) dragon
Both sister and brother in the bio field are weighted double what dragon is in all fields.
You can specify different weighting for terms in a field and out of it:!search in:bio ( +dragon ) dragon
The most spcific rule is applied. dragon in bio will be ranked double what dragon elsewhere is.
If you modify the field and the term, they are combined in the ways you would expected:!search in:+bio ( +dragon wyvern ) dragon wyvern
dragon in bio is x4, wyvern in bio is x2, dragon and wyvern elsewhere are normally weighted.
Categories
You can specify search terms to apply only to a specific category using theon:<category> syntax:!search on:handout gemstone
Search for gemstone in all fields of handouts.
Just like with in:<field>, you can use parenthesis to group terms:!search on:character( knight paladin )
Search for knight and paladin in all fields of characters.
Also like fields, the category can be modified just like terms and passes the modifications down the same way.!search on:character^1.2( knight paladin ) knight paladin
knight and paladin are ranked x1.2 when on a character.
You can nest in:<field> rules in on:<category> rules.!search on:character^1.3( in:name +dragon dragon ) dragon
dragon in character name is worth x2.6, elsewhere on character is worth x1.2, and anywhere else is worth normal.
You can get as complicated as you like with this.!search on:character( in:name( dragon -wyvern ~snake) +snake in:gmnotes^3 secret ) on:handout( *treasure *gold )
Search for characters with dragon, preverably not wyvern, and flat out not metion of snake in the name, but rank higher for snake elsewhere and secret in gmnotes is x3. Also include any handouts that mention both treasure and gold.
Results
The results are sorted based on the combination of the weights of all the terms they matched, then the top 30 are whispered to the user in the chat.Each result row contains a circle with an H for handout or C for character, followed by the name of the matching document with the folder it is in in smaller lettering above it. The name of the document is a link that will open it. At the top right is the total score for the document. Along the bottom of each row are the terms the document matched, with the number of unique fields it matched in, followed by the portion of the score it contributed. This is followed by a list of fields with the number of unique terms matched and the contribution to the score. Looking at these details can help you fine tune your search.
Building the indexes in Storm King's Thunder takes around 96 seconds.
Building the indexes in Curse of Strahd takes around 66 seconds.
Searches are nearly instantaneous!
Github: https://github.com/shdwjk/Roll20API/blob/master/Se...
