GamebeastDocs
Dashboard

Query Builder

Turn the markers your experience sends into charts: pick a query type, choose what to measure, filter and break it down, set the time range and chart, then save it to a dashboard or share it.

The query builder is how you turn the markers sent to Gamebeast from your experience into charts. You choose what to measure, filter and group it, pick a time range and chart, and save the result as a query on a dashboard.

APurchase
Where
By
Show
Line chart of Purchase050100Mar 2Mar 4Mar 6Mar 8Mar 10Mar 12Mar 14Purchase · Mar 2: 27Purchase · Mar 3: 35Purchase · Mar 4: 45Purchase · Mar 5: 38Purchase · Mar 6: 49Purchase · Mar 7: 72Purchase · Mar 8: 63Purchase · Mar 9: 45Purchase · Mar 10: 41Purchase · Mar 11: 53Purchase · Mar 12: 41Purchase · Mar 13: 61Purchase · Mar 14: 54Purchase · Mar 15: 77

497 unique players over the whole range. Adding up the points gives 701, because a player who buys on two days counts in both.

InteractiveChange the measurement, add a filter, break it down and limit it, and switch the granularity and chart. Click a legend entry to hide a series. The players are made up.

The demo is an insight. Filters, breakdowns, time and saving work the same way in every query type, and this page covers them. What you measure is different for each type: see each type's page.

Query types

Pick the kind of query from the menu at the top of the query setup:

Query typeYou pickCharts
InsightUp to 15 metrics, each an event or a statLine, Column, Bar, Pie, Metric, Table, World Map and more
FunnelTwo or more steps, in orderFunnel Steps, Stacked Steps, Funnel Table, Sankey
User JourneysOne or more anchor events, and steps around themA flow chart of the paths players take
RetentionA start event and a return eventRetention Curve, Cohort Grid, Line, Metric and more
HeatmapAn event sent with a position, and a mapContours drawn over your map

User Journeys is being rolled out. If it isn't in the menu, it isn't enabled for your organization yet.

Opening the builder

  • From a dashboard. Click Edit, then Add panel → Query. When you save, the chart is added to the top of the dashboard and you're taken back to it, with your other unsaved layout changes kept.
  • From Explore. Explore in the project sidebar opens an empty builder that isn't tied to a dashboard. Use it to answer a question without making a chart. When a result is worth keeping, Save asks for a name and a dashboard to put it on.
  • From a chart. Choose Edit in a chart's ⋮ menu to change it.

The assistant and the Community Pulse page can also open a query they built in Explore, ready to change and save.

The query setup sits on the right and a live preview of the chart on the left, which runs again as you change things. Drag the edge between them to resize the setup, or collapse it with the arrow at its bottom to see the chart full width. On a phone, the setup opens from Edit query at the bottom of the screen.

Filters

Filters limit which events a query counts. There are two kinds, and they use the same conditions.

Global filters

Global filters apply to every metric (or step) in the query. Click the + beside Global Filters. Use them when the condition applies to the whole question, such as "players on mobile".

Local filters

Local filters apply to one metric (or step) only. Click the filter icon on a metric, or choose Filter from its ⋯ menu. Use them when only one metric should be limited, such as "purchases of the starter pack" next to all sessions. With more than one local filter, choose whether events must match and all of them or or any of them.

What a filter on one step does depends on the query type. On a retention start event, for example, it decides who enters a cohort; each type's page says.

What you can filter by

The filter picker has a tab for each kind of value, and a search box that looks through all of them:

TabFilters by
ArgumentThe custom arguments you send with your markers, such as Level or ItemName.
PropertyInformation Gamebeast records with every marker, such as Country, Device and Language, plus your custom properties. Nested properties open a level at a time.
UserNew User: only events from each player's first-ever session. First Occurrence: only each player's first-ever occurrence of the event. User ID: specific players.
CohortPlayers who are (Is in) or aren't (Is not in) in one of your user cohorts. Create cohort at the bottom of the tab makes a new one.
ExperimentPlayers in an experiment or in some of its groups, or in any or no experiment.
DeeplinkEvents attributed to a deeplink (Was Used), or not (Was not Used).
PulseWhat players say in your community: each player's overall sentiment, and, with a Pulse metric, a message's topic, source or polarity. Only shown when Community Pulse in the query builder is enabled for you.

A global filter on an argument or property only works if every metric's event has it. If one doesn't, the filter shows Argument does not belong to all metrics selected: use a local filter on the metrics that have it instead.

Conditions

TypeConditions
TextIs, Is not, Contains, Does not contain
NumberEqual, Not equal, Greater than, Greater than or equal to, Less than, Less than or equal to, Between, Not between
True/falseTrue or False
DateIn the last, Not in the last, Between, Not between, On, Not on, Before, Since
ListSome, Every or None of the items match a condition, or the list's Length (plus Average, Sum, Minimum, Maximum for numbers)

Every type also has Exists and Does not exist, for whether the event has the value at all. Is, Contains and Equal accept several values, and an event matches if it matches any of them. Is not, Does not contain and Not equal exclude every value you list.

