Query logic of the test (Google Analytics 4 data)

Structure of the Google Analytics 4 Query logic

For data from Google Analytics 4 data source the Query logic has the following structure, you have an array of one or more requests. For each request you need to specify parameters separately. Each request has to include the required parameters: dateRanges and metrics. The main query parameters are described in detail below. Here is a full example of the simplest Query logic content.

{
    "requests": [
        {
            "dateRanges": [
                {
                    "startDate": "2021-03-01",
                    "endDate": "2021-03-31"
                }
            ],
            "metrics": [
                {
                    "name": "sessions"
                }
            ],
            "metricAggregations": [
                "TOTAL"
            ]
        }
    ]
}

Use of multiple requests

While there are powerful tests that require only a single query, often you need to compare data that cannot be fitted within a single table (for example, if you want to compare multiple separate filtering conditions). To receive a result with multiple tables of data, you can specify multiple requests.

Multiple requests are practical for example for comparison of data with and without a filter. Parameter dateRange can vary between requests, however, unlike classical GA between-query output reference not allowed.

Date range

First you need to specify the dates range for which you require data. The dateRanges consists of an array with at least one object which contains a combination of date thresholds called startDate and endDate. In particular, the parameter startDate is the first date to include data for and the endDate is the last date to include data for. The dateRanges is a required parameter for the query.

There are 3 options for the format of the parameters:

1. "today" or "yesterday" = to start or end with data from yesterday
2. "[N]daysAgo" where instead of [N] you fill in a positive whole number
3. Full date in format "YYYY-MM-DD", for example "2020-06-01"

A full example of the dateRanges loading data for last 7 days preceding the current date:

"dateRanges": [{
        "startDate": "7daysAgo",
        "endDate": "yesterday"
      }
]

"dateRanges": [{
        "startDate": "7daysAgo",
        "endDate": "yesterday"
      },{
        "startDate": "28daysAgo",
        "endDate": "yesterday"
      }
]

Metrics

The second and only other required parameter is the field for metrics, individual measurements of user activity on your property, such as sessions and pageviews, that can be extracted from your Google Analytics 4 data. When a query contains only dateRanges and metrics, the resulting data is the aggregation of the values for all selected days.

There can be one or more metrics expression, specified as array of objects. To include a metric, select an existing name of a Google Analytics 4 metric and input it as the value for the "name" key. The names can be searched in the list of available metrics. Contrary to classical Google Analytics no "ga:" prefix is necessary. An example of the metrics array follows:

"metrics": [{
        "name": "sessions"
      },{
        "name": "totalUsers"
      }
]

Unlike previous versions of Google Analytics, aggregate values for metrics are not automatically included. To include the aggregate values, you need to specify the "metricAggregations" parameter which is an array where you list the aggregations you need. Possible values are "TOTAL" (sum of all values for given metric), "MINIMUM" (minimum value for given metric) and "MAXIMUM" (maximum value for given metric).

"metricAggregations": [
    "TOTAL", 
    "MINIMUM", 
    "MAXIMUM"
  ]

"metrics": [{
        "name": "sessions",
        "alias": "Sessions",
      },{
        "name": "Sessions per User ratio",
        "expression": "sessions/totalUsers"
      }
]

Dimensions

To extract more than just the aggregate values for the selected metrics, you need to specify dimensions. When you include the dimensions parameter, there can be one or more dimensions names within, specified as array of objects. To include a dimension, select an existing name of a Google Analytics dimension and input it as the value for the "name" key. The names can be searched in the official list of available dimensions. An example of the dimensions array follows:

"dimensions": [{
        "name": "date"
      },{
        "name": "hostName"
      }
]

Ordering

To order the requested data, you can specify the OrderBys parameter. It is an array of objects consisting of the following structure:

1. either "dimension" or "metric" or "pivot" specifiying the type of the ordering with further settings
2. "desc" with value either false (for sorting from smallest to largest) or true (for sorting from largest to smallest)

