Clarify/fix helper.derive docs

[timkelty]

Trying to use a derived helper, a couple of things got me hung up from the docs.

I wanted my derived helper to search on a new index. The helper.derive function states The signature of the function is SearchParameters -> SearchParameters. However, there is no mention in the docs of a setIndex method for SearchParameters (though it seems to work, and what I need to use).

Furthermore, the docs refer it firing the results event, when it should be result. PR here: https://github.com/algolia/algoliasearch-helper-js/pull/476

[bobylito]

My bad, I need to rework the doc and make the SearchParameters more exhaustively documented. Thanks for reporting!

[timkelty]

np, thanks. I've managed to grind through it now, but an example of a multi-index query w/ .derive in the docs would be excellent.

[bobylito]

Ok that's noted thanks!

[thomo13]

@timkelty any chance you can share your solution? I'm also starting to look at using this feature, and as you mention the documentation is a little sparse.

[bobylito]

@thomo13 let me know if there is something that you don't understand, that would be of great help :)

[thomo13]

Well at the risk of sounding somewhat stupid I'm not even sure if this can help me to accomplish what I want to do.

Basically I have some fairly large docs, so to keep the size under control I'm using ID fields in one index to reference documents in a different index.

One of my users has just requested a filter on indexA based on the status of a related item in indexB. I'm not sure if this is something the derive function can help with, I was hoping for an example of some kind so that I might wrap my head around how it works.

[timkelty]

@thomo13 sure!

My scenario:

• A trips index search (in this case with Geo-Search params). These are displayed as "cards" on the page.
• The derived search is on the locations index, which we place as map (Leaflet) marker pins.

A super-simplified version looks something like:

helper
.setIndex('trips')
.setQueryParameter('insideBoundingBox', getGeoFilterParam('insideBoundingBox', map));
.search();

locationsHelper = helper.derive(function(searchParams) {
    searchParams = searchParams
    .clearRefinements()
    .setIndex('locations')
    .setHitsPerPage('1000');

    if (refineLocations) {
      searchParams = refineLocations(searchParams);
    }

    return searchParams;
});

What's nice about this is my derived search still inherits the params from the original, so it is also geo-filtered. clearRefinements is there because I also have a bunch of other facet/filtering widgets that can filter trips, but I never want locations to be filtered, except by geo. I also always want to show as many pins as possible, hence the setHitsPerPage('1000').

The part I wrestled with initially was understanding that all the SearchParameter setters return a new instance, and that is what you need to return from the helper.derive callback.

Meaning that this won't work, because the methods are not mutative:

helper.derive(function(searchParams) {
    searchParams
    .setIndex('locations')

    return searchParams;
}

From the docs:

SearchParameter is an immutable class. Each setter method returns a new instance with the modification, and does not modify the object it is called on.

In actuality this is all being done via a custom instantsearch widget. I'm happy to share that, but there's a lot more going on there too, so I'll start with this.

[bobylito]

The derive feature helps create several searches using a single search state. In practice this means that you can create two independent searches at the same time that can target different indices with different parameters. The derived request is not based on the results of the main, it is just based on the same original parameters.

For example, I have an ecommerce website two indices with two indices products_relevance (products are sorted by relevance) and products_best_selling (products ordered by sells). I can use the derivation to query both of them at the same time to display both the product that are more likely to be bought by the user and also the best selling.

var helperMostRelevant = algoliasearchHelper({}. 'products_relevance');
var helperBestSelling = helper.derive(function(searchParameters) {
  return searchParameters.setIndex('products_best_selling');
});

helperMostRelevant.on('result', function(content) {
  console.log(content.hits);
  // Displays the results for the most relevant results
});

helperBestSelling.on('result', function(content) {
  console.log(content.hits);
  // Displays the best selling results
});

helperMostRelevant.search();
// This triggers a search in each indices

What I understand of your use case is that you want to use the values of one of your search to do searches in another index. This won't be possible here because the requests are executed in parallel.

[thomo13]

Thanks both for your replies.... I guess ultimately this isn't what I was looking for, but interesting nonetheless

I guess my options are 1) replicate the information across the indexes or 2) make two requests and use a disjunctive facet to filter the final result set...

[bobylito]

@thomo13 Feel free to drop a comment / request for feedback on your use case directly in the algolia community forum :) Lots of helpful people around there :)

[jeerbl]

Struggled to find some docs too, glad for this issue honestly :)

Hope this will make it to the official docs and examples some day soon.