Documentation

Did you find this helpful?

Real-time Analytics: Event Queries

Several PlayFab Real-time Analytics tools support querying for a specific set of events. Each query is represented as text expression and follows rules described in this document. 

Consider the following event:

{
    "EventName": "title_statistic_version_changed",
    "StatisticName": "tournamentScore_hourly",
    "StatisticVersion": 1290,
    "ScheduledResetInterval": "Hour",
    "ScheduledResetTime": "2017-04-17T09:00:00Z",
    "EventNamespace": "com.playfab",
    "EntityType": "title",
    "Source": "PlayFab",
    "EventId": "a1883560c93b43f5b0543ade2d8cd093",
    "EntityId": "6EEA",
    "SourceType": "BackEnd",
    "Timestamp": "2017-04-17T09:00:22.4012656Z",
    "History": null,
    "CustomTags": null,
    "Reserved": null
}

In PlayFab, event is represented as object with a set of fields. Each field has value. User can compose query expression to filter events by specific values on one or more fields. Query expressions can be simplistic or complex.

PlayFab Free Tier only allows searching by default event fields. Paid Tier enables searching by custom event fields. Please post on our forums to ask about paid tiers and enabling PlayStream history.

SIMPLISTIC QUERIES

Simplistic query is just a value you want to search for. PlayFabgoes through each property of each event looking for that specific value.

For example, consider the aforementioned event and it's field called "StatisticName". This field has value: "tournamentScore_hourly". Using event search query "tournamentScore_hourly" (1), you may click "Run Query" button (2). The result will be rendered in the Event Timeline list (3) and will contain the subject event.

This happens because PlayFab analyzed all the events and found that this particular event has some property with the value of "tournamentScore_hourly". Important: PlayFab supports wildcards and some of the regex expressions. This means that you may search by part of the value:

For example, a query "tournamentScore_" (1) will result into no events in the list (2). Using wildcard, we may adjust query to "tournamentScore_*" (3) and this will result into all events that have a field with the value starting with "tournamentScore_" (4). Using this technique, you can quickly search for relevant events with no need to build complex queries or to use query builder.

COMPLEX QUERIES

To run complex analysis you will need complex queries with several conditions. For this purpose you can use complex queries. Complex query consists of one or more query expressions separated by AND/OR operators.

Filter expression is an expression that consists of 2 parts and has the following format: object_property:value_descriptor

Object property points to a property on your event data (that you want to filter by) and generally looks like this: "eventData.propertyName<.otherPropertyName*>"eventData part is absolutely necessary to point PlayFab to an event object. You can then extract specific properties using dot notation: eventData.eventName. You may also refer to nested propeties like this: eventData.history.triggeredEvents

Important: object property requires camelCase parts starting from a lowercase letter. For example, each event has property called EventName. However, to access this property in a query you have to adjust the first letter of the property and use: eventData.eventName.

Value descriptor is an expression that describes the value of the field you want to filter by. The simplest form of value descriptor is the value itself. The following query will look for all events with names equal to player_created

eventData.eventName:player_created

We can customize value descriptor by kicking in some regular expression elements, like wildcards. By convention, all PlayFab's player oriented event names start from player_: 

The following query will let us locate all such events:

eventData.eventName:player_*

Another example of complicated value descriptor is a descriptor for date property. The following query incorporates all the events which have timestamp between April 1st and April 17th:

eventData.timestamp:[2017-04-01T00:00:00 TO 2017-04-17T00:00:00]

Finally, we can combine several filter expressions using AND/OR operators and parenthesis for grouping. The following query will locate all the events that happened from April 1st to April 17th and have event name either player_logged_in or player_statistic_changed

eventData.timestamp:[2017-04-01T00:00:00 TO 2017-04-17T00:00:00]  AND ( eventData.eventName:player_logged_in OR eventData.eventName:player_statistic_changed )



Did you find this helpful?