Query Response

The engine responds to a Request using a serialized JSON dictionary object. See: Query Request for more information on how to construct a query.

Top Level Response Fields

  • itemIds

    The list of relevant item ids on this page of the result set.

    Type: array of string

  • exactMatches

    The corresponding list of whether the item was an exact match against the query.

    Type: array of boolean

  • relevanceValues

    The corresponding list of relevance values for each item on this page of the result set.

    Type: array of double

  • startIndex

    The index of the first item on this page of the result set.

    Type: int

  • currentPageSize

    The number of items on this page of the result set.

    Type: int

  • datasetSize

    The total number of items in the queried dataset.

    Type: int

  • totalSize

    The total number of items in the result set.

    Type: int

  • exactSize

    The number of exact matched items in the result set.

    Type: int

  • facets

    Describes the facets counts for each facets criterion.

    Type: dictionary

    See: facets Response

  • drillDown

    Describes the drilldown counts for each drilldown criterion. Deprecated. Use the facets request API instead.

    Type: array of dictionary

    See: drillDown

  • properties

    An array of dictionaries, one for each item returned in the query response, that includes any requested changeset property values. If the query request also included a highlighting criterion, then any highlighting would be applied to the appropriate changeset property values.

    Type: array of dictionary

    See: Properties

    New in version 2.8.3.

  • didYouMean

    An dictionary with one entry per didYouMean text type dimension. Each entry is a dictionary that includes the suggestions, highlighted values and information about the relevance of the suggestions.

    Type: dictionary

    See: DidYouMean

    New in version 2.9.

  • highlighting

    An array of dictionaries, one for each item returned in the query response, that includes any requested changeset property values that were highlighted. This field only exists if the merge field of the highlighting request was set to none. For more information about the highlighting request, refer to Highlighting Criterion.

    Type: array of dictionary

    See: Highlighting

    New in version 2.8.4.

  • indexValues

    A dictionary describing the new-form indexed values for each of the named dimensions in the indexValues request.

    Type: dictionary

    See: Index Values

    New in version 2.9.1.

  • calculate

    A dictionary that lists the user-defined keys and their calculated values. The user-defined keys are specified in the calculate request.

    Type: dictionary

    See: Calculate

    New in version 3.1.0.

  • values

    A dictionary describing the indexed values for each of the named dimensions in the legacy values request.

    Type: array of dictionary

    See: Values

    New in version 2.6.17.

  • debug

    A dictionary describing the many aspects of the matching process, including scoring.

    Type: dictionary

    See: Debug Response

  • sortBy TODO

    A dictionary listing the values used to determine sort order as specified in the sortBy criterion. This field only appears in the response when requesting the “sortBy” explain data.

    Type: array of dictionary

    See: sortBy Response

    New in version 2.8.4.

  • isGrouped

    A value describing whether the response includes a groupBy result.

    Type: boolean

  • legacyGroupBy

    A value describing whether the response includes a groupBy result using the legacy or new-style format. To enable the new style response format, set legacyGroupBy to true in the groupBy request criterion.

    Type: boolean

    Default: false

    See: Group By Criterion

  • groups

    A dictionary describing the exact matches, item ids and relevance values for the topN items in each group of the groupBy result.

    Type: array of dictionaries

  • renderParameters

    A URL encoded query string that can be passed to a template for rendering the search results. This is only present if the renderParameters request field is set to true or a dictionary.

    Type: string

    For information on how to reqeust renderParameters, refer to Render Parameters. For a description of the renderParameters response, refer to renderParmeters.

Response Example

{
    "itemIds": ["10", "11", "12", "13", "14", "15", "16", "17", "18", "19"],
    "exactMatches": [true, true, true, true, true, true, true, true, true, true],
    "relevanceValues": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
    "pageSize": 10,
    "currentPageSize": 10,
    "startIndex": 0,
    "exactSize": 38,
    "totalSize": 50,
    "drillDown": [
        {
            "dimension": "bedroom",
            "ids": ["studio", "1", "2", "3", "4", "5+"],
            "exactCounts": [0, 8, 2, 38, 2, 0],
            "fuzzyCounts": [0, 8, 2, 38, 2, 0]}],
    "datasetSize": 50}

facets Response

The following keys appear for each facets criterion key that is present in the request.

