feat: add EmptyFilter type to the Data API v1beta

Google APIs · copybara-github · commit 3a6c7dcb9e3b · 2024-11-20T14:13:03.000-08:00
feat: add the `empty_filter` field to the `Filter` type
docs: update documentation for the`RunReport` method
docs: remove all references to 'GA4' in documentation

PiperOrigin-RevId: 698517184
diff --git a/google/analytics/data/v1beta/analytics_data_api.proto b/google/analytics/data/v1beta/analytics_data_api.proto
@@ -71,7 +71,7 @@ service BetaAnalyticsData {
   }
 
   // Returns multiple reports in a batch. All reports must be for the same
-  // GA4 Property.
+  // Google Analytics property.
   rpc BatchRunReports(BatchRunReportsRequest)
       returns (BatchRunReportsResponse) {
     option (google.api.http) = {
@@ -81,7 +81,7 @@ service BetaAnalyticsData {
   }
 
   // Returns multiple pivot reports in a batch. All reports must be for the same
-  // GA4 Property.
+  // Google Analytics property.
   rpc BatchRunPivotReports(BatchRunPivotReportsRequest)
       returns (BatchRunPivotReportsResponse) {
     option (google.api.http) = {
@@ -92,7 +92,7 @@ service BetaAnalyticsData {
 
   // Returns metadata for dimensions and metrics available in reporting methods.
   // Used to explore the dimensions and metrics. In this method, a Google
-  // Analytics GA4 Property Identifier is specified in the request, and
+  // Analytics property identifier is specified in the request, and
   // the metadata response includes Custom dimensions and metrics as well as
   // Universal metadata.
   //
@@ -256,7 +256,7 @@ service BetaAnalyticsData {
 // report; fields shared with the `runReport` request should be the same values
 // as in your `runReport` request.
 message CheckCompatibilityRequest {
-  // A Google Analytics GA4 property identifier whose events are tracked. To
+  // A Google Analytics property identifier whose events are tracked. To
   // learn more, see [where to find your Property
   // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
   // `property` should be the same value as in your `runReport` request.
@@ -318,7 +318,7 @@ message Metadata {
 
 // The request to generate a report.
 message RunReportRequest {
-  // A Google Analytics GA4 property identifier whose events are tracked.
+  // A Google Analytics property identifier whose events are tracked.
   // Specified in the URL path and not the body. To learn more, see [where to
   // find your Property
   // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
@@ -378,9 +378,13 @@ message RunReportRequest {
 
   // Aggregation of metrics. Aggregated metric values will be shown in rows
   // where the dimension_values are set to "RESERVED_(MetricAggregation)".
+  // Aggregates including both comparisons and multiple date ranges will
+  // be aggregated based on the date ranges.
   repeated MetricAggregation metric_aggregations = 9;
 
   // Specifies how rows are ordered in the response.
+  // Requests including both comparisons and multiple date ranges will
+  // have order bys applied on the comparisons.
   repeated OrderBy order_bys = 10;
 
   // A currency code in ISO4217 format, such as "AED", "USD", "JPY".
@@ -396,15 +400,15 @@ message RunReportRequest {
   // removed by a filter.
   //
   // Regardless of this `keep_empty_rows` setting, only data recorded by the
-  // Google Analytics (GA4) property can be displayed in a report.
+  // Google Analytics property can be displayed in a report.
   //
   // For example if a property never logs a `purchase` event, then a query for
   // the `eventName` dimension and  `eventCount` metric will not have a row
   // eventName: "purchase" and eventCount: 0.
   bool keep_empty_rows = 13;
 
-  // Toggles whether to return the current state of this Analytics Property's
-  // quota. Quota is returned in [PropertyQuota](#PropertyQuota).
+  // Toggles whether to return the current state of this Google Analytics
+  // property's quota. Quota is returned in [PropertyQuota](#PropertyQuota).
   bool return_property_quota = 14;
 
   // Optional. The configuration of comparisons requested and displayed. The
@@ -448,7 +452,7 @@ message RunReportResponse {
   // Metadata for the report.
   ResponseMetaData metadata = 8;
 
-  // This Analytics Property's quota state including this request.
+  // This Google Analytics property's quota state including this request.
   PropertyQuota property_quota = 9;
 
   // Identifies what kind of resource this message is. This `kind` is always the
@@ -459,7 +463,7 @@ message RunReportResponse {
 
 // The request to generate a pivot report.
 message RunPivotReportRequest {
-  // A Google Analytics GA4 property identifier whose events are tracked.
+  // A Google Analytics property identifier whose events are tracked.
   // Specified in the URL path and not the body. To learn more, see [where to
   // find your Property
   // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
@@ -513,15 +517,15 @@ message RunPivotReportRequest {
   // removed by a filter.
   //
   // Regardless of this `keep_empty_rows` setting, only data recorded by the
-  // Google Analytics (GA4) property can be displayed in a report.
+  // Google Analytics property can be displayed in a report.
   //
   // For example if a property never logs a `purchase` event, then a query for
   // the `eventName` dimension and  `eventCount` metric will not have a row
   // eventName: "purchase" and eventCount: 0.
   bool keep_empty_rows = 10;
 
-  // Toggles whether to return the current state of this Analytics Property's
-  // quota. Quota is returned in [PropertyQuota](#PropertyQuota).
+  // Toggles whether to return the current state of this Google Analytics
+  // property's quota. Quota is returned in [PropertyQuota](#PropertyQuota).
   bool return_property_quota = 11;
 
   // Optional. The configuration of comparisons requested and displayed. The
@@ -590,7 +594,7 @@ message RunPivotReportResponse {
   // Metadata for the report.
   ResponseMetaData metadata = 6;
 
-  // This Analytics Property's quota state including this request.
+  // This Google Analytics property's quota state including this request.
   PropertyQuota property_quota = 7;
 
   // Identifies what kind of resource this message is. This `kind` is always the
@@ -601,7 +605,7 @@ message RunPivotReportResponse {
 
 // The batch request containing multiple report requests.
 message BatchRunReportsRequest {
-  // A Google Analytics GA4 property identifier whose events are tracked.
+  // A Google Analytics property identifier whose events are tracked.
   // Specified in the URL path and not the body. To learn more, see [where to
   // find your Property
   // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
@@ -630,7 +634,7 @@ message BatchRunReportsResponse {
 
 // The batch request containing multiple pivot report requests.
 message BatchRunPivotReportsRequest {
-  // A Google Analytics GA4 property identifier whose events are tracked.
+  // A Google Analytics property identifier whose events are tracked.
   // Specified in the URL path and not the body. To learn more, see [where to
   // find your Property
   // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
@@ -661,7 +665,7 @@ message BatchRunPivotReportsResponse {
 message GetMetadataRequest {
   // Required. The resource name of the metadata to retrieve. This name field is
   // specified in the URL path and not URL parameters. Property is a numeric
-  // Google Analytics GA4 Property identifier. To learn more, see [where to find
+  // Google Analytics property identifier. To learn more, see [where to find
   // your Property
   // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
   //
@@ -680,7 +684,7 @@ message GetMetadataRequest {
 
 // The request to generate a realtime report.
 message RunRealtimeReportRequest {
-  // A Google Analytics GA4 property identifier whose events are tracked.
+  // A Google Analytics property identifier whose events are tracked.
   // Specified in the URL path and not the body. To learn more, see [where to
   // find your Property
   // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
@@ -719,8 +723,9 @@ message RunRealtimeReportRequest {
   // Specifies how rows are ordered in the response.
   repeated OrderBy order_bys = 8;
 
-  // Toggles whether to return the current state of this Analytics Property's
-  // Realtime quota. Quota is returned in [PropertyQuota](#PropertyQuota).
+  // Toggles whether to return the current state of this Google Analytics
+  // property's Realtime quota. Quota is returned in
+  // [PropertyQuota](#PropertyQuota).
   bool return_property_quota = 9;
 
   // The minute ranges of event data to read. If unspecified, one minute range
@@ -760,7 +765,8 @@ message RunRealtimeReportResponse {
   // only 50 rows.
   int32 row_count = 7;
 
-  // This Analytics Property's Realtime quota state including this request.
+  // This Google Analytics property's Realtime quota state including this
+  // request.
   PropertyQuota property_quota = 8;
 
   // Identifies what kind of resource this message is. This `kind` is always the
diff --git a/google/analytics/data/v1beta/data.proto b/google/analytics/data/v1beta/data.proto
@@ -318,6 +318,9 @@ message Filter {
     NumericValue to_value = 2;
   }
 
+  // Filter for empty values.
+  message EmptyFilter {}
+
   // The dimension name or metric name.
   //
   // In most methods, dimensions & metrics can be used for the first time in
@@ -339,6 +342,9 @@ message Filter {
 
     // A filter for two values.
     BetweenFilter between_filter = 6;
+
+    // A filter for empty values such as "(not set)" and "" values.
+    EmptyFilter empty_filter = 8;
   }
 }
 
@@ -1048,8 +1054,8 @@ enum MetricType {
   TYPE_KILOMETERS = 13;
 }
 
-// Categories of data that you may be restricted from viewing on certain GA4
-// properties.
+// Categories of data that you may be restricted from viewing on certain
+// Google Analytics properties.
 enum RestrictedMetricType {
   // Unspecified type.
   RESTRICTED_METRIC_TYPE_UNSPECIFIED = 0;
