Skip to main content
Gainsight Inc.

Query Builder

This article explains how to configure and use the Query Builder analytics feature for your application.


Query builder is designed to answer tough product questions. Get the flexibility you need to create custom analytics without having to learn another query language. Compare usage across audiences and group results to gain unprecedented insights.

Example Business Use Cases:

  • Answer tough product questions with flexible query-like language
  • Compare user behavior across different audiences
  • Use different visualization methods to analyze results

Compare Different Audiences

Track specific events and compare any number of different cohorts and behaviors to learn more about a specific behavior or validate a specific hypothesis. 

Gainsight PX allows you to customize the name of the event or audience on the Query Builder filter. This helps you easily understand the events or audience pertaining to the filtered query. The event labels are auto-populated from the last part of the selected feature name and you can modify them. These labels are displayed in the Query Builder chart area as legends, and in the data rows.

Note: Query Builder graphs can now be viewed as Pie Charts.

Drill-Down Capability

Query Builder provides you the ability to drill down from the query result numbers to a detailed list of the underlying users or accounts. You can click the user or account count from the query result to navigate to the users or accounts list view. 

In the case of users, a further drill-down on an individual user helps you view the user profile and check their recent activity and engagements. Within the drill-down view of the Query Builder, you can switch between different cohorts as well as between different time periods.

Track Historical Behaviour 

You can build queries to analyze the time-lapsed cohort behaviour of different User and Account audiences. Gainsight PX supports a maximum of ten user and account attributes with historical values tracking that can now be leveraged to build queries. The Audience section in Query Builder supports historical tracking of User and Account attributes that can be used in queries.

This feature helps to:

  • Find cohorts that have specific current and/or historical values
  • Compare cohort behavior between historical and current values (using different audiences).

QB Historical Tracking.png

Group-Specific Events or Attributes

You can use the Group By field to aggregate results based on specific fields. Grouping the analytics data helps you gain insights from multiple custom events and analyze results quickly.   

Event Properties in Query Builder

Users can select the following event properties to analyze the product usage behaviors across audiences and group results to gain granular insights. 

  • Custom Events
  • Feature Events
  • Engagement Events
  • Session Initialization Events
  • Page View Events
  • Mobile Screen Events

Custom Event Properties

You can analyze custom event properties based on property values. This may come in handy when you want to measure the event properties such as video play counts or monetary values you're passing to Gainsight PX through Custom Events.

Global Context queries provides you the ability to have granular querying experience. 

For more information, refer to the Use Custom Event API article from the Additional Resources section.

Query Custom event.jpeg

For more information about all frequently asked questions, refer to the Analytics FAQs article from the Additional Resources section.

When you create a query with numerical attributes of custom events, you can evaluate the results using Property Value aggregations.

Property Values.png

Feature Events

Users can select events based on channel/feature in the Event dropdown list. The events are grouped into the following categories:

  • Web App Features
  • Mobile Features

Note: You can build queries using the All Features events that helps you define a cohort of users who have visited these features.

Use Labels for Feature Events

You can create labels for your product features or modules in Product Mapper. These labeled features can then be used to build queries to filter feature data.

Example Business Use Cases: Consider that you want to track the usage of features and modules that are shared as part of an onboarding guide. Group all the features using a label and then build queries to filter feature data.

QB Lables.jpg

Engagement Events

Users can now select engagement events in the Query Builder to create custom analytics and gain deeper insights into audience behaviors. You can further refine your query by selecting the required engagement type and its attributes.

Example Business Usecase: Create a query to find the number of views on a NPS Survey engagement among the android users who has submitted the survey response with a promoter score.

QB 1.jpeg


  • Query Builder results related to surveys can display results that are grouped by options of survey Score and Score type across NPS, CES, Rating, and Boolean surveys, allowing for a deeper analysis of the survey results.
  • You can build queries using All Engagements events that helps you define a cohort of users who interacted with the engagements.

Session Initialization Events

The Session Init option helps you query on user sessions data along with other query options in the event and audience sections. You can create queries to find out the details of the sessions initialized by users based on the attributes such as Global Context, Inferred LocationDevice, and Platform.

Query Session Init.jpeg

Page View Events

The Page View option helps to query on various page view events using various URL and UTM parameters as given below:

 URL parameters:

  • Hostname identifies the host that holds the resource. 
  • Page Title is a short description of a webpage that appears at the top of a browser window 
  • Path represents a specific section or page of your application or website. 
  • Query Parameter represents a set of parameters added to the base URL (along with a value usually) to get specific content or denote an action from your application or website
  • Referrer is the webpage that sends visitors to your site using a link.
  • Scheme identifies the protocol to be used to access the resource on the Internet. It can be HTTP (without SSL) or HTTPS (with SSL).
  • URI is a sequence of characters that distinguishes one resource from another.

UTM parameters:

  • utm_source: Identifies which site sent the traffic.
  • utm_medium: Identifies what type of link was used, such as cost per click or email.
  • utm_campaign: Identifies a specific product promotion or strategic campaign.
  • utm_term: Identifies the (paid) keyword associated with the traffic
  • utm_content: Identifies what specifically was clicked to bring the user to the site, such as a banner ad or a text link. 

Page view qury.png

Mobile Screen Events

Mobile screen events helps you create queries based on the screen events and their attributes such as platform, screen name or screen class. You can also add the Group By attributes to get the required query results.



  • You can add different combinations of events and audience that totals to six.
  • Query Builder supports selection of multiple features, engagements and custom events. You can build queries to analyze a cohort of users who have visited these features, interacted with engagements and involved with custom events.

Export Query Builder Report to CSV

You can export the Query Builder report data as a CSV file to suit your needs of insights or further analysis. To export Query Builder data, click on Export CSV

Query Builder_export.jpeg


  • The query results list view section displays 200 rows of cohort(s) data. 

QB Rows.jpg

  • The export limit for Query Builder CSV reports is 100K rows.

Additional Resources

Analytics FAQs
Use Custom Event API
  • Was this article helpful?