See: Facets Criterion for a detailed description of the facets request API.
  • navIds

    A list of the children who are either selected or have descendents that are selected the respect the sortBy key of the facets request.

    Type: array of string

  • childIds

    A list of child ids that are options for the next level of navigation which respect the sortBy, topN, minCount and navChildIds in the facets request.

    Type: array of string

  • dataIds

    The original list of dataIds from the facets request, in the same order, with invalid ids removed. Anything in the dataIds list will also be included in the data response dictionary.

    Type: array of string

  • hasMore

    Indicates that the node has more children to display but that the child data was not included because of a topN restriction. This key will only be present if the list of childIds is longer than the topN request value.

    Type: boolean

  • data

    A dictionary of all the requested response data for any facet id requested or related to the facet ids of the response.

    Note that the structure of data is flat. Any parentId and child node references will be included in the dictionary. To re-establish the hierarchy, use parentId and/or childIds.

    Type: boolean

facets data Response

The following is a discription of the data key of the facets response. For more information on the facets response, refer to facets Response.

A dictionary of all the requested response data for any facet id requested or related to the facet ids of the response.

Note that the structure of data is flat. Any parentId and child node references will be included in the dictionary. To re-establish the hierarchy, use parentId and/or childIds.

The key to the data is the facet id (either the distince data value or the id of the dimension element for the facet).

  • count

    The facet count that was requested using the request key countType.

    Type: integer

  • label

    The value of the name attribute for the dimension element for the facet id, if the request key includeLabel was set.

    Type: string

  • selected

    Indicates whether the value was requested in a query criterion.

    Type: boolean

  • parentId

    Indicates the parent node ID for hierarchical relationships in tree type dimensions.

    Type: boolean

  • childIds

    Indicates the direct child descendants of the node for hierarchical tree type dimensions.

    Type: array of string.

  • navIds

    Indicates the ancestral nodes that must be navigated through to reach the node.

    Type: array of string.

  • bounds

    If the facets criterion specified includeBounds then the data response will contain a bounds dictionary with the following keys:

facets data bounds Response

The following is a discription of the bounds key of the facets data response. For more information on the facets data response, refer to facets data Response.

  • min

    If the facets request specified includeBounds then for scalar type dimensions this key indicates the minimum value in the bucket.

    Type: number or time

  • max

    If the facets request specified includeBounds then for scalar type dimensions this key indicates the maximum value in the bucket.

    Type: number or time

  • minInclusive

    If the facets request specified includeBounds then for scalar type dimensions this key will be present if the value of min is exclusive only, for example, (30,100].

    Type: boolean

    Default: true

  • maxInclusive

    If the facets request specified includeBounds then for scalar type dimensions this key will be present if the value of max is exclusive only, for example, [30,100).

    Type: boolean

    Default: true

Sample response:

{
  "facets": {
      "category": {
          "childIds": ["a", "b"],
          "data": {
              "a": {
                  "count": 20,
                  "selected": true,
                  "childIds": ["c"]
              },
              "b": {
                  "count": 5,
                  "selected": false
              },
              "c": {
                  "count": 3,
                  "parentId": "a",
                  "selected": false
              }
          }
      }
  }
}

drillDown

The following keys appear for each drillDown criterion that is present in the request.

See: Drilldown Criterion for a detailed description of the drilldown API.
  • dimension

    Id of the dimension this drill down result refers to.

    Type: string

  • ids

    Node/bucket ids.

    Type: array of string

  • exactCounts

    Parallel counts based on the exact match results of the current query.

    Type: array of int

  • fuzzyCounts

    Parallel counts based on all the results of the current query.

    Type: array of int

Properties

The response includes a key named after each changeset property requested in the query or, if no changeset properties were explicitly requested, then the response includes an entry for every changeset property of the item.

If the query request included the highlighting criterion, then any highlighting will be applied to the returned changeset property values.

The order of the dictionaries in the response array is in the same order as the items return in the query response.

The properties are stored in a disk-based database and retrieve on an as-needed basis.

New in version 2.8.3.

Sample query:

{
  "startIndex": 0,
  "pageSize": 10,
  "properties": [
                  "title",
                  "synopsis"
                ]
  "highlighting": {
    "fragmentType": "best",
    "maxFragments": 4,
    "delimiter": "...",
    "template": [ "<b>", "</b>" ],
    "fragmentSize": 100
  },
  "criteria": [
    {
      "dimension": "fulltext",
      "value": "Star Trek",
      "searchStyle": "startsWith"
    }
  ]
}

