Search Service

The most up to date version of this document lives in titanhouse-api.

Basic usage

The Search Service API expects the following payload shape:

{
    "Search": {
        "FilterCriteria": [

        ],
        "pageSize": 1,
        "page": 1,
        "sortBy": "last_name_sort",
        "sortOrder": "asc"
    }
}

Filters

FilterCriteria is an array of objects representing specific filter types. Each filter should have a fieldName corresponding to an existing Search Strategy and usually a values array, though each Search Strategy can change this and require different value shapes.

Some examples:

{
    "Search": {
        "FilterCriteria": [
            {
                "fieldName": "location_geo",
                "values": [
                    {
                        "distance": "5miles",
                        "lat": 38.992643722961276,
                        "lon": -77.10815248373024
                    }
                ]
            },
            {
                "fieldName": "org_industries",
                "values": [
                    {
                        "executive": true,
                        "value": 52289
                    }
                ],
                "includePast": true
            },
            {
                "fieldName": "clone",
                "values": [{
                    "label": "Dennis Arndt",
                    "value": 121097
                }]
            }
        ],
        "pageSize": 1,
        "page": 1,
        "sortBy": "last_name_sort",
        "sortOrder": "asc"
    }
}

Search Results & Matches

The Search API returns a data array of Titans. Each Titan object includes a matches property which represents every match for the filters provided. These match objects are output by the filter's corresponding Search Strategy.

Search strategies

A Search Strategy is responsible for forming the ElasticSearch query for each search filter, and also for formatting the match objects related to each query.

Generic search strategies, including the BaseSearchStrategy are located in src/elasticsearch/strategies.

Titan-related search strategies usually extend BaseSearchStrategy and can be found in the src/api/titan/full-search/strategies folder.

As a convention, search strategy files end in .search-strategy.js.

Writing a custom Search Strategy

A custom Search Strategy should extend BaseSearchStrategy and can override the following methods:

getMatchId() controls how the filter's matchId is formed, usually using some sort of ID value and the filter's name, i.e:

"matchId": "clone-121097"

buildEsQuery() should output the Elastic query for the filter.

buildMatches() should only be used in instances where the match objects need to be customized. clone.search-strategy.js is an example.

Search