One of the biggest complaints I hear about Mastodon is that its local search is unusable. It certainly was. But not anymore. Now it’s quite powerful, if you know the basics. So here’s a primer for you. Because I love Mastodon, you, and good UX.

A few notes before we begin:

• Mastodon is decentralized. This means every instance has its own data that may or may not be known to yours. Search is relative to known data (more on this from Fedi.tips).
• This primer is in reference to the core search functionality in the main UI, which is what you see when you connect to Mastodon in a desktop or mobile browser. There are a number of mobile apps, each of them treating search wildly different, including the official Mastodon app.
• What I share here will undoubtedly change. These tips are ephemeral. I’ll do my best to edit this with updates as I noticed changes to the UX/UI. If you notice something I’ve gotten wrong, please reach out to me. I’m friendly and willing to correct mistakes.
• People can opt-in/out of search. So some folks and their posts aren’t findable this way. Mastodon developer Renaud Chaput has more info on this.
• Servers need to enable “Elasticsearch” for full-text search to be an option. If full-text search doesn’t work for you, your server admins haven’t enabled this.

Search anatomy

Mastodon search can be simple or robust. The former is type-and-go, like any search engine. The latter enables you to really fine-tune what you’re seeking, by optimizing specificity.
Fig 1: search anatomy
You can search by word(s) and then, if you want, further refine the results using the following options:

1. Has: the post includes media, a poll, or an embed (also usable with has but not in the UI: image, link, video, and audio)
2. Is: the post is a reply or marked as sensitive
3. Language: the actual ISO language code (i.e. Eng or En)
4. From: the username of the account (“from:me” works for finding your own posts)
5. Before, during, and after: ISO dates (YYYY-MM-DD) which aren’t intuitive but are functional (more on ISO date formats)
6. In: the post is global or I’ve created/interacted with it (favorited, boosted, or replied)
7. Operators: you can combine any of these, so a + operator isn’t necessary. But you can exclude words or options with a – operator. (i.e. “-word” or “-is:type”)

Search type

Mastodon supports full-text search or hashtag search. Each yields different results, but there is some overlap, which is helpful. (Read more about hashtag accessibility.)

Both types can target profiles, hashtags, and posts. Or a query can simply be submitted, and the results will be grouped into each of these. They match as follows:

1. Profiles: returns all accounts who have the search query in their bio or their username
2. Hashtags: returns a list of case-insensitive hashtags that match or are close to the search query (i.e. “product design” returns #ProductDesign and #Product Design, while “typography” returns #Typography and #TypographyInTheWild)
3. Posts: returns every post that includes the search query

As mentioned, there’s a lot of overlap. But there are good reasons to use one over the other.
Fig 2: full-text search
The main reason to use full-text search is because it yields a larger pool of results. The ratio of words vs hashtags in a post is almost always in favor of the former (at least they should be). And some folks use hashtags scarcely or simply don’t use them at all.
Fig 3: hashtag search
Hashtag searches are more explicit in what they return, even though they return results in the same way. The primary reason to search by hashtag is to tap into that shared ecosystem.

“#DogsOfMastodon” won’t return the same thing as “dogs of Mastodon.” The former will return Nicole Sandler’s account (Laffy) because she uses the hashtag in her profile (see fig 4 below). The latter will not, because she doesn’t use that phrase in her profile.
Fig 4: profile match
So it’s a little nuanced, but there is a difference between them. The one thing that full-text search offers that hashtags do not, is the option of exact matches for usernames. In fig 2 above, you’ll see a “quick actions” option for “go to profile @typography.” Because there is an account by that name, you can go straight to it.

You can also go straight to any of the targets by choosing one from the “quick actions” options. If you want to explicitly find posts matching your search query, you don’t have to key/submit. You can key your term then select your target.

Keying “#DogsOfMastodon” and submitting will return the “all” results, grouped by target. If you’re only interested in posts you can type your query and then choose “go to hashtag” or “posts matching” (see fig 5 below).
Fig 5: results target

Targeting hashtags vs targeting posts

The UX for this is quite ambiguous. You’d think that both would yield the same results, because if a hashtag is used in the post it would be relevant in either scenario. However, that’s not the case.

So why have both? It’s complicated…

Choosing “go to hashtag” from “quick actions” will take you to the actual URI for that hashtag (i.e. “#DogsOfMastodon” returns /tags/DogsOfMastodon on my instance). So it’s not necessarily search results, per se, but a link to that hashtag.

Yes, hashtags have their own URIs. There are two reasons for this. First, there’s metadata associated with hashtags. Second, and more importantly, you can follow hashtags on Mastodon in the same way you can follow accounts. (See these in fig 5.)

Note: choosing “go to hashtag” from the menu is not the same as choosing “hashtags” from the target tabs. The latter simply shows you a list of hashtags matching and related to your search query.

If you’re searching for posts, I strongly recommend using the “go to hashtag” instead of “posts matching.” The hashtag view yields far more results than the latter.

In all or library

While most of the search options are intuitive, this one is not. But it’s simple once you understand it.
Fig 6: in all
In “all” is basically an open search through all posts. I haven’t been able to find the real purpose for it, because it simply returns posts that match the query. So I believe it’s not really helpful.
Fig 7: in library
However, in “library” can be quite useful. Choosing this means it only returns posts you’ve interacted with. If it’s your post or someone else’s that you’ve favorited, boosted, or replied to it, it’s in your “library.” As seen in fig 7, the results show a reply that I favorited as well as one of my own posts.

With great power comes great…results

The real power in the Mastodon search is being able to mix and match the search options.

As mentioned, searching in Mastodon can be really simple: type and send. But using the search options for a detailed search is very powerful.
Fig 8: mix and match
Want to find a poll you posted two years ago? Easy (see fig 8). Want to find a reply to you from someone that may have included a link? Easy. Connect the dots and create your recipe. Mastodon search has you covered.

Conclusion

Mastodon didn’t invent anything new here. In fact, these options may look familiar to you. But robust search is relatively new to Mastodon. It’s a game changer that fixes what was one of the most frustrating aspects of Mastodon. It’s something that people have (rightfully) complained about en masse.

New to Mastodon? Don’t be a stranger. It’s the best social network you never knew you needed. If you’re ready to dive in, find me on mas.to and I’ll be happy to help you find your way.

Thanks to the following people, who helped me with tips and recommendations.

• Stn for inspiring me to write this piece and offering some tips
• Katzentratschen for a handful of additional resources
• Delta Wye for sharing some oddities with case sensitivity and spaces
• Claire Barnes for suggesting clarification on ISO date formats and additional resources
• Luca Hammer for recommending a note about operators

Happy searching!

#Mastodon #Fediverse #Search #FediTips #MastodonHelp #MastodonTips #SocialNetworks #Guide #HowTo

Like this? Find out when I publish new work.

I’m Mark Wyner, an activist, dad, husband, Designer, writer, public speaker, and Mastodon moderator. If you want me to write for you or speak at your event please say hello.

Like this? Find out when I publish new work.

I’m Mark Wyner, an activist, dad, husband, Designer, writer, public speaker, and Mastodon moderator. If you want me to write for you or speak at your event please say hello.

Renaud Chaput

2023-08-24 19:17:43

To opt into your content being searchable, once your instance is upgraded to support this feature, head to the your profile, and the new “Privacy and reach" tag, then tick the "include public posts in search”.

We will try to ensure users know this setting exists, nothing 100% defined yet, but we may add a dismissible banner asking to review your privacy settings page.