search-api

The search-api bundle provides an API for searching on a set of stores.

The API of this bundle is described in detail in the API documentation.

Usage

Bundles should inject the search-api.SearchService to trigger searches:

"components": [
    {
        "name": "MyComponent",
        "references": [{
            "name": "searchService",
            "providing": "search-api.SearchService"
        }]
    }
]

Use the service's search() method to search for items:

const result = searchService.search("a query");

Use cases

Registering stores for searching

To register a store with the search-api bundle, add the value "search" to the useIn property. By default, all registered stores are searched by the search-api.SearchService implementation.

Additionally, the store must fulfil the following requirements:

It must have a unique id value.
It must support the Complex Query Language (at least the $suggest operator must be implemented).
It must define the required properties from the following table.

Note: these properties may be defined either on the OSGi Level (as service properties) or directly on the store instance. If both ways are used, the service properties take precedence over instance properties.

Supported store properties

Property	Type	Required	Description
`id`	String	yes	The store's unique ID.
`title`	String	no	The label for results obtained from this store. Defaults to `id` if not specified.
`searchAttribute`	String	yes	The attribute name to query against.
`searchLabel`	String	no	The label for search results. This can be either an attribute name or a string template, e.g. `"title"` or `"${city_name} (${zip_code})"`. Defaults to the search attribute.
`searchPriority`	Number	no	The search priority of the store. A lower value indicates a higher priority. The default priority is `50`. The value is evaluated by the `search-ui` bundle.
`searchCandidateCount`	Number	no	The amount of result candidates fetched during a search. For these result candidates a score is calculated to produce best matching results. If the value is `0`, the algorithm is disabled. If the value is greater than 0, the exact amount of candidates are requested. See the section `Client-side score` for more details.

Property names of the omnisearch bundle continue to work on some occasions for compatibility reasons:

Property	Type	Required	Description
`omniSearchSearchAttr`	String	yes	The attribute name to query against. Same as `searchAttribute`.
`omniSearchLabelAttr`	String	no	The attribute name that defines the label of a search result. Same as `searchLabel`
`omniSearchLabelString`	String	no	The label for search results. Same as `searchLabel`.

Full example

The following code sample shows how to use the agssearch bundle to define a store:

"bundles": {
    "agssearch": {
        "AGSStore": [
            {
                "id": "stoerungen",
                "title": "Störungen",
                "description": "Störungen",
                "searchAttribute": "kommentar",
                "searchLabel": "kommentar",
                "url": "https://services.conterra.de/arcgis/rest/services/training/stoerungen/MapServer/0",
                "useIn": [
                    "search"
                ],
                "filterOptions": {
                    "suggestContains": true
                },
                "fetchIdProperty": true,
                "enablePagination": false,
            },
        ]
    }
}

Client-side score

When a search is performed, map.apps requests 10 times as much candidates as are displayed in the user interface (for example, 50 candidates are requested when 5 should be displayed). For these candidates, a score is calculated based on the position of the search term in the corresponding search input text.

If a store already calculates a score itself, you can disable client-side scoring by setting "searchCandidateCount": 0 in the store properties. This is already configured for the locator-store.

To configure the exact number of requested candidates, add the property with a concrete number, for example "searchCandidateCount": 100.

Analyzing search behavior

The search service will use the EventService to emit search-api/SELECTED events whenever a user selects an item from a result set. The event conforms to the SelectedEvent interface.