Fields are the core of the Project and data modeling. Fields are schemas on how the data is transformed to be used in Tables and Charts, and also for segmenting users. The field types include:

Fields can be accessed by navigating to Model > Fields.

Event Fields

Event Fields define how to transform data at the moment an Event is being processed. An Event Field can make use of the available Event Parameters and User Properties and transforms them into a single value. Event Fields can be used as Dimensions or Measures in a Table, or they can set the value of a Custom User Field.

Event Fields are transformation functions that uses Event Parameters and (optionally) User Attributes as input. The result is always a single value (a number, a date, a string, etc.) These type of fields are auto-generated from event parameters when using the "Automatically scan for events and create fields daily." of your project's options, or by manually adding them using the event scanner.

Event Parameter

An Event Parameter Field simply returns the value received in an Event Parameter, as is, without any transformation. This is the most basic and common case of data modeling.

Consider an Event Field "Total Revenue", whose type is Event Parameter and which is set to take the value of parameter "total" of Event Type "om_revenue". This is represented by the following event:

GET /event?api_key=1234abcd&uid=testuser&om_event_type=om_revenue&total=0.99&currency_code=USD

In this case, the Event Field "Total Revenue" will return the value 0.99.


Counters can calculate either the number of events, or number of unique users. It is equivalent to the SQL formulas count() and count(distinct uid) respectively. You can select only certain Event Type(s) for which you calculate the counts, or you can include all Event Types. More complex conditions for counting can also be created. The counts are aggregated according to the Table date range scope, being "daily" the default option.

Please exercise caution when summing this value across days, as certain values could be duplicated. For instance, if January 1st's count of distinct users is 100, and January 2nd's count is 90, the DAU for January 1st through 2nd is not 190, as users can be active across multiple days.

When scoped for om_revenue Event Type, "Count Events" will tell, for example, the number of purchases made and "Count Distinct Users" the number of buyers/spenders.

Event Formula

Event Formulas provide the full flexibility to define the data transformation. Via the scripting language LUA, formulas (function) can be written such that Event Parameters, Event Meta Data, User State (System User Fields) and/or User Variables (Custom User Fields) can be used as inputs to produce an output. The output is then the value set for the Event Field.

To refer to the different types of fields in LUA:

  • Event Parameters can be referred using event_kvp['<machine name of the parameter>']
  • Event Meta Data can be referred using event_meta['<machine name of the meta field>']
  • Fields in User State (Project, Platform, Environment) can be referred to using user_key['<field in user key>']
  • Other fields in User State can be referred to using user_state['<field in user state>']
  • User Variables (Custom User Fields) can be referred to using user_vars['<machine name of the custom user field>']
Use Case LUA

Calculating the net revenue (70 % of gross revenue)


Get the hour of the Event, using the timestamp'%H', tonumber(event_meta['timestamp']))

Referring to User State


Referring to User Variable (Custom User Field) which contains the amount of coins (cuf_coins) the user has


Lookup Tables

Lookup Tables allow you to transform a value from an Event Field using predefined one-to-one mappings. The resulting value is obtained by performing a lookup in a Lookup Table, using an existing Event Field as key, and returning the selected column where the key match the index column. Conceptually, this is similar to VLOOKUP function, where you pass a value to a function, the function looks up the value in one column, and then returns data from another column.

For example, machine-readable country codes (e.g. "CA") can be transformed to human-readable country names (e.g. "Canada") by using Lookup Tables. The Lookup Dimension must be another Event Field, and a value directly from an Event Parameter cannot be used.

Creating Event Fields

To create a new Event Field, navigate to Model > Fields > 'New...' > Event Field.

Here you can name the Event Field (System name is auto-generated), and also add a description (optional). Depending on the type of field several options become available:

  • Event Parameter:
    • Source: This section defines what parameter gets mapped. The list shows all defined Event Parameters, grouped by Event Type.
    • The format of each item is <Event Type> - <Event Parameter>, for example om_load - uid or om_revenue - total. When you select an item from the list, the Event Field will return the value sent in <Event Parameter> when an Event is of type <Event Type>.
    • If the Event Parameter you are looking for is not in the list, you need to define it in Event Types. Easiest way is to use Event Scan.
  • Counter:
    • Count Type: Count Distinct Users or Count Events. You need to also select for which Event Type(s) the count is done.
  • LUA Formula:
    • This option shows the LUA formula edit. You can also select for which Event Type(s) the formula is executed.
    • Event Type: Scope the execution of the LUA code for the field to a specific event(s).
  • ​Create Look-Up Tables.
    • Look-Up Vaue: The value that will be used to search in the lookup table.
    • Look-Up Table: The Look-up table where the search will be performed.
    • The actual Lookup Tables can be viewed and created in Global Settings > Lookup Tables