A filter with no value is ignored and highlighted, and isn't saved.

New players vs. new events

New User and First Occurrence answer different questions. Try both in the demo above:

  • New User keeps only what players did in their first session. "Purchases by new users" counts purchases made during each player's first session.
  • First Occurrence keeps only the first time each player sent the event, whenever that was. "First purchases" counts each player's first purchase, even if it was weeks after they joined, and leaves out players whose first purchase was before the time range.

Neither means "players who joined recently, in all their sessions since". For that, use a cohort.

Breakdowns

A breakdown splits every metric by the values of a property, argument, cohort, experiment or deeplink, with one series for each value. Click the + beside Breakdowns. Breaking down Purchase by Country, as in the demo, shows how many players bought something in each country.

  • Several breakdowns nest: by Country then Device gives one series per combination, such as France / Mobile.
  • New User and First Occurrence break results into true and false, for new vs. returning players or first vs. repeat events.
  • Cohort breaks results into players in and not in the cohort.
  • Experiment gives one series per group, plus players not in the experiment. Choose All experiments for one series per experiment.
  • Filter by, in a breakdown's ⋯ menu, adds a global filter on the same property, so you can pick which values to keep.

Break down by things with a handful of values, like country, platform or item. Breaking down by something unique to each player, like a player ID, produces one series per player.

Limiting and sorting breakdown values

Open a breakdown's ⋯ menu to add:

  • Limit: keep only the top (or bottom) 10, 25, 50 or 100 values, or a custom number up to 1,000. With several metrics, choose which metric decides the top values. The values that don't make the cut are grouped into one Other series, such as Other Country, measured over all their events together. (Retention leaves them out instead.)
  • Sort: order the values By value (largest or smallest first) or By name (A → Z or Z → A).

Without a limit, a breakdown keeps up to 1,000 values, and a time chart shows the first 10 series. Click a series in the legend to show or hide it.

Time

Time range

Above the chart, pick a range: Today, 1H, 7D, 1M or 3M, or open the range picker for more:

  • Presets: Yesterday, Last 15 minutes to Last year, and Week to Date, Month to Date, Quarter to Date and Year to Date.
  • Last: a rolling window, such as the last 14 days. It moves forward with time, so the chart always shows the most recent period.
  • Since: from a date until now.
  • Fixed: between two dates. The chart always shows that period.

On a dashboard, the dashboard's time range replaces each chart's own until it's set back to Default.

Granularity

Time charts (Line, Stacked Line, Column, Stacked Column and Table) show one point per Minute, Hour, Day, Week, Month, Quarter or Year. Changing the time range picks a suitable granularity for you, and you can change it after. Granularities that would produce too many points for the range (more than 48 days, or 16 weeks, for example) are disabled. Retention uses Day, Week or Month.

Drag across a time chart to zoom in. Click Reset Zoom to go back.

Timezone

Days, weeks and months start at midnight in the query's timezone, which is your project's timezone by default. Choose another from the timezone picker beside the time range, such as your local timezone or UTC, to see days as players in another region experience them.

Charts

Pick how to show the results from the chart menu above the preview. Each query type offers the charts that suit it: see Insights, Funnels, Retention and Heatmaps.

Insight charts come in two kinds, as the demo shows:

  • Time charts (Line, Stacked Line, Column, Stacked Column, Table) show a value for each point in time.
  • Whole-range charts (Bar, Stacked Bar, Pie, Metric, World Map) measure the whole time range at once. A whole-range Unique Users counts each player once, so it's usually less than the time chart's points added up.

The ⚙ beside the query type opens the query's options: its description, Invert colors order, and a fixed Min and Max for the value axis.

Saving a query

Name the query in the header above the chart, then click Create (from a dashboard) or Save (from Explore, where you also pick the dashboard). The description, set in the ⚙ options, shows under the chart's title on every dashboard it's on. A saved query records who created it and when it was created and last edited; hover the ⓘ beside the chart's title to see them.

When you edit a saved query:

  • Save updates it everywhere it appears.
  • Save as new keeps the original and saves your changes as a copy, on the dashboard you pick.
  • Discard throws away your changes.

If the query can't be saved yet (a metric with no event, a funnel with one step, a filter on an argument that doesn't exist, an unfinished formula), hover the save button to see why.

A query can appear on more than one dashboard. Editing it changes it everywhere. See Dashboards for arranging, refreshing and exporting your charts.

Sharing a query

On a saved query, Share in the builder's header makes a public link to that one chart, with the same options and PIN as a shared dashboard. Sharing a single chart is being rolled out. If there's no Share button, it isn't enabled for your organization yet.

With the assistant

Ask AI in the builder's header starts a chat with the assistant about the saved query you're looking at. The assistant can also build any query type from a description, such as "a funnel from tutorial start to first purchase" or "daily players by country". It runs the query, shows you the chart, and can open it in the builder or add it to a dashboard. Agents connected over MCP can do the same.

With the API

Run any query type from your own tools with the Analytics Queries endpoints, such as Execute insight query, or run a saved query by its id with Execute saved query.

On this page