Search
3.5.4The Search API offers two distinct functionalities: you can use it to create both search providers and search clients. Search providers are apps that respond to search queries, whereas search clients are apps that initiate searches. For instance, a search provider may return a list of instruments as a response to a search query, and may also support one or more actions - like showing a chart for the selected instrument. Actions may be executed when the user clicks on a result in the UI of a search client app. You may present multiple actions as options to the user via the search client UI, so that they may choose how to handle the search result depending on their current needs. The Search API also enables you to define search types, set debounce time for search queries, set limits for search results and more.
The Search API is accessible via the io.search object.
APIobject
Description
Search API.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| version | string | Search API version. |
Methods
getDebounceMSmethod
Signature
() => number
Description
Retrieves the current debounce interval for search queries.
listProvidersmethod
Signature
() => Promise<ProviderData[]>
Description
Retrieves a list of all available search providers.
listTypesmethod
Signature
() => Promise<SearchType[]>
Description
Retrieves a list of all available search types from all search providers.
querymethod
Signature
(queryConfig: QueryConfig) => Promise<Query>
Description
Creates a search query.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| queryConfig | QueryConfig | Settings for creating a search query. |
registerProvidermethod
Signature
(config: ProviderRegistrationConfig) => Promise<Provider>
Description
Registers a search provider.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| config | ProviderRegistrationConfig | Settings for registering a search provider. |
setDebounceMSmethod
Signature
(milliseconds: number) => void
Description
Sets the debounce interval for search queries.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| milliseconds | number | Interval in milliseconds to use as debounce interval. |
MainActionobject
Description
Describes an already registered Interop method to be assigned as a main action to a search result. This allows search clients to invoke the specified Interop method if, for example, the user clicks on the search result in a UI.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| method | string | Name of an Interop method to assign as an action for a search result. |
||
| params | any | Arguments to be passed to the specified Interop method when a search client invokes it. |
||
| target | { instance: string; } | "all" | Defines the Interop servers that will be targeted when invoking the specified method. Set to |
Providerobject
Description
Describes a registered search provider.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| appName | string | Name of the app that has registered the search provider. |
||
| id | string | Unique app ID within the framework. |
||
| interopId | string | Unique ID of the Interop instance of the app. |
||
| name | string | Name of the search provider. |
||
| types | SearchType[] | List of search types with which the search provider works. |
Methods
onQuerymethod
Signature
(callback: (query: ProviderQuery) => void) => UnsubscribeFunction
Description
Notifies when a search query is received.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (query: ProviderQuery) => void | Callback function for handling the event. Receives as an argument an object describing the search query. |
onQueryCancelmethod
Signature
(callback: (query: { id: string; }) => void) => UnsubscribeFunction
Description
Notifies when a search query is canceled.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (query: { id: string; }) => void | Callback function for handling the event. Receives as an argument an object with an |
unregistermethod
Signature
() => Promise<void>
Description
Unregisters the search provider from the framework.
ProviderDataobject
Description
Search provider details.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| appName | string | Name of the app that has registered the search provider. |
||
| id | string | Unique app ID within the framework. |
||
| interopId | string | Unique ID of the Interop instance of the app. |
||
| name | string | Name of the search provider. |
||
| types | SearchType[] | List of search types with which the search provider works. |
ProviderLimitsobject
Description
Describes the maximum total results and/or the maximum results per search type to return.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| maxResults | number | Maximum total results per search operation to return. |
||
| maxResultsPerType | number | Maximum results per search type to return. |
ProviderQueryobject
Description
Describes the search query received by the search provider and provides methods for responding to it.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| id | string | ID for the search query (assigned by the framework). |
||
| providerLimits | ProviderLimits | Specifies the maximum total results and/or the maximum results per search type to return. |
||
| providers | ProviderData[] | List of search providers to query. |
||
| search | string | String for which to query the search providers. |
||
| types | SearchType[] | List of search types in which the search client app is interested. |
Methods
donemethod
Signature
() => void
Description
Signals the framework that the search operation has been completed.
errormethod
Signature
(error: string) => void
Description
Sends errors back to search clients.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| error | string | Error message to send back to search clients. |
sendResultmethod
Signature
(result: QueryResult) => void
Description
Sends individual results back to search clients.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| result | QueryResult | Individual search result to send back to search clients. |
ProviderRegistrationConfigobject
Description
Settings for registering a search provider.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| name | string | Name for the search provider. |
||
| types | SearchType[] | Search types with which the provider works. |
Queryobject
Description
Describes a created search query.
Methods
cancelmethod
Signature
() => Promise<void>
Description
Cancels the search query.
onCompletedmethod
Signature
(callback: () => void) => UnsubscribeFunction
Description
Notifies when the search query is completed, i.e. when all search operations in all search providers have been completed.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | () => void | Callback function for handling the event. |
onErrormethod
Signature
(callback: (error: QueryError) => void) => UnsubscribeFunction
Description
Notifies when there is an error in the search process.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (error: QueryError) => void | Callback function for handling the event. Receives as an argument an object holding the error message sent by the search provider and data describing the provider that has sent the error. |
onResultsmethod
Signature
(callback: (resultBatch: QueryResultBatch) => void) => UnsubscribeFunction
Description
Notifies when a batch with results from the search query is received.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (resultBatch: QueryResultBatch) => void | Callback function for handling the event. Receives as an argument an object holding a list of the available search result and details about the search provider that has sent the results. |
QueryConfigobject
Description
Settings for creating a search query.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| providerLimits | ProviderLimits | Specifies the maximum total results and/or the maximum results per search type to return. |
||
| providers | ProviderData[] | List of search providers to query. |
||
| search | string | String for which to query the search providers. |
||
| types | SearchType[] | List of search types in which the search client app is interested. |
QueryErrorobject
Description
Describes a search operation error received by search clients.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| error | string | Error message. |
||
| provider | ProviderData | Details about the search provider that has sent the error. |
QueryResultobject
Description
Describes an individual search result received by search clients.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| action | MainAction | A main action that can be used to invoke an already registered Interop method when the user clicks on the search result displayed in a UI.
If you need to define multiple actions when handling search results, you can use the |
||
| description | string | Description for the search result that can be used in a UI. |
||
| displayName | string | Display name for the search result that can be used in a UI. |
||
| iconURL | string | URL pointing to an icon for the search result that can be used in a UI. |
||
| id | string | ID for the search result that can be used by the search client when handling the result. |
||
| metadata | any | Metadata for the search result that can be used by the search client when handling the result. |
||
| secondaryActions | SecondaryAction[] | Secondary actions can be used to invoke different already registered Interop methods if, for example, you want to present the user
with a choice of options related to the search result. The |
||
| type | SearchType | The predefined search type of the result. |
QueryResultBatchobject
Description
Describes a batch of search results received by search clients.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| provider | ProviderData | Details about the search provider that has sent the results. |
||
| results | QueryResult[] | List of individual search results received by search clients. |
SearchTypeobject
Description
Describes an entity with which a search provided works.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| displayName | string | User-friendly name for the search type that can be displayed in UIs. |
||
| name | string | Name for the search type. |
SecondaryActionobject
Description
Describes an already registered Interop method to be assigned as a secondary action to a search result.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| method | string | Name of an Interop method to assign as an action for a search result. |
||
| name | string | Name for the assigned action. May be used to differentiate between actions on the client side. |
||
| params | any | Arguments to be passed to the specified Interop method when a search client invokes it. |
||
| target | { instance: string; } | "all" | Defines the Interop servers that will be targeted when invoking the specified method. Set to |
UnsubscribeFunctionfunction
Signature
() => void
Description
Function that can be used to stop receiving notifications about events.