For sorting according to a metric, you only need to specify the metric name. The following example shows ordering by sessions from highest to lowest amount:

"orderBys": [
        {
          "metric": {
            "metricName": "sessions"
          },
          "desc": true
        }
      ]

For sorting according to a dimension, you specify the name of the dimension and you can additionally specify the orderType parameter. The default value for the orderType parameter is ALPHANUMERIC, which is the expected sorting for string values (for other case see the tip below). The following example shows ordering by date from oldest to newest.

"orderBys": [
        {
          "dimension": {
            "dimensionName": "date"
          },
          "desc": false
        }
      ]

Filters’ options

Google Analytics 4 dropped the one-line filter expression that is available in the classical Google Analytics. There is a separate filter object for filtering dimensions ("dimensionFilter") and metrics ("metricFilter"). The structure inside the objects is the same:

1. first you need to specify whether you want a single filter (by using "filter" parameter as in the following example), or whether you want to wrap more filters inside "andGroup" or "orGroup".
2. inside an individual filter you specify the "fieldName" parameter as the dimension or metric you want to filter on
3. next you choose a type of the filter:
   • stringFilter - comparison of dimension values to a single value
   • inListFilter - evaluation if dimension values are present in a list of strings
   • numericFilter - comparison of (mostly) metric values to a single value
   • betweenFilter - comparison of (mostly) metric values if they are between two values

The following example shows a dimension filter which leaves in the data only deviceCategory equal to "desktop". The values for the "matchType" parameter include: "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP" and "PARTIAL_REGEXP".

"dimensionFilter": {
    "filter": {
      "fieldName": "deviceCategory",
      "stringFilter": {
        "matchType": "EXACT",
        "value": "desktop",
        "caseSensitive": true
      }
    }
  }

For the inListFilter you need to specify only the parameter "value" with an srray of possible values.

The next example shows a metric filter filtering the data to keep only rows with sessions greater than 100. In a numeric filter it is required to specify the type of number included as a comparison value (options are "int64Value" with input as a string and "double" with input without the quotes as a normal number). The values for the "operation" parameter include: "EXACT", "GREATER_THAN", "LESS_THAN", "GREATER_THAN_OR_EQUAL", "LESS_THAN_OR_EQUAL".

"metricFilter": {
    "filter": {
      "fieldName": "sessions",
      "numericFilter": {
        "operation": "GREATER_THAN",
        "value": {
          "int64Value": "100"
        }
      }
    }
  }

For the betweenFilter you need to specify two parameters, "fromValue" and "toValue", to define the (inclusive) limits. Again you are required to specify the type of number included as a comparison value (as for the numericFilter).

When you want to combine multiple filters, you can use the "andGroup" and "orGroup" parameters. For filtering data where a condition does not hold, you can use the "notExpression". To provide an example of all these three parameters, the following filter applies two conditions to dimensions: deviceCategory can be only equal to "desktop" and browser must not be equal to "Safari", and one of these two conditions must hold for the metrics: either there were zero sessions, or there were zero users.

More about the options for filters can be found in the official documentation.

"dimensionFilter": {
    "andGroup": {
      "expressions": [
        {
          "filter": {
            "fieldName": "deviceCategory",
            "stringFilter": {
              "matchType": "EXACT",
              "value": "desktop",
              "caseSensitive": true
            }
          }
        },
        {
          "notExpression": {
            "filter": {
              "fieldName": "browser",
              "stringFilter": {
                "matchType": "EXACT",
                "value": "Safari",
                "caseSensitive": true
              }
            }
          }
        }
      ]
    }
  },
  "metricFilter": {
    "orGroup": {
      "expressions": [
        {
          "filter": {
            "fieldName": "sessions",
            "numericFilter": {
              "operation": "EQUAL",
              "value": {
                "int64Value": "0"
              }
            }
          }
        },
        {
          "filter": {
            "fieldName": "totalUsers",
            "numericFilter": {
              "operation": "EQUAL",
              "value": {
                "int64Value": "0"
              }
            }
          }
        }
      ]
    }
  }