Co de Ha rm on ics

mastering the routine play

Build a solution 

Start with a solution. Show the UI. Describe the components. And ask yourself – How did I get here? What have I done?!

(David Byrne)

What is a search experience?

An Algolia search experience is what an end user sees on the screen. Analyzing the end user experience helps you understand what we want to build, but it doesn’t help you understand the work that goes into building it.

Behind every search experience is another kind of experience: the Developer eXperience (DX) and the Business User eXperience (BuX). By providing great DX and BuX, Algolia ensures sure that its customers have it easy when developing a search experience. 

This document is about building a search experience. We organize it in the following way: we trace the main steps that all customers must follow to build a search solution.

Web Development

In the real world, there is no standard workflow for developing a website. Some companies will build the UI before plugging Algolia into its finished website. Others will start with their product data – seeing how to search and make sure that results are good, before building the search UI around that. Still others will do these in parallel. 

What matters is that all the necessary steps are done at some point in time. There are 4 steps to build a solution:

  • Data: Formatting and sending product data to Algolia, creating an index.
  • Configuration: Optimizing the data and engine-level settings.
  • UI: Building a vibrant front-end search experience.
  • Analytics: Tracking user behavior to continuously improve the search experience and ROI. 

We’ll begin with the data, then move to some essential configurations, then UI, then Analytics. We emphasize throughout that: this cycle is indeed a cycle that continues to roll – every step is revisited with feedback from the other steps, continuously evolving the solution to create the best experience. 

Data (Indexing)

The data is the customer’s data. Maybe this is obvious, but Algolia has no data. It has an empty space on its servers for customer data. The data that customers want their end users to search for must be located on Algolia’s servers. And for this, they must send Algolia its data in a process called Indexing

Indexing involves connecting to the server (via the API or Dashboard) and sending data. Once that’s done, the data is searchable. 

Customers can use the Dashboard to index their data, which is convenient for testing and troubleshooting, but definitely not the norm for sending large amounts of data. Live production data needs to be indexed by the API. The API allows developers to write a program that fetches their company’s data (located on their own databases and servers) and sends it to Algolia.

Let’s repeat that: Customer data needs to be fetched from the customer’s own databases. We say database but it could be a spreadsheet or an XML / CSV file or any other kind of source. This is what we call the Customer’s source data.

The kind of the data on the customer side is unimportant. What matters, during the Data stage, is the following:

  • Customers themselves have to create their own process (a “script”) that will find and collect their data on their computers;
  • Once the data is thus collected, they need to pick and choose the right information and reformat it into a new format called JSON (pronounced Jason). Jason is a human readable way to format data that Algolia accepts..
  • Once Jason is ready, it’s time for the customer to send (upload) it to Algolia. This is what we mean by Indexing.

So the first step is done – Algolia now has the customer’s data. The customer, at this point, should be able to test the search, to see if their upload worked. They can use either the Dashboard or the API. What they are testing is to see if Algolia has all the records they uploaded, and that all the information in their records is correct.


Once that’s all done, the customer needs to keep thinking about its data, but in how they configure it. Configuration overlaps with Data. What do we mean by that? 

Configuration can be broken down into 3 parts: 

  • Data-centric configuration
  • Engine-level configuration
  • UI-centric configuration

Data-Centric Configuration

The first step for any client is to focus on the data-centric configuration, to make sure that the attributes they sent in their dataset are well chosen and used properly. Concretely: 

  • They need to select the attributes they want to use for searching: these need to be configured as Searchable Attributes. Title and Description are examples. 
  • Some are for ordering records: these need to be set up as Custom Ranking. Number of sales, or highest-rated are examples.
  • Some are for filtering: these need to be set up as Attributes for Faceting. Brand and color are examples.
  • The rest are for display (image) or for technical purposes (objectID). 

Actually, they overlap. Many attributes are good for both search and display (title, short description), and some are even good for search, display, and filtering (brand, color). 

Keep in mind, this implementation process is iterative. Customers will return to data and configurations, making small adjustments, as they move along in their implementation.

Build the UI

Once the data is set up properly, it’s time to start thinking about the UI. There are many examples of a great search UI. The best have a central search bar and an easy to read, vibrant set of results, with on-screen filters, pagination, and highlighting. Even better, a federated search with multiple kinds of data on the same screen (for example, Amazon’s books, films, appliances, and clothing showing up on the same results page, side-by-side, all matching the same query term).