Sample response:

{
  "totalSize": 34544,
  "pageSize": 2,
  "properties": [
    {
      "title": "<b>Star Trek</b>",
      "synopsis": "Boldly going where no <b>Trek</b> has gone before...beloved
      crew of the <b>Starship</b> Enterprise...attend <b>Starfleet</b> Academy.
      But before they can even sign",
      "genres": "Science Fiction,Drama"
    },
    {
      "title": "<b>Star Trek</b> III: The Search for Spock",
      "synopsis": "Admiral Kirk has his hands full after defeating the evil Khan
       in<b>Star Trek</b> II:Spockisdead."
    }
  ],
  "exactSize": 2234,
  "currentPageSize": 2,
  "itemIds": [
    "17-MV",
    "1958-MV,
  ]
}

Highlighting

The response includes a key named after each changeset property that was highlighted. Tree dimensions are highlighted differently than text type dimensions.

The order of the dictionaries in the response array is in the same order as the items returned in the query response and is returned in the same format as the properties response field.

This field will only be present if the highlighting request merge field was set to none. For more information about the highlighting request, refer to Highlighting Criterion.

New in version 2.8.4.

Index Values

The response includes a key named after each dimension named in the values request. The value is in turn a dictionary with keys containing arrays of the same length as the item result set determined by the pageSize top-level request field.

Multi-values will be returned as arrays.

  • id The indexed value.

  • hit If the corresponding id value resulted in a match for the current

  • label The name attribute of the dimension element for the given

    id that can be used to translate the id to a readable format.

See: indexValues Criterion for a description of the indexValues request API.

New in version 2.9.1.

Sample response for a 3-item response:

{
  "indexValues": {
    "genres": [
        {
          "id": [["CO"],["CD"],["DR","HR"]],
          "hit": [[false],[true],[true,false]]
          "label": [["Comedy"],["Crime Drama"],["Drama","Horror"]],
        }
     ]
  }
}

Calculate

The response includes a key that was defined in the calculate request. The value is in turn one or more calculated values, usually one calculated value per item in the query response.

See: Calculate Criterion for a description of the calculate request API.

New in version 3.1.0.

{
  "calcluate": {
    "distanceFromSchool": [
        "0.234", "1.3433", "10.54"
     ]
  }
}

Values

The response includes a key named after each dimension named in the values request. The value is an array of values, in the order of the items in the response, for the dimension.

See: Values Criterion for a description of the values request API.

Sample response:

{
  "values": {
    "genres": [
        "Comedy",
        [
          "Crime drama",
          "Drama"
        ],
        "Horror"
     ],
    "ethnicity": [
      "white",
      "asian",
      "american indian"
    ]
  }
}

sortBy Response

The response is an array of dictionaries, one entry for each sortBy criterion, in the order in which the criterion were specified. The first field of the response includes the type of sortBy specified in the sortBy request field builtin or dimension.

See: Sort By Criterion for a description of the sortBy request API.
  • builtin The type of builtin dynamic value to used for the sort. Either builtin or dimension will be present for each sortBy response row.

    Type: string

    Values: exactMatch, relevance, id or random

  • dimension The dimension whose value was used for the sort. Either builtin or dimension will be present for each sortBy response row.

    Type: string

  • values The values used for the sort. This array contains an element for every item in the result set, in the same order as the result set items.

    If the dimension is a geoloc dimension then the value will the distance of the item from the geo point specified in the sortBy criterion latitude and longitude fields.

    The units (miles/kilometers) of the distance values will be in the units specified by the sortBy criterion’s distanceUnit field.

    Type: array of values

Sample response:

{
  "currentPageSize": 3,
  "datasetSize": 3,
  "exactMatches": [true, false, false],
  "exactSize": 1,
  "sortBy": [
    {
      "dimension": "Location",
      "values": [8.549, 8.549, 8.549, 9.034, 10.572, 10.572, 11.51,
                    11.51, 11.51, 11.51]
    },
    {
      "builtin": "exactMatch",
      "values": [true, true, true, false, false, false, false,
                    false, false, false]
    },
    {
      "builtin": "relevance",
      "values": [0.9996560800350993, 0.9996560800350993, 0.9996560800350993,
        0.9996365661127987, 0.999574675986841, 0.999574675986841,
        0.9995369569317102, 0.9995369569317102, 0.9995369569317102,
        0.9995369569317102]
    },
    {
      "builtin": "id",
      "values": ["933250", "933251", "933252", "877692", "985783",
                    "993906", "965193", "965194", "965195", "999564"]
    }
  ]
}

