Document advance search syntax

[seam345]

There is a lot of undocumented functionality in the search box, it would be nice to have a page describing the available functionality. Then maybe a button in the top bar that links to said page.

I'm not the best at writing but to get it kick started I have put down all the knowledge I have bellow.
From asking on discord I understand the category filter but the rest I guessed from src/controllers/krate/search.rs

Documentation draft (outdated, most up to date near bottom of discussion)

Advance searching

Searches can be filtered down further using the following syntax

Categories category:<category_id>

Categories can be filtered using their ID's. ID list can be found here or go to the category and find the ID in the URL. Sub categorys have the syntax <category>::<sub_category>

examples

• search "mqtt" crates in "no standard library" category = mqtt category:no-std or category:no-std mqtt

All Keywords all_keywords

Unknown functionality or syntax

Keyword keyword

Unknown functionality or syntax

Letter letter

Unknown functionality or syntax

User id user_id

Unknown functionality or syntax

Team id team_id

Unknown functionality or syntax

Following following

Unknown functionality or syntax

ID's ids[]

Unknown functionality or syntax

[Turbo87]

you can find a bit more information on these advanced search tokens in #4382 :)

[seam345]

Awesome thank you. I was a bit unsure if I should just edit my initial comment or make a new one with the updated documentation draft. For the idea of other people iterating on it, maybe we try keep an updated version as one close to the bottom post and make it collapsible if outdated.

After looking at #4382 I realised why just looking at search.rs was getting me nowhere. As a result I added a "Devs working on search" section so other people don't fall into the same pitfall as me, this may want to be a separate doc though or just mentioned elsewhere in the code.

I'll try looking into letter, user_id, team_id, following and ids[] soon. Then eventually submit a PR to add the page to either docs or a more user facing subpage on crates.io.

Advance searching

Search box

Both categories and keywords can be added to the search box to help filter down searches
Note: the prefix before : is case sensitive, everything's lowercase. After : is not case sensitive.

Categories category:<category_id>

Categories can be filtered using their ID's. ID list can be found here or go to the category and find the ID in the URL. Sub categorys have the syntax <category>::<sub_category> Note: searching multiple categories is not yet supported.

examples

• search crates in "no standard library" category = category:no-std
• search crates in "Drones" subcategory of "Aerospace" = category:aerospace::drones

Keywords keyword:<keyword>

There is no easily searched list of keywords, as it is a set of words defined by each crate, however you can paginate through the entire computed list here. You can also specify multiple keywords doing keyword:foo keyword:bar note this is an and operation not an or so each additional keyword will reduce the results further as a crates needs to match every keyword to display.

examples

• find all crates with keyword "cli" = keyword:cli gets ~2805 results
• find all crates with keyword "cli" and "asyc" =keyword:cli keyword:async gets ~12 results

examples

Both keywords and categories can be mixed and matched just make sure to have things separated by a space.

• Search for crate mentioning elegant print with keywords cli and async. Bellow searches are equivalent:
  • print keyword:cli keyword:async Elegant
  • keyword:cli keyword:async Elegant print
  • keyword:cli Elegant print keyword:async
• Search for crate in algorithms category and keyword random. Bellow searches are equivalent:
  • category:algorithms keyword:random
  • keyword:random category:algorithms

to learn (things I have yet to find out what they do)

bellow are a set of things in the backend api that filter searches I fount looking at src/controllers/krate/search.rs and have yet to investigate as to how they work

Letter letter

Unknown functionality or syntax

User id user_id

Unknown functionality or syntax

Team id team_id

Unknown functionality or syntax

Following following

Unknown functionality or syntax

ID's ids[]

Unknown functionality or syntax

Devs working on search

Looking to work on search to add or change functionality, you may want to read this first.
The front end search box is a bit disconnected from the back end search, steps are:

• user types in search
• JS takes query
  • adds to url to keep refresh working
  • Parses query formatting for the crates.io/api
    • query is parsed in app/utils/search.js
    • I need to find out where the other things are parsed, like the sort by
• crates.io/api call is made
• Rust handles search query and returns a list of crates, src/controllers/krate/serach.rs
• JS loads/displays the returned api (Rust) result

Note: if looking at url and search.rs q is not equal and a bit of a false friend e.g. url https://crates.io/search?q=category%3Ano-std%20mqtt&sort=relevance puts "category:no-std mqtt" in search box and makes this api call https://crates.io/api/v1/crates?category=no-std&page=1&per_page=10&sort=recent-downloads so to search.rs q=mqtt but to search.js q=`category:no-std mq

[nyurik]

Is it possible to combine multiple search items, e.g. if i want to search for #sqlite AND #async keywords. Currently the number of results is overwhelming and mostly irrelevant. Any documentation page would be awesome, even if its a markdown page in github, and crates.io points to it. Thanks!

[seam345]

Yes so in your specific example you can put keyword:sqlite keyword:async in the search field to narrow down by both sqlite and async tag.

[erlangparasu]

how to find library only crate? or find binary only crate?

[ToBinio]

thoughts about making the documentation of seam345 a bit more official though adding a .md file to the docs folder and adding a link to it in the footer of the website?

[Turbo87]

I'm not sure if the footer is necessarily the right place for this. Might be better to put it somewhere closer to the search box, but as long as we don't have inline search results I'm not sure where to put it there either 😅

[ToBinio]

What do you think about adding a dropdown menu next to the Browse All Crates

there could be the options to Browse all Categories, Browse all Keywords, and something like Advance search info which would link to the markdown file.

this is similar to what is proposed in #1555 | #4958