User Fields

System User Fields

System User Fields represent values from User State. User States contains basic user properties, such as acquisition date, acquisition country, last known country and lifetime session count. The User States are stored for each user, and System User Fields are transformations of these properties in form of Fields.

Common System User Fields
System User Field Information
User Creation Date The day when the user installed the application. Defined as the day when the user sent the first event to Omniata.
Country Name The last known country of the user. Country Codes are also available. Determined usually by IP location where events come from.
Retained Days The number of days since the acquisition date of the user. Can be used for tracking the activity of users during their life span, for example number of active users on 7th day after acquisition.
Age The age of the user, if demographic data is available (e.g. through Facebook). Age tiers are also available.
Gender The gender of the user, if demographic data is available (e.g. through Facebook).
Experiment Name, Experience Name The Experiments and the Experiences of the Experiments in which the user belongs to. Can be used for tracking and visualizing the Experiment groups.
Accumulated Revenue The total revenue generated by the user during his/her lifetime.
Spender Tier The tier of the user based on his/her accumulated revenue. There are 8 tiers: 0, 0.01–0.99, 1.00–4.99, 5.00–9.99, 10.00–49.99, 50.00–99.99, 100.00–499.99, 500+ (USD).
User Is New Boolean value indicating a user or group of users was new on a specific day. Zero indicates returning users, and one indicates new users.
Accumulated Session Count, Accumulated Session Time The total number of sessions and the total playing time the user has had during his/her lifetime.
Common Fields of User State
Field in User State (system name) Information
User's gender
User's age tier
Country code for user's first country
Country code for user's last country
delta_events, events
Number of the user's events on current day / cumulatively before current day
delta_purchases, purchases
Number of the user's purchases (om_revenue events) on current day / cumulatively before current day
delta_revenue, revenue
Total sum of the user's revenue (in USD) on current day / cumulatively before current day
delta_session_count, session_count
Number of the user's sessions on current day / cumulatively before current day
delta_session_seconds, session_seconds
Total time of the user's sessions on current day / cumulatively before current day
usr_created_at, first_daynum
Epoch timestamp / day number of user's first event
last_event_time, daynum
Epoch timestamp / day number of user's last event
Epoch timestamp of the beginning of user's last session

Custom User Fields

Custom User Fields extend the System User Fields and can be constructed to store user properties specific to the project in which they are contained. These custom user attributes are build on top custom events. A custom user property is, for example, "current user progression position" which uses the progression event and position parameter to construct a project-wide accessible user property; other examples include "in-app location", "date of first purchase", "is premium user", and many more based on individual use cases.

You can refer to any Custom User Field in any LUA formula, using the following notation:
user_vars['<system name of the custom user field>']


