Search Service
Overview
The search service is located at the following URL:
- http(s)://<smarthub-web-app>/_bai/v1.0/search
-
- Replace the first part of the URL above with the address of your own SmartHub instance
Service Description
This service exposes the following endpoints:
/search
- Scope: Endpoint is used to execute searches and return search results along with refiners.
- Method: POST
- Type: JSON-based
- Authentication:
- Must match what is configured in SmartHub Administration.
- If None (Public site) is configured, then no authentication header is required.
- Otherwise, send header X-SH-Authorization: Bearer xxxxxxx (replace the placeholder with a valid token that SmartHub can use).
- Must match what is configured in SmartHub Administration.
Request
Property | Required/Optional | Property | Description | ||
---|---|---|---|---|---|
QueryText |
Required | String | Defines the query text that will be executed | ||
QueryTemplate |
Required | String | Defines the query template that will be used | ||
RowLimit |
Required | Integer | Specifies the number of results expected from the search | ||
StartRow |
Required | Integer | Specifies the start index of the results expected from the search (used for pagination in conjunction with RowLimit) | ||
SelectProperties |
Required | Array of Strings | Specifies the list of property names (case sensitive) that are requested for the results being returned from search | ||
SourceId | Required | String | GUID controlling the results being returned (usage is engine-specific; for SharePoint it's mapped as Result Source ID) | ||
TrimDuplicates |
Optional | Boolean | Controls duplicate filtering. | ||
SummaryLength | Required | Integer | Defines the length of the text snippet (excerpt) that should be returned for the items returned by the search | ||
ResultsUrl |
Optional | String | Defines a reference to the current page that runs the search (used for analytics or query processing stages to track where the search comes from) | ||
Refiners |
Optional | String |
Comma separated list of property names that should be returned as refiners (the response for the search returns refiner values for them) IF supported by the engine, for each refiner, you can optionally specify a Refiner Specwhich has the format: PropertyName(number of values to request/minimum refiner count/prefix followed by star) For example Author(15/0/Jan*),ContentSource would return 2 refiners:
|
||
RefinementFilters |
Optional | Array of Strings |
Defines the refiners that should be applied with the search query.
|
||
EnableSorting | Optional | Boolean | Controls the sorting capability. | ||
SortList |
Optional |
Array of SortCollection objects |
Defines the type of sorting that will be applied. |
||
|
|||||
|
Required |
Binary | 0 means ascending, 1 means descending | ||
|
String | The name of the property used to sort | |||
|
Binary | 0 means "sort by property", 1 means "sort by rank" | |||
VectorQueries | Optional | Array of VectorQuery objects |
Stores your embeddings and performs hybrid (keyword + vector) search. If left blank, keyword search will be performed. |
||
|
|||||
|
Required |
Array of Strings | Specifies the list of vector fields to be targeted when the search is going to be executed. | ||
|
Array of Doubles |
Specifies the vector embeddings of the QueryText property. |
Response
The SearchResults object exposes all the properties that can be:
- Used at request time
- Processed by the API calls
Object | Property | Description |
---|---|---|
RelevantResults | Array of Objects |
Contains the set of properties for each search results for the current request. Each result contains 2 sets of properties, listed below:
|
|
Array of Objects | Contains an array of objects that define each property value (below): |
|
Integer |
|
|
String | The name of the property. |
|
String | The value of the property. |
|
String | The full class name of the .NET type of the property. |
|
Array of Objects |
Contains an array of objects. The following objects give SmartHub-specific information about the specific search engine (backend) that returned the result:
|
TotalRelevantResultsRowCount | Integer | The number of results that have been returned with the current request (lower or equal to the number of results per page). |
TotalRelevantResults | Integer | The total number of results available for the current query. |
RefinementResults: | Array of Objects |
The available refinement values for the refiner requests with the current query. Each refinement result is an object with the properties listed below: |
|
String | The name of the refiner value (the text that would be displayed). |
|
String | The decoded value (decoded token) of the refiner entry. |
|
String | The encoded value of the refiner entry (this is the value that must be sent with the query as an applied refiner). |
|
String | The property name of the refiner that the current value belongs to. |
|
Integer | The number of search results that match the current refinement value. |
Use Cases
The following use cases collect results for a basic keyword search.
Note: In the examples below, the text smarthub.contoso.com is used in URLs.
When executing your calls, be sure to replace this text with the URL of your SmartHub site web app.
Run a Basic Keyword Search
Request
{
"QueryText": "*",
"QueryTemplate": "{searchboxquery}",
"SortList": [
{
"SortType": 1,
"PropertyName": "Rank",
"Direction": 1
}
],
"EnableSorting": true,
"RowLimit": 10,
"StartRow": 0,
"SelectProperties": ["excerpt", "Rank", "author", "date", "ContentSource", "title"],
"Refiners": "",
"SourceId": "0140dd13-5a87-434c-ac94-dbfb8e579fdd",
"RefinementFilters": [],
"TrimDuplicates": true,
"SummaryLength": 200,
"ResultsUrl": "https://smarthub.contoso.com/Results.html"}
Response
{
"RelevantResults": [
{
"Properties": [
{
"DateTimeMode": 3,
"Name": "Rank",
"Type": "System.Double, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
"Value": 16.4980812072754
}, {
"DateTimeMode": 3,
"Name": "title",
"Type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
"Value": "SmartHub"
}, {
"DateTimeMode": 3,
"Name": "excerpt",
"Type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
"Value": "SmartHub Enterprise Search" }
(...)
]
},
(...)
],
"TotalRelevantResults": 14
}
Filter Results based on Property Values
You can use this approach to filter out results based on their property values.
Using this approach can lead to 0 results if no document matches the filter specified in the QueryText.
Alternatively, you can use Refiners (see sections below) to know in advance how many results a certain filter will return.
Request
{
"QueryText": "* AND ContentSource:MyDocuments",
"QueryTemplate": "{searchboxquery}",
"SortList": [
{
"SortType": 1,
"PropertyName": "Rank",
"Direction": 1
}
],
"EnableSorting": true,
"RowLimit": 10,
"StartRow": 0,
"SelectProperties": ["excerpt", "Rank", "author", "date", "ContentSource", "title"],
"Refiners": "",
"SourceId": "0140dd13-5a87-434c-ac94-dbfb8e579fdd",
"RefinementFilters": [],
"TrimDuplicates": true,
"SummaryLength": 200,
"ResultsUrl": "https://smarthub.contoso.com/Results.html"}
Response
{
"RelevantResults": [
{
"Properties": [
{
"DateTimeMode": 3,
"Name": "Rank",
"Type": "System.Double, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
"Value": 16.4980812072754
}, {
"DateTimeMode": 3,
"Name": "title",
"Type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
"Value": "SmartHub" }, {
"DateTimeMode": 3,
"Name": "excerpt",
"Type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
"Value": "SmartHub Enterprise Search" }
(...)
]
},
(...)
],
"TotalRelevantResults": 1
}
Filter Results using Refiners
You can use this approach to filter out results based on their property values.
- Using this filtering approach does not return 0 results because only the refiner values that match documents are returned at search time.
- This approach requires 2 queries to be performed:
- Query 1: Returns results and the refiner values
- Query 2: Filters the query results using the refiner value
Request with Refiners
-
Refiners define a comma-separated list of properties to retrieve refiner values for.
-
The query Refiners in the example below lists the properties to retrieve refine values for ContentSource.
{
"QueryText": "*",
"QueryTemplate": "{searchboxquery}",
"SortList": [
{
"SortType": 1,
"PropertyName": "Rank",
"Direction": 1
}
],
"EnableSorting": true,
"RowLimit": 10,
"StartRow": 0,
"SelectProperties": ["excerpt", "Rank", "author", "date", "ContentSource", "title"],
"Refiners": "ContentSource",
"SourceId": "0140dd13-5a87-434c-ac94-dbfb8e579fdd",
"RefinementFilters": [],
"TrimDuplicates": true,
"SummaryLength": 200,
"ResultsUrl": "https://smarthub.contoso.com/Results.html"}
Response with Refiner Values
Note that the property RefinerName matches the Refiners property specified in the request above.
{
"RefinementResults": [
{
"RefinementName": "MyDocuments",
"RefinementValue": "MyDocuments",
"RefinerName": "ContentSource",
"Token": "\"ǂǂ4d79446f63756d656e7473\"",
"RefinementCount": 1
}
(...)
],
"RelevantResults": [
{
"Properties": [
{
"DateTimeMode": 3,
"Name": "Rank",
"Type": "System.Double, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
"Value": 16.4980812072754
}, {
"DateTimeMode": 3,
"Name": "title",
"Type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
"Value": "SmartHub" }, {
"DateTimeMode": 3,
"Name": "excerpt",
"Type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
"Value": "SmartHub Enterprise Search" }
(...)
]
},
(...)
],
"TotalRelevantResults": 14
}
Request with Applied Refiner Value
Note that the value for the property RefinementFilters matches the token from the previous response.
{
"QueryText": "*",
"QueryTemplate": "{searchboxquery}",
"SortList": [
{
"SortType": 1,
"PropertyName": "Rank",
"Direction": 1
}
],
"EnableSorting": true,
"RowLimit": 10,
"StartRow": 0,
"SelectProperties": ["excerpt", "Rank", "author", "date", "ContentSource", "title"],
"Refiners": "ContentSource",
"SourceId": "0140dd13-5a87-434c-ac94-dbfb8e579fdd",
"RefinementFilters": ["ContentSource:\"ǂǂ436f6e666c75656e636520436f6e74656e74\""],
"TrimDuplicates": true,
"SummaryLength": 200,
"ResultsUrl": "https://smarthub.contoso.com/Results.html"}
Response with Applied Refiner Value
Note that the property TotalRelevantResults changed and the property RefinementResults are returned for further refining.
{
"RefinementResults": [
{
"RefinementName": "MyDocuments",
"RefinementValue": "MyDocuments",
"RefinerName": "ContentSource",
"Token": "\"ǂǂ4d79446f63756d656e7473\"",
"RefinementCount": 1
}
(...)
],
"RelevantResults": [
{
"Properties": [ {
"DateTimeMode": 3,
"Name": "Rank",
"Type": "System.Double, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
"Value": 16.4980812072754
}, {
"DateTimeMode": 3,
"Name": "title",
"Type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
"Value": "SmartHub" }, {
"DateTimeMode": 3,
"Name": "excerpt",
"Type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
"Value": "SmartHub Enterprise Search" }
(...)
]
},
(...)
],
"TotalRelevantResults": 1
}
Exclude Refiner Values
To exclude a refiner value, the "not" operator has to be used for the refinement filter.
{
"QueryText": "*",
"QueryTemplate": "{searchboxquery}",
"SortList": [
{
"SortType": 1,
"PropertyName": "Rank",
"Direction": 1
}
],
"EnableSorting": true,
"RowLimit": 10,
"StartRow": 0,
"SelectProperties": ["excerpt", "Rank", "author", "date", "ContentSource", "title"],
"Refiners": "filetype",
"SourceId": "0140dd13-5a87-434c-ac94-dbfb8e579fdd",
"RefinementFilters": ["filetype:not("ǂǂ706466")"],
"TrimDuplicates": true,
"SummaryLength": 200,
"ResultsUrl": "https://smarthub.contoso.com/Results.html"
}
Ranges can also be excluded using the operator "range_not".
{
"QueryText": "*",
"QueryTemplate": "{searchboxquery}",
"SortList": [
{
"SortType": 1,
"PropertyName": "Rank",
"Direction": 1
}
],
"EnableSorting": true,
"RowLimit": 10,
"StartRow": 0,
"SelectProperties": ["excerpt", "Rank", "author", "date", "ContentSource", "title"],
"Refiners": "date",
"SourceId": "0140dd13-5a87-434c-ac94-dbfb8e579fdd",
"RefinementFilters": ["date:range_not(\"ǂǂ28323032302d30372d31315430303a30303a30302e303030303030305a2c20323032322d30372d31315430303a30303a30302e303030303030305a29\")"],
"TrimDuplicates": true,
"SummaryLength": 200,
"ResultsUrl": "https://smarthub.contoso.com/Results.html"
}
Get Possible Refiner Values for a Keyword
Sometimes you need to fetch a list of refiner values with the intention of using them as suggestions.
- For example, you can fetch the first 10 Authors that start with a specific keyword like Mike.
In this case you don't need to return results so RowLimit will be set to 1 to avoid unnecessary information.
The only thing that changes is the way you request the refiner - instead of just specifying the name you can specify extra information like:
- How many values to be returned
- The minimum document count that the refiner value should match
- What is the refiner values prefix
Those 3 values compose the Refiner Spec which is passed to the service as part of the Refiners property like below.
Request
{
"QueryText": "*",
"QueryTemplate": "{searchboxquery}",
"SortList": [
{
"SortType": 1,
"PropertyName": "Rank",
"Direction": 1
}
],
"EnableSorting": true,
"RowLimit": 1,
"StartRow": 0,
"SelectProperties": ["excerpt", "Rank", "author", "date", "ContentSource", "title"],
"Refiners": "Author(10/0/Mike*),ContentSource",
"SourceId": "0140dd13-5a87-434c-ac94-dbfb8e579fdd",
"RefinementFilters": [],
"TrimDuplicates": true,
"SummaryLength": 200,
"ResultsUrl": "https://smarthub.contoso.com/Results.html"}
Response
{
"RefinementResults": [
{
"RefinementName": "MyDocuments",
"RefinementValue": "MyDocuments",
"RefinerName": "ContentSource",
"Token": "\"ǂǂ4d79446f63756d656e7473\"",
"RefinementCount": 1
},
{
"RefinementName": "Mike Mayers",
"RefinementValue": "Mike Mayers",
"RefinerName": "Author",
"Token": "\"ǂǂ4d696b65204d6179657273\"",
"RefinementCount: 1,
},
(...)
],
"RelevantResults": [
{
(...)
},
],
"TotalRelevantResults": 1
}
Run a Basic Hybrid Search
Request
{
"QueryText": "what is SmartHub?",
"QueryTemplate": "{searchboxquery}",
"SortList": [
{
"SortType": 1,
"PropertyName": "Rank",
"Direction": 1
}
],
"EnableSorting": true,
"RowLimit": 10,
"StartRow": 0,
"SelectProperties": ["excerpt", "Rank", "author", "date", "ContentSource", "title", "vector_field"],
"Refiners": "",
"SourceId": "0140dd13-5a87-434c-ac94-dbfb8e579fdd",
"RefinementFilters": [],
"TrimDuplicates": true,
"SummaryLength": 200,
"ResultsUrl": "https://smarthub.contoso.com/Results.html",
"VectorQueries": [
{
"Fields": ["vector_field", "second_vector_field"],
"Embeddings": [0.005581075, 0.002107214, -0.02097912, -0.02603071, -0.04682379, 0.01581305, -0.01413872, -0.006267977, 0.02213827, -0.03963995, 0.01317277, -0.006657937, -0.03709269, 0.001167196, -0.0128794, -0.006804619, 0.02982298, -0.01858927, 0.0021734, -0.02751899, -0.02909314, 0.0043146, 0.0161565, -0.01260751, -0.004550723, 0.002481074, 0.03528957, -0.01744444, -0.01815996, -0.009344723, -0.005316332, 0.002853146, -0.007269708, -0.02757624, -0.02394138, 0.01285078, 0.004393308, -0.0210936, 0.0003300347, -0.007441434, 0.03265645, -0.00524478, (...)]
}
]
}
Response
{
"RelevantResults": [
{
"Properties": [
{
"DateTimeMode": 3,
"Name": "vector_field",
"Type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
"Value": "-0.023336241;0.021285176;0.018703416;0.019650063;-0.03187039;0.015390158;-0.0026624398;-0.004148745;-0.02084054;-0.029632866;0.018545642;-0.018369818; -0.007179654; 0.01863625; -0.009612604; -0.029167347; -0.006222601; -0.014639764; 0.01173004 (...)"
},
{
"DateTimeMode": 3,
"Name": "Rank",
"Type": "System.Double, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
"Value": 16.4980812072754
},
{
"DateTimeMode": 3,
"Name": "title",
"Type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
"Value": "SmartHub"
},
{
"DateTimeMode": 3,
"Name": "excerpt",
"Type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
"Value": "SmartHub Enterprise Search"
}
(...)
]
},
(...)
],
"TotalRelevantResults": 17
}