Search Guide

Search is all about finding documents.

A document is an individual JSON object.

When you add data into your Engines, you are taking database or backend API objects and indexing them.

But what does it mean, to index?

To better understand this, we will look no further than a JSON object:

{
  "name": "SuperObject",
  "authors": "Examplio McDemonstratio",
  "downloads": "98765",
  "info": "A stunning look at potential."
}

That is one object. Your datastore will likely contain many.

During indexing, your set of objects, of documents, is evaluated to develop a schema.

The keys are translated into Fields.

The values are, by default, given the type of text.

Prior to your data being indexed, the schema is created:

Each document that you index can now be considered part of a set of data.

This changes the objects in a small way:

{
  "id": "1234",
  "name": "SuperObject",
  "authors": "Examplio McDemonstrate",
  "downloads": "98765",
  "info": "A stunning look at potential."
}

Each one now contains an id, this id is how your documents are known to your Engines.

By belonging to a defined - though still flexible - schema, the Engine can get deep into its analysis of the documents.

The end result is the ability to search vast sets of objects, of documents, with great precision.

If you are the visitor, then you arrive at an application, seek out the search bar or search box, or magic box, enter some text, then hit enter. If search is fast and relevant, then they click on a result, their experience continues and they consume the content, purchase the project, or accomplish whatever it was they sent out to do.

If you are the developer, then you develop applications that access a robust set of APIs. You can access the APIs via an official client, like Python, Ruby, JavaScript, NodeJS, or Java. Or, you can weave in whatever sort of programmatic brilliance that you can dream up.

The visitor has it easy.

They are not aware of the deep logic that is happening below the interface with which they interact.

The act of searching, in its most simple form, is a request against an Engine wherein the document they seek is indexed.

Example - Performing a simple search.

curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/ruby-gems/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-qcqrj73hmom796c98r22zeao' \
-d '{
  "query": "search"
}'

It is a big difference between returning something and returning the right thing.

The name of the game is relevance.

When we make a request, the Engine will send a response object in return.

The response object contains a nested _meta object with a score key.

The value of the score key is the relevance.

Consider that we host an application for finding useful RubyGems.

The best search Gem of all - somehow, even better than App Search - is Searcheror Supreme.

It is popular.

If we had basic search, a visitor querying for search would return Searcheror Supreme as one of the last results.

That can lead to a poor experience - we want them to find the best Gem for their query.

The result of the search query would be:

{
   "name": {
     "raw": "Searcheror Supreme"
   },
   "id": {
     "raw": "1334"
   },
   "authors": {
     "raw": "Doctor Odd"
   },
   "downloads": {
     "raw": "421321431"
   },
   "info": {
     "raw": "A mind-bending experience of reclamation from the Ether. Not compatible with Dormammu Exiler."
   },
   "_meta": {
     "score": 4.986149
   }
 }

The relevance score under the _meta key is so low, a mere 5! Why is that?

By default, the Engine would take a uniform look across all fields for the keyword sent along with the query.

The word search appears only once, as a part of the name Searcheror.

Despite being the most popular and relevant Gem, it is buried under results that use the word search more often.

This is not ideal! But this is how most search functions work.

To go deeper, you must write sophisticated algorithms.

You would need to solve challenging data structure problems.

But you already have a million things to build.

Managing these deep search complexities is the problem solved by App Search.

There are many different endpoints to help you craft a fast, imaginative and useful search experience.

Explore the documentation to learn more.

The meta key will be a JSON object containing information about the result set, such as:

The Internet offers information.

A product, a thought — whatever it may be, search can get people to the things they want, quicker.

The faster they get there, the more likely they are to have an enjoyable experience and help you accomplish your business goals.

You are now familiar with the basics of search. Next, you can apply powerful tools to provide a relevant and valuable search experience. If you want to start polishing up how results appear, improving relevance and meeting business goals in the process, consider reading about Curations and Relevance Tuning. If you want to see how your users search, dive into Analytics. For the nitty-gritty details on the Search API, we have the Search API Reference.