DidYouMean

The following keys appear in the dictionary entry for each text didYouMean dimension that appeared in the search criterion request. The key is the id of the dimension.

See: DidYouMean Criterion for a description of the Did You Mean? request API and DidYouMean for a description of the Did You Mean? web service API.

  • tokenCount

    This in an informational value that indicates how many tokens (words) were discovered in the query text.

    Type: integer

  • uncertainCount

    This in an informational value that indicates how many tokens (words), out of the total number of tokens (tokenCount), were not able to be provided with suggestions.

    Type: integer

  • suggestions

    This is a dictionary that returns the suggested query strings. The value of up to maxSuggestions from the didYouMean request limits the number of suggestions returned.

    Suggestions are returned in order of decreasing relevance.

    Type: dictionary

    There are two keys in the dictionary:
    • value. The plain text suggested query string.
    • label. The suggested query string with replaced terms highlighted
  • query

    This is a dictionary that returns the original query used for Did You Mean? as well as the version in which the replaced tokens are highlighted, if highlighting has been enabled.

    Type: dictionary

    There are two keys in the dictionary:
    • value. Original query string used for Did You Mean?
    • label. Query string with replaced terms highlighted

Sample response:

This response returns Did You Mean query suggestions for two dimensions with id “freetext” and “name” respectively.

"didYouMean": {
    "freetext": {
        "tokenCount": 2,
        "uncertainCount": 1,
        "query": {
            "value": "st marys",
            "label": "<i>st</i> <i>marys</i>"
        },
        "suggestions": [
            {
                "value": "st mary",
                "label": "st <i>mary</i>"
            },
            {
                "value": "st maria",
                "label": "st <i>maria</i>"
            },
            {
                "value": "st mark",
                "label": "st <i>mark</i>"
            },
            {
                "value": "st mar",
                "label": "st <i>mar</i>"
            }
        ]
    },
    "name": {
        "tokenCount": 1,
        "uncertainCount": 0,
        "query": {
            "value": "elementary",
            "label": "<i>elementary</i>"
        },
        "suggestions": [
        ]
    }
}

Groups

The following keys appear for each groupBy criterion that also specifies the topN field. Note that the field name for the response is groups.

See: Group By Criterion for a description of the groupBy request API.

  • itemIds

    The list of relevant item ids for each topN item in each group.

    Type: array of array of string

  • exactMatches

    The parallel array (to itemIds) that indicates whether the topN item was an exact match against the query.

    Type: array of array of boolean

  • relevanceValues

    The parallel array (to itemIds) that reports the relevance values for each topN item on this page of the result set.

    Type: array of array of double

  • properties

    The parallel array (to itemIds) that reports the propertiess for each topN item on this page of the result set.

    Type: array of array of double

  • highlighting

    The parallel array (to itemIds) that reports the highlighting for each topN item on this page of the result set.

    Type: array of array of double

  • indexValues

    The parallel array (to itemIds) that reports the indexValues for each topN item on this page of the result set.

    Type: array of array of double

Sample response:

{
  "startIndex": 0,
  "currentPageSize": 3,
  "pageSize": 3,
  "datasetSize": 33853,
  "itemIds": ["1011068", "1030677", "1001509"],
  "exactMatches": [true, true, true],
  "relevanceValues": [1, 1, 1],
  "isGrouped": true,
  "groups": {
    "itemIds": [
      ["854516", "854517"],
      ["971633", "938607"],
      ["5194685", "839126"]
    ],
    "exactMatches": [
      [true, true],
      [true, true],
      [true, true]
    ],
    "relevanceValues": [
      [1, 1],
      [1, 1],
      [1, 1]
    ],
    "indexValues": {
      "City_Id": {
        "hit": [
          [[true, false, false], [true, false, false]],
          [[true], [true]],
          [[true, false, false], [true, false, false]]
        ],
        "value": [
          [["106335-45", "126371-45", "127679-45"], ["106335-45", "126371-45", "127679-45"]],
          [["106335-45"], ["106335-45"]],
          [["106335-45", "126371-45", "127679-45"], ["106335-45", "126371-45", "127679-45"]]
        ]
      }
    },
    "properties": [
      [
        {
          "Baths": "1.0",
          "Beds": "1",
          "State_Name": "Ohio",
          "Zip_Code": "44224"
        },
        {
          "Baths": "2.0",
          "Beds": "2",
          "State_Name": "Ohio",
          "Zip_Code": "44224"
        }
      ],
      [
        {
          "Baths": "1.5",
          "Beds": "2",
          "State_Name": "Ohio",
          "Zip_Code": "44221"
        },
        {
          "Baths": "2.0",
          "Beds": "3",
          "State_Name": "Ohio",
          "Zip_Code": "44221"
        }
      ],
      [
        {
          "Baths": "2.0",
          "Beds": "3",
          "State_Name": "Ohio",
          "Zip_Code": "44224"
        },
        {
          "Baths": "1.0",
          "Beds": "1",
          "State_Name": "Ohio",
          "Zip_Code": "44224"
        }
      ]
    ]
  }
}

