API Reference / API Parameters / similarQuery
Type: string
Engine default: "" (returns all records)
Parameter syntax
'similarQuery' => "query"

Can be used in these methods:

About this parameter

Overrides the query parameter and performs a more generic search that can be used to find “similar” results.

Usage notes

similarQuery should be constructed from the tags and keywords of the object you are trying to find related results to.

similarQuery is not automatically generated. You need to select which keywords you think would be useful. For example, a similarQuery for a movie could use the genre, principle actors, and tags attributes. After extracting information from those categories, you might end up with a similarQuery that looks like: “Romance Comedy Gordon-Levitt NY”. Check out the examples section for a more detailed walk-through.

Use of this parameter changes the search settings in four ways:

  1. Sets queryType to prefixNone (no prefix match).
    • matched prefixes are not counted as word matches.
  2. Sets removeStopWords to true.
    • stop words like ‘the’, ‘a’, ‘an’ are removed.
  3. Treats all remaining words (all non-stopwords) as optional.
    • objects that match any word in similarQuery will be returned.
    • note, your similarQuery will likely invoke the caveat behavior of the optionalWords parameter!
  4. Sets words to be the first ranking criteria
    • the number of exactly matching words is the first ranking criteria.

Note, because the optionalWords parameter (which is leveraged by similarQuery) can yield a high volume of results, you should add filters and optional filters to your similar searches.

Examples

Search with similarQuery

This example demonstrates the construction of a similarQuery from a returned movie object. The movie, “Fargo”, is represented by the follwoing JSON:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "title": "Fargo",
  "year": 1996,
  "director": "Joel Coen",
  "cast": [
    "Frances McDormand",
    "William H. Macy",
    "Steve Buscemi",
    "Peter Stormare",
    "Harve Presnell"
  ],
  "genres": [
    "Comedy",
    "Drama",
    "Crime"
  ],
  "tags": [
    "black-comedy",
    "americana",
    "coen-brothers",
  ]
  "objectID": "97327292",
  "budget": 7000000
}

From this object, on the backend, we generate similarQuery by extracting words from genres, cast, and director. We turn these extracted words into a long query string.

1
similarQuery = "Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen"

Despite the long query string, this will return many results because all words are optional. Therefore, we should add a filter to make sure we get only the best results. Lets filter on release dates that are within five years of Fargo’s release year: 1991 to 2001. To accomplish this we want to add a filter on the year attribute.

1
filter = "year:1991 TO 2001" 

finally we put it together into a search call.

1
2
3
4
$results = $index->search('', [
  'similarQuery' => 'Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen',
  'filters' => 'year:1991 TO 2001'
]);

Did you find this page helpful?