Some of these options get us back to Data – How do we set up the data, for example, so that there are more filters? How about creating multiple kinds of data for the federated search? UI decisions also take us back to Configuration – the UI-centric ones, like pagination, and highlighting. Additionally, some configuration decisions are both data and UI – like on-screen faceting.

Once we’ve iterated back and forth between data, config, and UI, the website can be built. We offer developers out of the box tools (InstantSearch) to build a world-class search experience, whether it be on the web or mobile. With IS, developers need only focus on the design of the page, IS does all the work in connecting and communicating with the Algolia servers. Developers can also choose to use their own technologies, building everything from scratch. In either case, a solution is nothing without a great UI.

Once we have built the UI, and everything is set up, we’re ready to go live. Let’s make sure:

  • We have great and complete data; 
  • We paid careful attention to the essential configurations;
  • We tested our relevance and ranking; 
  • We built a vibrant UI for the end user. 


What’s left? Analytics

Analytics. You need to know what search does for your business. You want to find the relationship between Search and ROI. You want to quantify the business value that search brings. Only Analytics can help you do that. 

But Analytics has another purpose – one directly related to implementation. It’s the 4th step: Analytics brings us back to the Data <-> Config <-> UI iteration process. By tracking usage, over days, months, and years, we can analyze user behavior and continuously improve the experience, making sure that every query and click brings the most value. When looking at Analytics reports – for example, the statistics of “no results”, or “top searches”, or “most common misspellings” – and many more – all of this can help the customer reflect on their earlier decisions in the Data or Configuration steps. We can reformat data, add new tidbits, remove some data, and configure some of the more difficult “engine-level settings”, such as enable or disable typo tolerance, switch precision with attribute,  or turn on plurals and stop words.

That’s it. 


Waiting Room

“The sky is gray.”

Sound reverberated in a large space of oddly arranged seating but he was sitting so quietly. I had noticed him even before entering the room. He was the kind of fixture I would have expected to see in such a place as this. He could have been waiting for a train, or sitting in a large government building. But it was here, and I guess a therapist’s waiting room too has its place — and a disquiet that sometimes gets played out even as we wait.

“The kind of gray,” he continued, “that colors everything with the threat of annihilation. Perhaps that’s only a feeling. Not the gray but the tragic end.”

Continue reading “Waiting Room”

Ten Years Younger

The movie was over, the credits still rolled. We all moved towards the exit with just enough light in the theatre to scroll over the darkness. No more movie magic, no more colorful faces, no dialogue; we were only a vast quiet of hesitant voices and shuffling shoes, a sleepy movement brushing against a dirty and drab carpeting.

My brother was ahead of me in the double file, momentarily paired-off with one-half of another couple. He eventually slowed down to join me, but we exchanged no words, no look. I was eight, he was eighteen. I could feel a sudden chill from the outside coming from the open doorway, sucking us out of the dark and spitting us out onto the sidewalk. I turned my head, but not quick enough. The theater had already transformed itself into an imposing concrete wall. The night air hit us. We were on our own.

Continue reading “Ten Years Younger”

Exploring Technical Documentation Space

Awe. Like I am part of something insanely large. Touching infinity.

We travel in space. We are in space, and we and everything in it are moving.

To see this, you need to get out of the city and into the dark country. Lay back on the ground and face the sky.

It takes about 30 minutes for your eyes to adapt.

And then feel the movement.

Continue reading “Exploring Technical Documentation Space”

a baseball kind of hero

He was a boy, a baby really, not more than a few months old, still in diapers, a pacifier dangling from his mouth.

She was wearing a baseball cap that collected in its palm a bundle of blond curls with some red highlights.

He stood at the plate, legs apart and knees slightly bent, his bare toes solidly sinking into the drenched dirt.

The rain fell in puddles, there were no boys left in the field. She stood in the center of the mound ready to sink to the bottom of a river to throw him a ball. The sweat and dirt on the girl’s knuckles were eating away at the already beaten leather of the baseball. The ball was dry at its core, heat-dried from the girl’s touch. She was fired up but bathed in the pouring rain. Her bare toes tore away at the earth beneath.

Poised on his tiptoes, the boy balanced a very large wooden bat.

Continue reading “a baseball kind of hero”

Create a website or blog at

Up ↑