Skip to main content

Track Queries

The Track Query API captures search queries that have been made within your application to a search engine/API, and the candidate results of the queries. Amongst other fields, it captures

  • The query as the user entered it (user_query)
  • The ids of the matching candidates for the query (query_response_hit_ids)
  • Any attributes about the query, such as A/B experiment, cohort, query as sent to the search engine, etc. (query_attributes)

Query Flow​

The following sequence diagram illustrates the typical flow for tracking queries:


After your search engine/API responds with the search results for the query, a request should be made to Releval's track query API to capture the details about the query, and the results from the search engine/API.

Query specification​

The OpenAPI specification contains the JSON schema for the query request and response types, QueryRequest and QueryResponse, respectively, for the REST API.

The User Behavior Insights proto contains the proto messages for the query request and response gRPC API: TrackQueryRequest and TrackQueryResponse.

The schema follows Version 1.3.0 of the UBI specification.

Query ID​

The track query API accepts a unique identifier for a query using the query_id field. If unspecified in the request, a unique identifier will be generated by Releval and returned in the track query response.

The query_id is used to associate the query with later events captured by the track event API, so it should be returned in the response to the user.

Query Response ID​

The track query API accepts a unique identifier for a query response using the query_response_id field. If unspecified in the request, a unique identifier will be generated on the server and returned in the track query response.

The query_response_id is useful in scenarios where a user's search creates more than one request to your search API/engine. When this happens, the query_id will be the same for all requests, but the query_response_id will be unique for each request.

Example​

Here's an example request to the track query API:

{
    "application": "primary-search",
    "query_id": "01JE0VKZF8G03G7X16EDE6WNKJ",
    "query_response_id": "01JE0VM6029EVZT2SGHN1VYNAS",
    "query_response_hit_ids": [
        "sku001",
        "sku002",
        "sku003"
    ],
    "client_id": "search_service",
    "user_query": "men's warm winter coat",
    "query_attributes": {
        "query": "{\"query\":{\"match\":{\"title\":{\"query\":\"men's warm winter coat\"}}}}",
        "experiment": "EXP001",
        "cohort": "A"
    },
    "object_id_field": "sku",
    "timestamp": "2024-12-01T00:00:00.0000000Z"
}