Search
Socotra’s search allows you to find policies, quotes, and accounts quickly and easily.
Overview
You can search against locators, static data, and data extensions of type string
. If there is a match with some degree of relevancy, the corresponding quote, policy, or account will be returned for that match. Results are ordered by relevancy score, from highest to lowest. Relevancy scores are boosted for exact matches on locators and static data, helping to ensure that such results emerge towards the top of the results.
Example
If you have an account configured with a data extension field lastName
, and there is at least one account with last name “Swerski” in your set of accounts, a search query for Swerski
will return at least one result: the account record for “Swerski”, with a high relative score.
Request
POST
request body:
{
"searchString":"Swerski"
}
Response
{
"page": 0,
"results": [
{
"score": 1.0,
"searchEntityType": "ACCOUNT",
"locator": "01HRQ8BQTAPT16ZZ6JQJBDNVP8",
"highlights": [
"Score:1.0 ,Document: accountdata_01HRQ8BQTAPT16ZZ6JQJBDNVP8,Highlight: {data.lastName.keyword=[<em>Swerski</em>], data.lastName=[<em>Swerski</em>]}"
]
},
{
"score": 0.85714287,
"searchEntityType": "ACCOUNT",
"locator": "01HRQ8QEA03ZNSV73Y6X9Y8P6Z",
"highlights": [
"Score:0.85714287 ,Document: accountdata_01HRQ8QEA03ZNSV73Y6X9Y8P6Z,Highlight: {data.lastName.keyword=[<em>Swersky</em>], data.lastName=[<em>Swersky</em>]}"
]
}
]
}
Note
A similar name, “Swersky”, appears in the results, but with lower relevance than the more exact match on “Swerski”. An exact match request with “Swerski” wrapped in (escaped) quotes would only return the “Swerski” account. Read on for details about search behavior and search string syntax.
Requests
Requests can be sent as a single searchString
or as a searchTerm
array. See the API reference for details.
Search String Syntax
A search request comprises search terms - an array of searchTerm
items - and can be expressed as a searchString
. searchString
syntax allows you to express a complete query in a single string, such as one passed through a typical search form box.
A search string follows these rules:
A sequence one or more
searchTerm
strings, separated by whitespace.Each
searchTerm
string has the following form:Form:
[+|-][fieldName:]string[*]
The
fieldName
slug determines whether the match should be against a specific field name or any field.The
fieldName
can be qualified by the full path of the element to which it belongs, which allows for greater specificity in your query. For example, a top-levellastName
data extensionstring
on an account can be searched like this:+data.lastName:Swerski
, while afirstName
data extension on an exposure “insured” under some product can be searched as+insuredQuote.firstName:Veronica
(for quotes) or+insuredPolicy.firstName:Veronica
(for policies).Term relevance scoring:
If the term is prefixed with a
+
, the term is required for search result relevance.If the term is prefixed with a
-
, the term must be excluded for search result relevance.Absence of
+
or-
before a term is interpreted as a suggestion: the presence of the term increases the relevance score, but does not require that the term be present or absent from a match candidate.
The default match behavior is fuzzy.
Appending
*
to the term sets matching tostartsWith
.Enclosing the term in double quotes sets matching to
exact
. Searches with spaces cannot be fuzzy searches.
Responses
The SearchServiceResponse provides a list of SearchResultResponse results
, along with properties to assist in paging through results.
You can fetch up to 100 results at a time, and use the count
, offset
, and searchToken
values to control pagination. If no count
is set for the initial search request, it will be set to 100
. The searchToken
should be used in subsequent GET
requests to page through the results, with count
serving as the number of results to be returned in the page and offset
as the starting index (beginning at 0
) in the result list. For example, if you perform a search with a total of 70 results, and want to page through 25 results at a time, you can do it with three requests, all setting count
to 25
:
The initial query
A second query, along with the
searchToken
andoffset
as25
A final query , along with the
searchToken
andoffset
as50
You’ll know that you have exhausted the result set when the length of the result list is less than count
. If there are no results beginning at some offset
index, the service will return an empty result list. You can set the count
to another value when fetching results; following the example above, if you decided you wanted all the results in a single response, just provide the searchToken
with count
at least 70
. A provided count
greater than 100
will be set to 100
.
Relevance
The highlights
and score
properties provide additional context about the match. In highlights
you will find one or more excerpts from text that matched the query, while score
indicates the relative numerical value assigned for ranking. You’ll see very high score
values for certain cases, such as exact matches on locator values.
Search Summary
The searchSummary
object serves as a digest about the entity, reducing the need for subsequent data fetches from the API in order to understand which entity is being referred to, or to display the search result in an effective way. The contents of searchSummary
depends on the result entity type:
Accounts will have all string-type data extension field values in the
data
property, along withname
andstate
.Quotes and policies will have all static data fields in a
static
property.Quotes will also have a
state
property.
Sample Responses
A SearchResultResponse for a “ConsumerAccount” account (search query was simply “Evans”):
{
"score": 1.0,
"searchEntityType": "account",
"searchEntityLocator": "01J53T5V9B3ARJDF38CYY17CJ1",
"searchSummary": {
"data": {
"crm_reference_id": "refId123",
"firstName": "Bill",
"lastName": "Evans"
},
"name": "ConsumerAccount",
"state": "validated"
},
"highlights": [
"Score:1.0 ,Document: 01J53T5V9B3ARJDF38CYY17CJ1,Highlight: {entity.data.lastName=[<em>Evans</em>]}"
]
}
A SearchResultResponse for a quote result (search query was the locator value 01J56JJ8N7S00XFBW8Z69Q94JX
– note that the score
is set to the highest in the highlights
):
{
"score": 102.0,
"searchEntityType": "quote",
"searchEntityLocator": "01J56JJ8N7S00XFBW8Z69Q94JX",
"productName": "Basic_Homeowners",
"accountLocator": "01J53T5V9B3ARJDF38CYY17CJ1",
"searchSummary": {
"state": "issued",
"static": {
"policyNumber": "123-31231"
}
},
"highlights": [
"Score:102.0 ,Document: 01J56JJ8N7S00XFBW8Z69Q94JX,Highlight: {entity.elements.staticLocator.keyword=[<em>01J56JJ8N7S00XFBW8Z69Q94JX</em>], entity.elements.locator.keyword=[<em>01J56JJ8N7S00XFBW8Z69Q94JX</em>]}",
"Score:101.0 ,Document: 01J56JJ8N7S00XFBW8Z69Q94JX,Highlight: {entity.locator.keyword=[<em>01J56JJ8N7S00XFBW8Z69Q94JX</em>]}"
]
}
Configuration
Search is enabled by default, indexing both locators and data extension fields of type string
. String field indexing includes data fields contained within Custom Data Types and in static data.
Locator indexing makes it possible to search for quotes, policies, and accounts by locator, along with elements by locator or static locator.
You may use the defaultSearchable
and searchable
configuration properties to more precisely control which string fields are indexed for search. defaultSearchable
is available at the top level of the configuration, in addition to configuration for accounts, products, and elements. When defaultSearchable
is true
, all string fields at that level and below are indexed. When defaultSearchable
is false
, then a string field must have searchable
set to true
in order to be indexed for search. For a given field, the nearest defaultSearchable
value when going up the configuration hierarchy applies.