similarQuery

A manually constructed query to find similar results based on shared attributes

Usage

• Build the similarQuery from relevant object metadata, such as tags, categories, or keywords.
• This query isn’t generated automatically. You must select meaningful terms manually. For example, a similarQuery for a movie could include its genre, key actors, and tags, such as: Romance Comedy Gordon-Levitt NY.

When specified, this parameter changes the search behavior:

• Sets queryType to prefixNone—turns off prefix matching.

• Enables removeStopWords—removes common stop words like “the”, “a”, or “an”.

• Sets Words as the first ranking criterion—results with more exact matches rank higher.

• Treats all remaining words as optionalWords:

  • Matches any (not all) of the words in the query (OR behavior).
  • Due to the broader match, you should apply filters to narrow the results.
  • Long queries may trigger specific behavior related to optionalWords with four or more words.

Example

Search with similarQuery

The following example demonstrates the construction of a similarQuery from a record for the movie “Fargo”:

{
  "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, use similarQuery to extract words from genres, cast, and director as a long query string. This search returns many results because all words are optional. To ensure you get the best results, add a filter on release dates within five years of Fargo’s: filter = “year:1991 TO 2001”

Current API clients

C#

var response = await client.SearchSingleIndexAsync<Hit>(
  "INDEX_NAME",
  new SearchParams(
    new SearchParamsObject
    {
      Query = "",
      SimilarQuery = "Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen",
      Filters = "year:1991 TO 2001",
    }
  )
);

final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    query: "",
    similarQuery:
        "Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen",
    filters: "year:1991 TO 2001",
  ),
);

response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "INDEX_NAME").WithSearchParams(search.SearchParamsObjectAsSearchParams(
  search.NewEmptySearchParamsObject().
    SetQuery("").
    SetSimilarQuery("Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen").
    SetFilters("year:1991 TO 2001"),
)))
if err != nil {
  // handle the eventual error
  panic(err)
}

SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject()
    .setQuery("")
    .setSimilarQuery("Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen")
    .setFilters("year:1991 TO 2001"),
  Hit.class
);

const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: {
    query: '',
    similarQuery: 'Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen',
    filters: 'year:1991 TO 2001',
  },
});

var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams =
      SearchParamsObject(
        query = "",
        similarQuery = "Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen",
        filters = "year:1991 TO 2001",
      ),
  )

$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['query' => '',
        'similarQuery' => 'Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen',
        'filters' => 'year:1991 TO 2001',
    ],
);

response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "query": "",
        "similarQuery": "Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen",
        "filters": "year:1991 TO 2001",
    },
)

response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(
    query: "",
    similar_query: "Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen",
    filters: "year:1991 TO 2001"
  )
)

val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        query = Some(""),
        similarQuery = Some("Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen"),
        filters = Some("year:1991 TO 2001")
      )
    )
  ),
  Duration(100, "sec")
)

let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "INDEX_NAME",
    searchParams: SearchSearchParams.searchSearchParamsObject(SearchSearchParamsObject(
        query: "",
        similarQuery: "Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen",
        filters: "year:1991 TO 2001"
    ))
)

Legacy API clients

C#

index.Search(new Query("")
{
    SimilarQuery = "Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen",
    Filter = "year:1991 TO 2001"
});

res, err := index.Search(
	"",
	opt.SimilarQuery("Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen"),
	opt.Filters("year:1991 TO 2001"),
)

index.search(
  new Query("")
    .setSimilarQuery("Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen")
    .setFilters("year:1991 TO 2001")
);

index
  .search("", {
    similarQuery:
      "Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen",
    filters: "year:1991 TO 2001",
  })
  .then(({ hits }) => {
    console.log(hits);
  });

val query = query("") {
    similarQuery = "Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen",
    filter = "year:1991 TO 2001"
}

index.search(query)

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

results = index.search(
    "",
    {
        "similarQuery": "Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen",
        "filters": "year:1991 TO 2001",
    },
)

results = index.search(
  "",
  {
    similarQuery: "Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen",
    filter: "year:1991 TO 2001"
  }
)

client.execute {
  search into "myIndex" query Query(
    query = Some(""),
    similarQuery = Some("Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen"),
    filters = Some("year:1991 TO 2001")
    )
}

let query = Query()
  .set(\.similarQuery, to: "Comedy Drama Crime McDormand Macy Buscemi Stormare Presnell Coen")
  .set(\.filters, to: "year:1991 TO 2001")

index.search(query: query) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}