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).

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:

  • One refiner for Author
    • 15 values
    • Minimum count 0
    • Only values that start with Jan
  • One refiner for ContentSource with the default options:
    • 100 values
    • Minimum count 0
    • No prefix, return all values

RefinementFilters

Optional Array of Strings

Defines the refiners that should be applied with the search query.

  • The format is <RefinerPropertyName>:<RefinerValueToken>
EnableSorting Optional Boolean Controls the sorting capability.
SortList 
Optional

Array of SortCollection objects

Defines the type of sorting that will be applied.
  Members of the SortCollection object:
     
  • Direction
Required
 Binary 0 means ascending, 1 means descending
  • PropertyName
String The name of the property used to sort
  • SortType
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.
  Members of the VectorQuery object:
     
  • Fields
Required
 Array of Strings Specifies the list of vector fields to be targeted when the search is going to be executed.
  • Embeddings
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:

  • Properties
  • FederatorMetadata
  • Properties
Array of Objects Contains an array of objects that define each property value (below):
    • DateTimeMode
Integer

  • Used for date properties.

  • Represents the type of the date property:

    • 0 - Local
    • 1 - Unspecified
    • 2 - Unspecified Local
    • 3 - Utc
      • Typically, date properties are returned as UTC dates
    • Name
String The name of the property.
    • Value
String The value of the property.
    • Type
String The full class name of the .NET type of the property.
  • FederatorMetadata
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:

  • FederatorBackend
    • The search engine that returned the result
  • FederatorPositionInBackend
    • The position of the result in the search engine that returned the result
  • FederatorBackendRank
    • The original rank of the result in the set of results (from the search engine queried) before being mixed with results from other search engines.
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:
  • RefinementName
String The name of the refiner value (the text that would be displayed).
  • RefinementValue
String The decoded value (decoded token) of the refiner entry.
  • Token
String The encoded value of the refiner entry (this is the value that must be sent with the query as an applied refiner).
  • RefinerName
String The property name of the refiner that the current value belongs to.
  • RefinementCount
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

Copy 
{
    "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

Copy 
{
    "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

Copy 
{
    "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

Copy 
{
    "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.

Copy 
{
    "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.

Copy 
{
    "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.

Copy 
{
    "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.

Copy 
{
    "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.

Copy 
{
    "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".

Copy 
{
    "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 

Copy 
{
    "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

Copy 
{
    "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 

Copy 
{
    "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

Copy 
{
    "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
}