Search Service
Search Service🔗
The search service allows to retrieve results from the index. It comes with methods to execute a search, and to receive static metadata needed to display the search results. All methods exist in two variants: one including user authentication, and another one requesting a valid access token.
Furthermore, the search service is available in multiple versions: Currently V3, V4, and V5. In the following we will provide only one service description which is valid for the current V5 version. For the V3 and V4 description please consult the Search documentation of version 3.20 or earlier.
All methods of this service can raise the following common errors. Method-specific errors are mentioned later. While the methods with user authentication can raise an INVALID_PASSWORD error, the versions requiring access tokens can instead return INVALID_ACCESS_TOKEN errors.
Common Error Handling🔗
| Error Code | Description |
|---|---|
| EMPTY_ARGUMENT | One or more mandatory arguments are empty. |
| INVALID_PASSWORD | The password is incorrect - applies to password authentication. |
| INVALID_ACCESS_TOKEN | The token is not valid (possibly timed-out) - applies to token authentication. |
| ENVIRONMENT_NOT_AVAILABLE | The environment is not available (see log-file for possible errors). |
| INVALID_ACCESS_ROLES | The access roles are incorrect. |
| SEARCH_EXECUTION_ERROR | An error occurred during the execution of a search query. |
| INCOMPATIBLE_API | Returned if attempting to search with the V3 or V4 endpoint on environments that require higher API versions. |
Synonym Expansion Language Selection🔗
Synonyms are expanded with using languages in given flow and priority:
synonymLanguagesrequest parameter is present and is not empty- user's language preference as stored in UserSettings if exists
- Environment's default languages as configured in Synonym Indexes
- all languages defined in the environment configuration
Method Search🔗
Method call🔗
search(environment, password, user, accessRoles, accessOptions, request) : SearchResult
Description🔗
The search service takes a request object as a parameter that typically contains a keyword query ( see query language) and other parameters to determine the search results ( see SearchRequest). The service returns a search result object, containing a list of top results: document identifiers and their document metadata ( see SearchResult).
This method can be called as a SOAP service.
These interfaces are functionally identical.
Parameters🔗
| Parameter Name | Type | Description |
|---|---|---|
| environment | string | identifier of a search environment |
| password | string | password for the search environment |
| user | string | the user id for retrieving custom synonyms, optional parameter |
| accessRoles | list of strings | list of access roles for which to retrieve the documents |
| accessOptions | AccessOptions object | optional object containing access options (for external searchers) See AccessOptions in chapter Object Structures |
| request | SearchRequest object | See description of SearchRequest in chapter Object Structures |
Example🔗
Searching for records where field experienceyears has value greater than 10. Note the enclosure of CDATA tags to make
sure > and similar characters are not invalidly parsed as XML.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sear="http://home.textkernel.nl/search">
<soapenv:Header/>
<soapenv:Body>
<sear:search>
<environment>example</environment>
<password>demo</password>
<accessRoles>all</accessRoles>
<request>
<queryParts>
<field>experienceyears</field>
<items>
<value><![CDATA[>10]]></value>
</items>
</queryParts>
</request>
</sear:search>
</soapenv:Body>
</soapenv:Envelope>
Returns🔗
| Result Name | Type | Description |
|---|---|---|
| searchResult | SearchResult object | See description of SearchResult in chapter Object Structures |
Pre-Condition🔗
None
Post-Condition🔗
None
Error Handling🔗
See the description of common errors as well as method specific errors listed below:
| Error Code | Description |
|---|---|
| INVALID_REQUEST | The search request is incorrect. |
| INVALID_EXTERNAL_TOKEN | The external token (one of optional accessOptions) is not valid. |
| SEARCHER_ACCESS_DENIED | The searcher is restricted and there is no access granted in the token's access options searcherAccess. |
| DATABASE_ERROR | The request experienced a database error while trying to retrieve custom synonyms. |
Method SearchWithToken🔗
Method call🔗
searchWithToken(accessToken, request) : SearchResult
Description🔗
The search service is identical with the above described search method but requires a valid accessToken coming from the authentication service instead of the environment name, password, and access options parameters.
Method Search With ID🔗
Method call🔗
searchWithId(environment, password, user, accessRoles, accessOptions, savedSearchID, extraQueryParts, searchEngine, language, sorting, ip, agent, uuid) : SearchResult
Description🔗
The search service executes the saved search with given savedSearchID on the given searcher. In addition to the saved search extra query parts can be added to the request which are combined with the query parts extracted from the saved search. This can e.g. be used to execute a saved query with an additional document date restriction as used in email alerts.
Parameters🔗
| Parameter Name | Type | Description |
|---|---|---|
| environment | string | identifier of a search environment |
| password | string | password for the search environment |
| user | string | the user id for retrieving custom synonyms, optional parameter |
| accessRoles | list of strings | list of access roles for which to retrieve the documents |
| accessOptions | AccessOptions object | optional object containing access options (for external searchers) See AccessOptions in chapter Object Structures |
| savedSearchID | string | the identifier of the saved search |
| extraQueryParts | list of QueryPart | additional query parts added to the query stored in the search state |
| searchEngine | string | the identifier of the searcher to use. If empty, the default is used |
| language | string | the language used to translate search results |
| sorting | ResultSorting | optional result sorting definition. |
| ip | string | optional ip address of the request origin. If this is omitted, it is ascertained automatically when possible. |
| agent | string | optional user agent used in the search request for Indeed Jobs |
| uuid | string | optional used to uniquely and persistently identify a users browser or device. Implemented on the front end as a UUID stored in permanent local storage. Required for Broadbean search requests on CV Library. |
| suppressFacetCounts | boolean | Optional. If true the search responses will not contain facet count. Improves query response time. |
| suppressHighlighting | boolean | Optional. If true search responses will not be highlighted. Note: If a snippet was requested from the searcher as part of the result fields, the snippet can still contain highlighting. |
| synonymLanguages | list of string | Optional. List of language codes preferred by the user to filter synonyms by languages. See Synonym Expansion Language Selection section |
Returns🔗
| Result Name | Type | Description |
|---|---|---|
| searchResult | SearchResult object | See description of SearchResult in chapter Object Structures |
Pre-Condition🔗
None
Post-Condition🔗
None
Error Handling🔗
See the description of search method errors.
| Error Code | Description |
|---|---|
| SAVED_SEARCH_NOT_FOUND | The saved search with specified ID could not be found. |
| PROJECT_NOT_FOUND | The associated project is not existing. |
| PROJECT_ACCESS_DENIED | The associated project is not owned by or shared with the user. |
| DATABASE_ERROR | The request experienced a database error. |
Method SearchWithIdWithToken🔗
Method call🔗
searchWithIdWithToken(accessToken, savedSearchID, extraQueryParts, searchEngine, language, sorting, ip, agent, uuid) : SearchResult
Description🔗
The method is identical with the above described searchWithId method but requires a valid accessToken coming from the authentication service instead of the environment name, password, and access options parameters.
Method Search With State (DEPRECATED)🔗
NOTE: The searchWithState method is deprecated and will be removed by future versions of Search.
Method call🔗
searchWithState(environment, password, user, accessRoles, accessOptions, state, extraQueryParts, searchEngine, language, sorting, ip, agent, uuid) : SearchResult
Description🔗
The search service executes a search query extracted from the given hashed search state on the given searcher. In addition to the state extra query parts can be added to the request which are combined with the query parts extracted from the state. This can e.g. be used to execute a saved query with an additional document date restriction as used in email alerts.
Parameters🔗
| Parameter Name | Type | Description |
|---|---|---|
| environment | string | identifier of a search environment |
| password | string | password for the search environment |
| user | string | the user id for retrieving custom synonyms, optional parameter |
| accessRoles | list of strings | list of access roles for which to retrieve the documents |
| accessOptions | AccessOptions object | optional object containing access options (for external searchers) See AccessOptions in chapter Object Structures |
| state | string | hashed (base64-encoded) search state |
| extraQueryParts | list of QueryPart | additional query parts added to the query stored in the search state |
| searchEngine | string | the identifier of the searcher to use. If empty, the default is used |
| language | string | the language used to translate search results |
| sorting | ResultSorting | optional result sorting definition. |
| ip | string | optional ip address of the request origin. If this is omitted, it is ascertained automatically when possible. |
| agent | string | optional user agent used in the search request for Indeed Jobs |
| uuid | string | optional used to uniquely and persistently identify a users browser or device. Implemented on the front end as a UUID stored in permanent local storage. Required for Broadbean search requests on CV Library. |
Returns🔗
| Result Name | Type | Description |
|---|---|---|
| searchResult | SearchResult object | See description of SearchResult in chapter Object Structures |
Pre-Condition🔗
None
Post-Condition🔗
None
Error Handling🔗
See the description of search method errors.
Method SearchWithStateWithToken (DEPRECATED)🔗
NOTE: The SearchWithStateWithToken method is deprecated and will be removed by future versions of Search.
Method call🔗
searchWithStateWithToken(accessToken, state, extraQueryParts, searchEngine, language, sorting, ip, agent, uuid) : SearchResult
Description🔗
The method is identical with the above described searchWithState method but requires a valid accessToken coming from the authentication service instead of the environment name, password, and access options parameters.
Method Search With Url🔗
Method call🔗
searchWithUrl(environment, password, user, accessRoles, accessOptions, url, searchEngine, language, sorting, ip, agent, uuid, suppressFacetCounts, suppressHighlighting, extractorName) : SearchResult
Description🔗
The query is extracted from URL, then executed on the given searcher. The Textkernel Parser needs to be configured for your environment to process the URL and return a templated result as a query. Query extraction is creating a query from a semantically parsed document. For example, automatically creating a query from a vacancy to search for suitable candidates. If extractorName is provided, uses that specific extractor if it is null or does not match to any extractor defined in the environment configuration, default extractor is used.
This endpoint does NOT support pagination. After a call to searchWithUrl, additional results can be fetched by calling the search method of the Search service using the queryParts returned by the searchWithUrl method.
This method is a convenience API for calling the following services in order:
-
Query Extraction Service: extractFromUrl Query extraction part performs differently depending on the request protocol (http, https, doc) of the url parameter.
doc://The URL parameter is expected to be in doc://environmentName/searchEngine/documentID/[extractorName] format. In this case it retrieves the document from Search's own docstore and sends it to the extractor to generate a query. If the URI contains an extractorName that one is used, otherwise the endpoint's extractorName parameter gets evaluated, and if neither is set the configured default extractor is used.http://, https://The URL parameter is expected to be a valid external URL that is forwarded by this service to the configured extractor account with the specified name. If no extractorName is provided, the configured default extractor is used. The generated query is returned.
-
Search Service: search Searches with the extract query obtained in previous step
This method is only available as a SOAP service.
Parameters🔗
| Parameter Name | Type | Description |
|---|---|---|
| environment | string | identifier of a search environment |
| password | string | password for the search environment |
| user | string | the user id for retrieving custom synonyms, optional parameter |
| accessRoles | list of strings | list of access roles for which to retrieve the documents |
| accessOptions | AccessOptions object | optional object containing access options (for external searchers) See AccessOptions in chapter Object Structures |
| url | string | URL of either an external document to be downloaded and processed by the Textkernel Parser |
| searchEngine | string | the identifier of the searcher to use. If empty, the default is used |
| language | string | the language used to translate search results |
| sorting | ResultSorting | optional result sorting definition. |
| ip | string | optional ip address of the request origin. If this is omitted, it is ascertained automatically when possible. |
| agent | string | optional user agent used in the search request for Indeed Jobs |
| uuid | string | optional used to uniquely and persistently identify a users browser or device. Implemented on the front end as a UUID stored in permanent local storage. Required for Broadbean search requests on CV Library. |
| suppressFacetCounts | string | optional flag for suppressing facet counts calculation. |
| suppressHighlighting | string | optional flag for suppressing output highlighting. |
| extractorName | string | optional the extractor name that will be used for query parsing. |
| Result Name | Type | Description |
|---|---|---|
| searchResult | SearchResult object | See description of SearchResult in chapter Object Structures |
Pre-Condition🔗
- Document Parsing is set up for your environment.
- The URL must be accessible to Textkernel.
Post-Condition🔗
None.
Error Handling🔗
See the description of search method errors as well as method specific errors listed below:
| Error Code | Description |
|---|---|
| QUERY_EXTRACTION_NOT_AVAILABLE | The quey extraction is not available. |
| QUERY_EXTRACTION_EXECUTION_ERROR | An error occurred while processing the document. |
Method Search With File🔗
Method call🔗
searchWithFile(environment, password, user, accessRoles, accessOptions, filename, fileContent, searchEngine, language, sorting, ip, agent, uuid, suppressFacetCounts, suppressHighlighting, extractorName) : SearchResult
Description🔗
The query is extracted from the provided file, then executed on the given searcher. The Textkernel Parser needs to be enabled for the environment to process the file and return a templated result as a query. Query extraction is creating a query from a semantically parsed document. For example, automatically creating a query from a vacancy to search for suitable candidates. If extractorName is provided, uses that specific extractor if it is null or does not match to any extractor defined in the environment configuration, default extractor is used.
After a call to searchWithFile, additional results can be fetched by calling the search method of the Search service using the queryParts returned by the searchWithFile method.
This method is a convenience API for calling the following services in order:
This method is only available as a SOAP service.
Parameters🔗
| Parameter Name | Type | Description |
|---|---|---|
| environment | string | identifier of a search environment |
| password | string | password for the search environment |
| user | string | the user id for retrieving custom synonyms, optional parameter |
| accessRoles | list of strings | list of access roles for which to retrieve the documents |
| accessOptions | AccessOptions object | optional object containing access options (for external searchers) See AccessOptions in chapter Object Structures |
| filename | string | Filename of the document to process. |
| fileContent | byte array | Binary file content of the document to process. |
| searchEngine | string | the identifier of the searcher to use. If empty, the default is used |
| language | string | the language used to translate search results |
| sorting | ResultSorting | optional result sorting definition. |
| ip | string | optional ip address of the request origin. If this is omitted, it is ascertained automatically when possible. |
| agent | string | optional user agent used in the search request for Indeed Jobs |
| uuid | string | optional used to uniquely and persistently identify a users browser or device. Implemented on the front end as a UUID stored in permanent local storage. Required for Broadbean search requests on CV Library. |
| suppressFacetCounts | string | optional flag for suppressing facet counts calculation. |
| suppressHighlighting | string | optional flag for suppressing output highlighting. |
| extractorName | string | optional the extractor name that will be used for query parsing. |
Returns🔗
| Result Name | Type | Description |
|---|---|---|
| searchResult | SearchResult object | See description of SearchResult in chapter Object Structures |
Pre-Condition🔗
- Document Parsing is set up for your environment.
- The file must be in a format that is supported by the Textkernel Parser supports (e.g. docx, PDF, HTML).
Post-Condition🔗
None
Error Handling🔗
See the description of search method errors as well as method specific errors listed below:
| Error Code | Description |
|---|---|
| QUERY_EXTRACTION_NOT_AVAILABLE | The quey extraction is not available. |
| QUERY_EXTRACTION_EXECUTION_ERROR | An error occurred while processing the document. |
Method GetMetadata🔗
Method call🔗
getMetadata(environment, password, accessOptions, language, userOptions, accessRoles) : CompositeMetadata
Description🔗
The method provides static information such as field names, searchers and configured facets. The getMetadata method is typically the first method called by a user interface of Search during initialization. The provided metadata is needed by a user interface to correctly interpret and display search results by subsequent calls of the search method. This information should not be repeated in all queries to avoid redundancy. Therefore it is returned by this separate method.
Parameters🔗
| Parameter Name | Type | Description |
|---|---|---|
| environment | string | identifier of a search environment |
| password | string | password for the search environment |
| accessOptions | AccessOptions object | optional object checked here for the hasReportingAccess flag See AccessOptions in chapter Object Structures |
| language | string | identifier of a language for the returned metadata |
| userOptions | UserOptions object | optional object checked here for the hasEmailAddressesOnToken flag See UserOptions in chapter Object Structures |
| accessRoles | list of strings | optional list of access roles for which to retrieve facet items. If omitted the result will contain all facet items. |
Returns🔗
| Result Name | Type | Description |
|---|---|---|
| CompositeMetadata | Composite metadata object | See description of CompositeMetadata in chapter Object Structures |
Pre-Condition🔗
None
Post-Condition🔗
None
Error Handling🔗
See the description of common errors.
Method GetMetadataWithToken🔗
Method call🔗
getMetadataWithToken(accessToken, language) : CompositeMetadata
Description🔗
The method is identical with the above described getMetadata method but requires a valid accessToken coming from the authentication service instead of the environment name, password, access options, user options and access roles parameters.