Skip to main content

User Behavior Insights

User Behavior Insights (UBI) captures client-side events and server-side queries to improve search relevance and the user experience. You can think of it as user analytics/telemetry specifically for search systems.

It is a causal system, linking a user's query to all of their further interactions with your application until they perform another search. The captured data forms the foundation for building click models and implicit judgment lists.

User Behavior Insights is a standard open source format to define and share user event tracking information.

User Behavior Insights APIs are available as both REST and gRPC APIs. We recommend using the gRPC APIs for optimal performance in high-demand environments.

Queries and Events​

The two fundamental pieces of data that UBI tracks are queries and events. Joining query and event data together provides a comprehensive picture of user behavior that can then be used as input to build better search experiences.

Queries​

A query represents a user's search input and its associated metadata, and the response from a search engine/API.

Key properties include:

  • query_id: A unique identifier for the query, typically a ULID, but can be any string.
  • user_query: The user's query, as they entered it.
  • query_response_hit_ids: The ids of the documents that were returned by the search engine for this query in the order they were returned.
  • query_attributes: Additional metadata about the query, like experiment IDs or other contextual information.

Events​

An event captures a user's interaction following a query, such as impressions, clicking on a search result, or adding an item to a cart.

Key properties include:

  • action_name: Describes the type of interaction, e.g., "click_through", "add_to_cart", or "purchase".
  • query_id: Links the event back to the originating query.
  • timestamp: Records when the event occurred.
  • client_id: Identify the client involved in the event.
  • user_id: Identify the user involved in the event.
  • event_attributes: Provides detailed information about the event, including:
    • object: Details about the item interacted with, such as its ID and type.
    • position: Information about the item's position in the search results or its screen coordinates.