Custom User Fields take data processed by Event Fields and store it per user. Custom User Fields can be transient (for example user's level) or non-transient (for example level of first purchase). This type of fields provide "global variables" that are always available when processing events, allowing you to slice any metric by these user properties.

Custom User Fields also persist across events and days, one event can set a Custom User Field and make this property available to other Events in later days. For example, an event called "levelUp" sets the Custom User Field "Level" value today, the next event received tomorrow (say om_revenue) will have available the current level of the user. This allows you to calculate new metrics, like "revenue per level".

Consider the following example: "Level" is defined as a Custom User Field which gets its value from the parameter new_level of the event level_up. A period of two days is evaluated. During the first day the user reaches level 1. During the second day, two more level_up events are received and between them the user makes one purchase worth $1.99 USD. The timeline is as follows:


Activity Date

User Id








If the data is calculated in Reporting Table, the following would be the result:

Activity Date


Count of Users



Creating Custom User Field follows the same steps as creating Event Fields

NOTE: Custom User Fields have a limit of 31 characters.
Setting Custom User Fields values on demand

Omniata supports direct assignation of state values using special event om_update_user. This event is used to modify/update Custom User Fields without altering the rest of user state. In practice this means that these events do not mark the user as active and neither update user’s last action time and other state fields.(e.g. without altering the rest of user state, like "last activity date.")

The special event om_update_user can be used to

  • Update field values in Custom User Fields and System User Fields
  • Set initial Custom User Field values
  • Apply changes to users without triggering user's activity

The fields that this event supports for updating are:

System Name Description
name of acquisition source of the user, e.g. mat||Chartboost|TestGame%20(Default)||
country user last accessed the application from, two characters, e.g. FI
country user access the application from for the first time, two characters, e.g. FI
m for male, f for female, or u for other or unknown, e.g. m
date of birth, days since 1900-03-02
total past revenue of the user, e.g. 15.20
number of purchases user made, e.g. 4
number of times user accessed the application, e.g. 5

To set initial Custom User Field values you can use parameters with the following syntax (where cuf_test is name of the field to update; the key name and value should be URL encoded):


Here is an example event:[cuf_myfield]=myvalue

Segment Fields

Segment Fields are build on Segments created in the Engage section of the Omniata Panel. These segments are used for targeting content to users, and Omniata allows you to create custom visualizations based on them.

When used in a Reporting Table, a Segment Field will split the aggregations by the users who do and do not match the segment criteria.

Creating a Segment Field

Navigate to Model > Fields > New > User Field and select Segment.

  1. Enter name for the Segment Field. This is the display name, and you are allowed to use alphanumeric characters, underscores and spaces.
  2. Add a description (optional). Useful to keep track of the meaning of a field. Useful when users wonder “What does this field mean?”.
  3. Select Source Segment. This will be the segment, previously created under the Engage module, for which the field is created for.
  4. Display Options. The default values for Segment Fields are boolean values True/False (True if user belongs to a segment), which you can customize to your liking.

Once a Reporting Table has been made using a Segment Field, previous week data will provide information of the daily size of the Segment. The DAU and revenue data for users that are eligible and inelgible for the Segment can be beneficial when gauging whether or not the Segment criteria is too narrow, or how much of a potential impact targeting that group of users could have.

Table Fields

Table Fields are SQL formulas, that can be used in Tables. These formulas can take as input other columns, and return a value that is available to be used in a Chart. Table Fields extends Tables with "virtual fields", creating new metrics calculated on-the-fly as functions of existing data. A good example of table fields is "Events per User" which is defined as SUM(ct_events)/SUM(ct_users), where "Count of Events" (ct_events) and "Count of Users" (ct_users) are already existing columns in a Table.

Table Fields do not transform events, nor have access to the Event Parameters or User State during event processing. Table Fields are calculated over already aggregated Tables, and the input for these formulas are already existing columns. In addition, Table Fields will not be included in CSV exports as the CSVs only contain data from actual data fields, not virtual fields.

Creating a Table Field

Navigate to Model > Fields > New > Table Field. Here you can:

  • Formula Builder:
    • Allows simple creation of averages
    • Select Numerator and Denominator from your available fields
    • Name for the Table Field. (This is the display name, and you are allowed to use alphanumeric characters, underscores and spaces)
  • SQL Formula
    • You can use MySQL or BigQuery compatible SQL statements (according to your project's implementation in Omniata)
    • You can refer to existing columns by using the system name of the fields previosly added to the table
    • You cannot refer to other Table Fields.
    • If your formula will be used as a Measure in the Table, it must have aggregation such as SUM, MIN, MAX, COUNT
    • If your formula will be used as a Dimension in the Table, it should not have an aggregation function
  • Table Fields
    • These fields are a 1-1 mapping of existing Table columns, useful for reusing table columns in more than just one table
  • JSON Attributes
    • This fields are specific to BigQuery implementations
    • They extract values from the JSON extructure of Enriched Events

The formula entered must be valid SQL that can run within the SELECT segment of the query. For example, if your formula is used as Dimension:

FROM ... 
WHERE ... 
GROUP BY ..., <Table_Field_Formula>

And when you use the Formula as a Measure:

FROM ... 
WHERE ... 

This article was last updated on July 27, 2016 13:54. If you didn't find your answer here, search for another article or contact our support to get in touch.

Contact Sales

Add Phone Number