The the query or groupBy dimension enables legacyGroupBy then the response will include the following fields.

  • itemIds

    The list of relevant item ids on this page of the result set.

    Type: array of string

  • exactMatches

    The corresponding list of whether the item was an exact match against the query.

    Type: array of boolean

  • relevanceValues

    The corresponding list of relevance values for each item on this page of the result set.

    Type: array of double

    See: Group By Criterion for a description of the groupBy request API.

Sample response:

{
  "currentPageSize": 3,
  "datasetSize": 3,
  "exactMatches": [true, false, false],
  "exactSize": 1,
  "groups": [
    {
      "exactMatches": [true, false, false],
      "itemIds": ["CheapHeavyCircle", "CheapLightCircle", "LightCircle"],
      "relevanceValues": [1, 0.99999999720603228, 0.99999999534338713]
    },
    {
      "exactMatches": [false, false, false],
      "itemIds": ["CheapTriangle", "HeavyTriangle", "ExpensiveLightTriangle"],
      "relevanceValues": [0.99999999860301614, 0.99999999580904841, 0.99999998789280653]
    },
    {
      "exactMatches": [false, false, false],
      "itemIds": ["Square", "ExpensiveHeavySquare", "ExpensiveSquare"],
      "relevanceValues": [0.99999999487772584, 0.99999999161809683, 0.99999999022111297]
    }
  ],
  "isGrouped": true,
  "legacyGroupBy": true,
  "itemIds": ["circle", "triangle", "square"],
  "pageSize": 10,
  "relevanceValues": [1, 0.99999999860301614, 0.99999999487772584],
  "startIndex": 0,
  "totalSize": 3
}

Debug Response

Transparensee Systems reserves the right to alter or remove this API in any way and at any time in the future. It provides this feature solely for debugging purposes.

See: Debug Request for a description of the debug request API.

Example:

{
  "debug": {
    "explain": {
      "10": "... LONG EXPLANATION GOES HERE ..."
    },
    "explainFuzzy": {
      "11": "... LONG EXPLANATION GOES HERE ..."
    },
    "query": "+linearScore(normalDistance=1000000,from=dist(selected=\"[3,4)\",field=bedroom_int_sndv)) #bedroom_i:[3 TO 4}",
    "queryFuzzy": "+linearScore(normalDistance=1000000,from=dist(selected=\"[3,4)\",field=bedroom_int_sndv)) #_dimensions_s:bedroom",
    "sortBy": [
      {
        "builtin": "exactMatch",
        "values": [true,false]
      },
      {
        "builtin": "relevance",
        "values": [1,1]
      },
      {
        "builtin": "id",
        "values": ["10","11"]
      }
    ],
    "time": {
      "search": 0,
      "searchFuzzy": 0,
      "count": 0,
      "page": 0,
      "total": 1
    }
  }
}

renderParmeters

The renderParameters response is used primarily by the Transparensee jQuery widget suite. It returns a single field, “renderParameters”.

See: Render Parameters for a description of the renderParmeters request API.

Sample responses:

{
  "renderParameters": "startIndex=0&pageSize=4&exactSize=9&totalSize=9 \
      &itemIds=CheapHeavyCircle+CheapLightCircle+CheapTriangle+ExpensiveHeavySquare \
      &exactMatches=1111"
}
{
  "renderParameters": "startIndex=0&pageSize=4&exactSize=9&totalSize=9 \
      &itemIds=CheapHeavyCircle%2CCheapLightCircle%2CCheapTriangle%2CExpensiveHeavySquare \
      &exactMatches=1111"
}