How Mixedbread Transformed Our Search
When we built the Effect documentation site, our search layer was powered by Pagefind, which is the default search provider built into the Starlight Documentation Plugin for Astro. Pagefind offers efficient, client-side full-text indexing and low bandwidth usage for static sites. It served us well as a straightforward, zero-infrastructure solution allowing us to index our content at build time and ship small chunked search indices to the browser while users searched for the content they were interested in.
But over time, we hit the limitations of pure keyword search:
- Inability to handle semantically rich search queries from our users (i.e. “Tell me how to use a Scope in Effect”)
- Problems surfacing relevant content when query phrasing diverges from the source content
- Limited ability to incorporate document metadata into ranking and filtering
Luckily, we were fortunate enough to be introduced to the folks at Mixedbread, an applied research lab dedicated to building next-generation retrieval and memory systems for AI. They offered to let us use their platform to solve the problems we were having with search on our docs website.
I have to say, the improvement in search after integrating Mixedbread into our docs search was immediately noticeable. Search results instantly felt more relevant, contextually accurate, and tailored to the query that the user entered.
We’ve been running a Mixedbread-powered search experience on our docs site for about a month now, and with the significant improvement we have observed in search result quality and relevance, we have no intention of going back.
What made Mixedbread stand out to us was how simple it was to get started building out a vector store for our docs content. In just a few minutes I was able to setup a vector store via Mixedbread’s dashboard. Then, using the Mixedbread CLI I was able to sync and ingest all our docs content into the store in a single command. That allowed us to not have to worry at all about indexing our documentation content and instead focus on building out the frontend for our documentation website’s search experience.
Given how simple it was to setup and hydrate our main Mixedbread vector store, we would like to also add support for generating “preview” vector stores for pull requests made to our documentation site. This way, contributors can test out whether or not changes made to the documentation are properly surfaced by search results before ever pushing those changes into production.
Switching from Pagefind’s keyword-centric index to a vector-embedded search backend unlocked several improvements:
Semantic Understanding
Our previous search experience could not handle semantically rich queries from our end users - e.g. “What is the purpose of the Layer data type”. Mixedbread’s vector store and retrieval APIs allow us to go beyond the literal query entered by the end user and instead surface results that are more relevant to the user’s intent.
Metadata-Aware
Because Mixedbread supports ingesting metadata along with content, we can tag documents with additional attributes such as version information, last update time, source module name, or relevant categories.
In addition, Mixedbread is able to automatically generate certain types of metadata for you based on the type of document being ingested. We took advantage of the metadata generated by Mixedbread for our Markdown content to create anchor tags for subheadings in our documents. This allows us to let the end user link directly to the page and heading that a search result points to in our documentation so they can immediately access the content they need.
Low Latency
Despite performing search across our entire Mixedbread vector store, re-ranking search results, and returning them to our client with every query, the response time of our docs search has remained exceptionally fast.
As mentioned before, our docs site is built using the Starlight Documentation Plugin for Astro. To provide a seamless experience, we built a small, custom Starlight Plugin which replaces the default Pagefind search. This plugin overrides the Search component that comes out of the box with Starlight with a custom MixedbreadSearch Astro component. The MixedbreadSearch Astro component sends the user’s search query to an Astro API route which executes the search against our Mixedbread vector store. Results are returned to the client and rendered by the MixedbreadSearch Astro component.
If you’re curious and want to learn more about our custom Starlight plugin for Mixedbread, you can view all the code on GitHub.
As a consumer of our docs, what you’ll notice from the search experience is simple:
- More relevant results
- Fewer “nothing useful found” dead ends
- Easier discovery of deep, advanced topics
You’ll get better search without having to change how you ask questions.
For us as maintainers, it has allowed us to surface more relevant content to our users regardless of how large the body of Effect knowledge grows! This also let to the related benefit of reducing the number of support requests we have needed to address about the quality of the search experience on our docs site.
Mixedbread is now publicly available! If you have a docs site, a knowledge base, or any content corpus you want to make more intelligently searchable, head over to mixedbread.com and give it a spin. Our search got smarter - yours can be too.