[Monitor Query] Update filter docstrings (#34974)

pvaneck · web-flow · commit ccaf592492ad · 2024-03-28T10:39:12.000-07:00
These were using `$filter`, but this is misleading. Updated to reflect
more accurate usage.

Signed-off-by: Paul Van Eck &lt;paulvaneck@microsoft.com&gt;
diff --git a/sdk/monitor/azure-monitor-query/azure/monitor/query/_metrics_client.py b/sdk/monitor/azure-monitor-query/azure/monitor/query/_metrics_client.py
@@ -84,23 +84,39 @@ def query_resources(
         :keyword order_by: The aggregation to use for sorting results and the direction of the sort.
             Only one order can be specified. Examples: 'sum asc', 'maximum desc'.
         :paramtype order_by: Optional[str]
-        :keyword filter: The **$filter** is used to reduce the set of metric data returned. Example:
-            Metric contains metadata A, B and C. - Return all time series of C where A = a1 and B = b1 or
-            b2 **$filter=A eq 'a1' and B eq 'b1' or B eq 'b2' and C eq '*'** - Invalid variant: **$filter=A
-            eq 'a1' and B eq 'b1' and C eq '*' or B = 'b2'** This is invalid because the logical or
-            operator cannot separate two different metadata names. - Return all time series where A = a1,
-            B = b1 and C = c1: **$filter=A eq 'a1' and B eq 'b1' and C eq 'c1'** - Return all time series
-            where A = a1 **$filter=A eq 'a1' and B eq '*' and C eq '*'**. Special case: When dimension
-            name or dimension value uses round brackets. Eg: When dimension name is **dim (test) 1**
-            Instead of using **$filter= "dim (test) 1 eq '*'"** use **$filter= "dim %2528test%2529 1 eq '*'"**.
-            When dimension name is **dim (test) 3** and dimension value is **dim3 (test) val**, instead of using
-            **$filter= "dim (test) 3 eq 'dim3 (test) val'"** use **$filter= "dim
-            %2528test%2529 3 eq 'dim3 %2528test%2529 val'"**. Default value is None.
+        :keyword filter: The **filter** is used to reduce the set of metric data returned. Default value is None.
+
+            Example: Metric contains metadata A, B and C.
+
+            - Return all time series of C where A = a1 and B = b1 or b2:
+
+              **filter="A eq 'a1' and B eq 'b1' or B eq 'b2' and C eq '*'"**
+
+            - Invalid variant:
+
+              **filter="A eq 'a1' and B eq 'b1' and C eq '*' or B = 'b2'"**. This is invalid because the
+              logical 'or' operator cannot separate two different metadata names.
+
+            - Return all time series where A = a1, B = b1 and C = c1:
+
+              **filter="A eq 'a1' and B eq 'b1' and C eq 'c1'"**
+
+            - Return all time series where A = a1:
+
+              **filter="A eq 'a1' and B eq '*' and C eq '*'"**
+
+            - Special case: When dimension name or dimension value uses round brackets. Example: When dimension name
+              is **dim (test) 1**, instead of using **filter="dim (test) 1 eq '*'"** use
+              **filter="dim %2528test%2529 1 eq '*'"**.
+
+              When dimension name is **dim (test) 3** and dimension value is
+              **dim3 (test) val**, instead of using **filter="dim (test) 3 eq 'dim3 (test) val'"**, use **filter="dim
+              %2528test%2529 3 eq 'dim3 %2528test%2529 val'"**.
         :paramtype filter: str
         :keyword roll_up_by: Dimension name(s) to rollup results by. For example if you only want to see
             metric values with a filter like 'City eq Seattle or City eq Tacoma' but don't want to see
             separate values for each city, you can specify 'City' to see the results for Seattle
-            and Tacoma rolled up into one timeseries. Default value is None.
+            and Tacoma rolled up into one timeseries.
         :paramtype roll_up_by: str
         :return: A list of MetricsQueryResult objects.
         :rtype: list[~azure.monitor.query.MetricsQueryResult]
diff --git a/sdk/monitor/azure-monitor-query/azure/monitor/query/_metrics_query_client.py b/sdk/monitor/azure-monitor-query/azure/monitor/query/_metrics_query_client.py
@@ -98,25 +98,41 @@ def query_resource(
          `azure.monitor.query.MetricAggregationType` enum to get each aggregation type.
         :paramtype aggregations: Optional[list[str]]
         :keyword max_results: The maximum number of records to retrieve.
-         Valid only if $filter is specified.
+         Valid only if 'filter' is specified.
          Defaults to 10.
         :paramtype max_results: Optional[int]
         :keyword order_by: The aggregation to use for sorting results and the direction of the sort.
          Only one order can be specified.
          Examples: sum asc.
         :paramtype order_by: Optional[str]
-        :keyword filter: The **$filter** is used to reduce the set of metric data returned. Example:
-         Metric contains metadata A, B and C. - Return all time series of C where A = a1 and B = b1 or
-         b2 **$filter=A eq 'a1' and B eq 'b1' or B eq 'b2' and C eq '*'** - Invalid variant: **$filter=A
-         eq 'a1' and B eq 'b1' and C eq '*' or B = 'b2'** This is invalid because the logical or
-         operator cannot separate two different metadata names. - Return all time series where A = a1, B
-         = b1 and C = c1: **$filter=A eq 'a1' and B eq 'b1' and C eq 'c1'** - Return all time series
-         where A = a1 **$filter=A eq 'a1' and B eq '*' and C eq '*'**. Special case: When dimension
-         name or dimension value uses round brackets. Eg: When dimension name is **dim (test) 1**
-         Instead of using **$filter= "dim (test) 1 eq '*'"** use **$filter= "dim %2528test%2529 1 eq '*'"**.
-         When dimension name is **dim (test) 3** and dimension value is **dim3 (test) val**, instead of using
-         **$filter= "dim (test) 3 eq 'dim3 (test) val'"** use **$filter= "dim
-         %2528test%2529 3 eq 'dim3 %2528test%2529 val'"**. Default value is None.
+        :keyword filter: The **filter** is used to reduce the set of metric data returned. Default value is None.
+
+            Example: Metric contains metadata A, B and C.
+
+            - Return all time series of C where A = a1 and B = b1 or b2:
+
+              **filter="A eq 'a1' and B eq 'b1' or B eq 'b2' and C eq '*'"**
+
+            - Invalid variant:
+
+              **filter="A eq 'a1' and B eq 'b1' and C eq '*' or B = 'b2'"**. This is invalid because the
+              logical 'or' operator cannot separate two different metadata names.
+
+            - Return all time series where A = a1, B = b1 and C = c1:
+
+              **filter="A eq 'a1' and B eq 'b1' and C eq 'c1'"**
+
+            - Return all time series where A = a1:
+
+              **filter="A eq 'a1' and B eq '*' and C eq '*'"**
+
+            - Special case: When dimension name or dimension value uses round brackets. Example: When dimension name
+              is **dim (test) 1**, instead of using **filter="dim (test) 1 eq '*'"** use
+              **filter="dim %2528test%2529 1 eq '*'"**.
+
+              When dimension name is **dim (test) 3** and dimension value is
+              **dim3 (test) val**, instead of using **filter="dim (test) 3 eq 'dim3 (test) val'"**, use **filter="dim
+              %2528test%2529 3 eq 'dim3 %2528test%2529 val'"**.
         :paramtype filter: Optional[str]
         :keyword metric_namespace: Metric namespace to query metric definitions for.
         :paramtype metric_namespace: Optional[str]
diff --git a/sdk/monitor/azure-monitor-query/azure/monitor/query/aio/_metrics_client_async.py b/sdk/monitor/azure-monitor-query/azure/monitor/query/aio/_metrics_client_async.py
@@ -85,23 +85,39 @@ async def query_resources(
         :keyword order_by: The aggregation to use for sorting results and the direction of the sort.
             Only one order can be specified. Examples: 'sum asc', 'maximum desc'.
         :paramtype order_by: Optional[str]
-        :keyword filter: The **$filter** is used to reduce the set of metric data returned. Example:
-            Metric contains metadata A, B and C. - Return all time series of C where A = a1 and B = b1 or
-            b2 **$filter=A eq 'a1' and B eq 'b1' or B eq 'b2' and C eq '*'** - Invalid variant: **$filter=A
-            eq 'a1' and B eq 'b1' and C eq '*' or B = 'b2'** This is invalid because the logical or
-            operator cannot separate two different metadata names. - Return all time series where A = a1,
-            B = b1 and C = c1: **$filter=A eq 'a1' and B eq 'b1' and C eq 'c1'** - Return all time series
-            where A = a1 **$filter=A eq 'a1' and B eq '*' and C eq '*'**. Special case: When dimension
-            name or dimension value uses round brackets. Eg: When dimension name is **dim (test) 1**
-            Instead of using **$filter= "dim (test) 1 eq '*'"** use **$filter= "dim %2528test%2529 1 eq '*'"**.
-            When dimension name is **dim (test) 3** and dimension value is **dim3 (test) val**, instead of using
-            **$filter= "dim (test) 3 eq 'dim3 (test) val'"** use **$filter= "dim
-            %2528test%2529 3 eq 'dim3 %2528test%2529 val'"**. Default value is None.
+        :keyword filter: The **filter** is used to reduce the set of metric data returned. Default value is None.
+
+            Example: Metric contains metadata A, B and C.
+
+            - Return all time series of C where A = a1 and B = b1 or b2:
+
+              **filter="A eq 'a1' and B eq 'b1' or B eq 'b2' and C eq '*'"**
+
+            - Invalid variant:
+
+              **filter="A eq 'a1' and B eq 'b1' and C eq '*' or B = 'b2'"**. This is invalid because the
+              logical 'or' operator cannot separate two different metadata names.
+
+            - Return all time series where A = a1, B = b1 and C = c1:
+
+              **filter="A eq 'a1' and B eq 'b1' and C eq 'c1'"**
+
+            - Return all time series where A = a1:
+
+              **filter="A eq 'a1' and B eq '*' and C eq '*'"**
+
+            - Special case: When dimension name or dimension value uses round brackets. Example: When dimension name
+              is **dim (test) 1**, instead of using **filter="dim (test) 1 eq '*'"** use
+              **filter="dim %2528test%2529 1 eq '*'"**.
+
+              When dimension name is **dim (test) 3** and dimension value is
+              **dim3 (test) val**, instead of using **filter="dim (test) 3 eq 'dim3 (test) val'"**, use **filter="dim
+              %2528test%2529 3 eq 'dim3 %2528test%2529 val'"**.
         :paramtype filter: str
         :keyword roll_up_by: Dimension name(s) to rollup results by. For example if you only want to see
             metric values with a filter like 'City eq Seattle or City eq Tacoma' but don't want to see
             separate values for each city, you can specify 'City' to see the results for Seattle
-            and Tacoma rolled up into one timeseries. Default value is None.
+            and Tacoma rolled up into one timeseries.
         :paramtype roll_up_by: str
         :return: A list of MetricsQueryResult objects.
         :rtype: list[~azure.monitor.query.MetricsQueryResult]
diff --git a/sdk/monitor/azure-monitor-query/azure/monitor/query/aio/_metrics_query_client_async.py b/sdk/monitor/azure-monitor-query/azure/monitor/query/aio/_metrics_query_client_async.py
@@ -99,25 +99,41 @@ async def query_resource(
          Use `azure.monitor.query.MetricAggregationType` enum to get each aggregation type.
         :paramtype aggregations: Optional[list[str]]
         :keyword max_results: The maximum number of records to retrieve.
-         Valid only if $filter is specified.
+         Valid only if 'filter' is specified.
          Defaults to 10.
         :paramtype max_results: Optional[int]
         :keyword order_by: The aggregation to use for sorting results and the direction of the sort.
          Only one order can be specified.
          Examples: sum asc.
         :paramtype order_by: Optional[str]
-        :keyword filter: The **$filter** is used to reduce the set of metric data returned. Example:
-         Metric contains metadata A, B and C. - Return all time series of C where A = a1 and B = b1 or
-         b2 **$filter=A eq 'a1' and B eq 'b1' or B eq 'b2' and C eq '*'** - Invalid variant: **$filter=A
-         eq 'a1' and B eq 'b1' and C eq '*' or B = 'b2'** This is invalid because the logical or
-         operator cannot separate two different metadata names. - Return all time series where A = a1, B
-         = b1 and C = c1: **$filter=A eq 'a1' and B eq 'b1' and C eq 'c1'** - Return all time series
-         where A = a1 **$filter=A eq 'a1' and B eq '*' and C eq '*'**. Special case: When dimension
-         name or dimension value uses round brackets. Eg: When dimension name is **dim (test) 1**
-         Instead of using **$filter= "dim (test) 1 eq '*'"** use **$filter= "dim %2528test%2529 1 eq '*'"**.
-         When dimension name is **dim (test) 3** and dimension value is **dim3 (test) val**, instead of using
-         **$filter= "dim (test) 3 eq 'dim3 (test) val'"** use **$filter= "dim
-         %2528test%2529 3 eq 'dim3 %2528test%2529 val'"**. Default value is None.
+        :keyword filter: The **filter** is used to reduce the set of metric data returned. Default value is None.
+
+            Example: Metric contains metadata A, B and C.
+
+            - Return all time series of C where A = a1 and B = b1 or b2:
+
+              **filter="A eq 'a1' and B eq 'b1' or B eq 'b2' and C eq '*'"**
+
+            - Invalid variant:
+
+              **filter="A eq 'a1' and B eq 'b1' and C eq '*' or B = 'b2'"**. This is invalid because the
+              logical 'or' operator cannot separate two different metadata names.
+
+            - Return all time series where A = a1, B = b1 and C = c1:
+
+              **filter="A eq 'a1' and B eq 'b1' and C eq 'c1'"**
+
+            - Return all time series where A = a1:
+
+              **filter="A eq 'a1' and B eq '*' and C eq '*'"**
+
+            - Special case: When dimension name or dimension value uses round brackets. Example: When dimension name
+              is **dim (test) 1**, instead of using **filter="dim (test) 1 eq '*'"** use
+              **filter="dim %2528test%2529 1 eq '*'"**.
+
+              When dimension name is **dim (test) 3** and dimension value is
+              **dim3 (test) val**, instead of using **filter="dim (test) 3 eq 'dim3 (test) val'"**, use **filter="dim
+              %2528test%2529 3 eq 'dim3 %2528test%2529 val'"**.
         :paramtype filter: Optional[str]
         :keyword metric_namespace: Metric namespace to query metric definitions for.
         :paramtype metric_namespace: Optional[str]
