Imrprove LogsQuery Request (Azure#20132)

* Imrprove docstrings

* more docs changes

* Apply suggestions from code review

Co-authored-by: swathipil <76007337+swathipil@users.noreply.github.com>

Co-authored-by: swathipil <76007337+swathipil@users.noreply.github.com>

Author: Rakshith Bhyravabhotla

sdk/monitor/azure-monitor-query/README.md

@@ -212,6 +212,44 @@ for rsp in response:
             print(df)
 ```
 
+#### Handling the response for Logs Query
+
+The `query` API returns the `LogsQueryResult` while the `batch_query` API returns the `LogsBatchQueryResult`.
+
+Here is a heirarchy of the response:
+
+```
+LogsQueryResult / LogsBatchQueryResult
+|---id (this exists in `LogsBatchQueryResult` object only)
+|---status (this exists in `LogsBatchQueryResult` object only)
+|---statistics
+|---render
+|---error
+|---tables (list of `LogsQueryResultTable` objects)
+    |---name
+    |---rows
+    |---columns (list of `LogsQueryResultColumn` objects)
+        |---name
+        |---type
+```
+
+So, to handle a response with tables and display it using pandas,
+
+```python
+table = response.tables[0]
+df = pd.DataFrame(table.rows, columns=[col.name for col in table.columns])
+```
+A full sample can be found [here](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-query/samples/sample_log_query_client.py).
+
+In a very similar fashion, to handle a batch response, 
+
+```python
+for result in response:
+    table = result.tables[0]
+    df = pd.DataFrame(table.rows, columns=[col.name for col in table.columns])
+```
+A full sample can be found [here](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-query/samples/sample_batch_query.py).
+
 ### Query metrics
 
 The following example gets metrics for an Event Grid subscription. The resource URI is that of an event grid topic.

sdk/monitor/azure-monitor-query/azure/monitor/query/_logs_query_client.py

@@ -22,11 +22,6 @@
 class LogsQueryClient(object):
     """LogsQueryClient
 
-    :param credential: The credential to authenticate the client
-    :type credential: ~azure.core.credentials.TokenCredential
-    :keyword endpoint: The endpoint to connect to. Defaults to 'https://api.loganalytics.io'.
-    :paramtype endpoint: str
-
     .. admonition:: Example:
 
     .. literalinclude:: ../samples/sample_log_query_client.py
@@ -35,6 +30,11 @@ class LogsQueryClient(object):
         :language: python
         :dedent: 0
         :caption: Creating the LogsQueryClient with a TokenCredential.
+
+    :param credential: The credential to authenticate the client.
+    :type credential: ~azure.core.credentials.TokenCredential
+    :keyword endpoint: The endpoint to connect to. Defaults to 'https://api.loganalytics.io'.
+    :paramtype endpoint: str
     """
 
     def __init__(self, credential, **kwargs):
@@ -139,7 +139,7 @@ def batch_query(self, queries, **kwargs):
 
         :param queries: The list of queries that should be processed
         :type queries: list[dict] or list[~azure.monitor.query.LogsBatchQueryRequest]
-        :return: BatchResponse, or the result of cls(response)
+        :return: List of LogsBatchQueryResult, or the result of cls(response)
         :rtype: ~list[~azure.monitor.query.LogsBatchQueryResult]
         :raises: ~azure.core.exceptions.HttpResponseError
 
@@ -156,6 +156,7 @@ def batch_query(self, queries, **kwargs):
             queries = [LogsBatchQueryRequest(**q) for q in queries]
         except (KeyError, TypeError):
             pass
+        queries = [q._to_generated() for q in queries] # pylint: disable=protected-access
         try:
             request_order = [req.id for req in queries]
         except AttributeError:

sdk/monitor/azure-monitor-query/azure/monitor/query/_metrics_query_client.py

@@ -25,11 +25,6 @@
 class MetricsQueryClient(object):
     """MetricsQueryClient
 
-    :param credential: The credential to authenticate the client
-    :type credential: ~azure.core.credentials.TokenCredential
-    :keyword endpoint: The endpoint to connect to. Defaults to 'https://management.azure.com'.
-    :paramtype endpoint: str
-
     .. admonition:: Example:
 
     .. literalinclude:: ../samples/sample_metrics_query_client.py
@@ -38,6 +33,11 @@ class MetricsQueryClient(object):
         :language: python
         :dedent: 0
         :caption: Creating the MetricsQueryClient with a TokenCredential.
+
+    :param credential: The credential to authenticate the client.
+    :type credential: ~azure.core.credentials.TokenCredential
+    :keyword endpoint: The endpoint to connect to. Defaults to 'https://management.azure.com'.
+    :paramtype endpoint: str
     """
 
     def __init__(self, credential, **kwargs):

sdk/monitor/azure-monitor-query/azure/monitor/query/_models.py

@@ -25,8 +25,8 @@ class LogsQueryResultTable(object):
     :type name: str
     :param columns: Required. The list of columns in this table.
     :type columns: list[~azure.monitor.query.LogsQueryResultColumn]
-    :keyword rows: Required. The resulting rows from this query.
-    :paramtype rows: list[list[str]]
+    :param rows: Required. The resulting rows from this query.
+    :type rows: list[list[str]]
     """
     def __init__(self, name, columns, rows):
         # type: (str, List[LogsQueryResultColumn], List[List[str]]) -> None
@@ -46,10 +46,10 @@ def _from_generated(cls, generated):
 class LogsQueryResultColumn(InternalColumn):
     """A column in a table.
 
-    :keyword name: The name of this column.
-    :paramtype name: str
-    :keyword type: The data type of this column.
-    :paramtype type: str
+    :ivar name: The name of this column.
+    :vartype name: str
+    :ivar type: The data type of this column.
+    :vartype type: str
     """
 
     _attribute_map = {
@@ -109,22 +109,22 @@ class MetricsResult(object):
 
     All required parameters must be populated in order to send to Azure.
 
-    :keyword cost: The integer value representing the cost of the query, for data case.
-    :paramtype cost: int
-    :keyword timespan: Required. The timespan for which the data was retrieved. Its value consists of
+    :ivar cost: The integer value representing the cost of the query, for data case.
+    :vartype cost: int
+    :ivar timespan: Required. The timespan for which the data was retrieved. Its value consists of
      two datetimes concatenated, separated by '/'. This may be adjusted in the future and returned
      back from what was originally requested.
-    :paramtype timespan: str
-    :keyword interval: The interval (window size) for which the metric data was returned in. This
+    :vartype timespan: str
+    :ivar interval: The interval (window size) for which the metric data was returned in. This
      may be adjusted in the future and returned back from what was originally requested. This is
      not present if a metadata request was made.
-    :paramtype interval: ~datetime.timedelta
-    :keyword namespace: The namespace of the metrics been queried.
-    :paramtype namespace: str
-    :keyword resourceregion: The region of the resource been queried for metrics.
-    :paramtype resourceregion: str
-    :keyword metrics: Required. the value of the collection.
-    :paramtype metrics: list[~monitor_query_client.models.Metric]
+    :vartype interval: ~datetime.timedelta
+    :ivar namespace: The namespace of the metrics that has been queried.
+    :vartype namespace: str
+    :ivar resourceregion: The region of the resource that has been queried for metrics.
+    :vartype resourceregion: str
+    :ivar metrics: Required. The value of the collection.
+    :vartype metrics: list[~monitor_query_client.models.Metric]
     """
     def __init__(self, **kwargs):
         # type: (Any) -> None
@@ -148,7 +148,7 @@ def _from_generated(cls, generated):
             metrics=[Metric._from_generated(m) for m in generated.value] # pylint: disable=protected-access
         )
 
-class LogsBatchQueryRequest(InternalLogQueryRequest):
+class LogsBatchQueryRequest(object):
     """A single request in a batch.
 
     Variables are only populated by the server, and will be ignored when sending a request.
@@ -212,6 +212,14 @@ def __init__(self, query, workspace_id, duration=None, **kwargs): #pylint: disab
         self.headers = headers
         self.workspace = workspace_id
 
+    def _to_generated(self):
+        return InternalLogQueryRequest(
+            id=self.id,
+            body=self.body,
+            headers=self.headers,
+            workspace=self.workspace
+        )
+
 class LogsBatchQueryResult(object):
     """The LogsBatchQueryResult.
 
@@ -265,12 +273,12 @@ def _from_generated(cls, generated):
 class LogsBatchResultError(object):
     """Error response for a batch request.
 
-    :param message: The error message describing the cause of the error.
-    :type message: str
+    :ivar message: The error message describing the cause of the error.
+    :vartype message: str
     :param code: The error code.
-    :type code: str
+    :vartype code: str
     :param details: The details of the error.
-    :type inner_error: list[~azure.monitor.query.ErrorDetails]
+    :vartype inner_error: list[~azure.monitor.query.ErrorDetails]
     """
     def __init__(self, **kwargs):
         # type: (Any) -> None
@@ -299,7 +307,7 @@ class MetricNamespace(object):
     :keyword name: The name of the namespace.
     :paramtype name: str
     :keyword metric_namespace_name: The fully qualified namespace name.
-    :paramtype properties: str
+    :paramtype metric_namespace_name: str
     """
     def __init__(
         self,
@@ -399,19 +407,19 @@ class MetricValue(object):
 
     All required parameters must be populated in order to send to Azure.
 
-    :keyword time_stamp: Required. the timestamp for the metric value in ISO 8601 format.
-    :paramtype time_stamp: ~datetime.datetime
-    :keyword average: the average value in the time range.
-    :paramtype average: float
-    :keyword minimum: the least value in the time range.
-    :paramtype minimum: float
-    :keyword maximum: the greatest value in the time range.
-    :paramtype maximum: float
-    :keyword total: the sum of all of the values in the time range.
-    :paramtype total: float
-    :keyword count: the number of samples in the time range. Can be used to determine the number of
+    :ivar time_stamp: Required. The timestamp for the metric value in ISO 8601 format.
+    :vartype time_stamp: ~datetime.datetime
+    :ivar average: The average value in the time range.
+    :vartype average: float
+    :ivar minimum: The least value in the time range.
+    :vartype minimum: float
+    :ivar maximum: The greatest value in the time range.
+    :vartype maximum: float
+    :ivar total: The sum of all of the values in the time range.
+    :vartype total: float
+    :ivar count: The number of samples in the time range. Can be used to determine the number of
      values that contributed to the average value.
-    :paramtype count: float
+    :vartype count: float
     """
     def __init__(
         self,
@@ -443,18 +451,18 @@ class Metric(object):
 
     All required parameters must be populated in order to send to Azure.
 
-    :keyword id: Required. the metric Id.
-    :paramtype id: str
-    :keyword type: Required. the resource type of the metric resource.
-    :paramtype type: str
-    :keyword name: Required. the name of the metric.
-    :paramtype name: str
-    :keyword unit: Required. the unit of the metric. Possible values include: "Count", "Bytes",
+    :ivar id: Required. The metric Id.
+    :vartype id: str
+    :ivar type: Required. The resource type of the metric resource.
+    :vartype type: str
+    :ivar name: Required. The name of the metric.
+    :vartype name: str
+    :ivar unit: Required. The unit of the metric. Possible values include: "Count", "Bytes",
      "Seconds", "CountPerSecond", "BytesPerSecond", "Percent", "MilliSeconds", "ByteSeconds",
      "Unspecified", "Cores", "MilliCores", "NanoCores", "BitsPerSecond".
-    :paramtype unit: str
-    :keyword timeseries: Required. the time series returned when a data query is performed.
-    :paramtype timeseries: list[~monitor_query_client.models.TimeSeriesElement]
+    :vartype unit: str
+    :ivar timeseries: Required. The time series returned when a data query is performed.
+    :vartype timeseries: list[~monitor_query_client.models.TimeSeriesElement]
     """
     def __init__(
         self,
@@ -485,11 +493,11 @@ def _from_generated(cls, generated):
 class TimeSeriesElement(object):
     """A time series result type. The discriminator value is always TimeSeries in this case.
 
-    :keyword metadata_values: the metadata values returned if $filter was specified in the call.
-    :paramtype metadata_values: list[~monitor_query_client.models.MetadataValue]
-    :keyword data: An array of data points representing the metric values. This is only returned if
+    :ivar metadata_values: The metadata values returned if $filter was specified in the call.
+    :vartype metadata_values: list[~monitor_query_client.models.MetadataValue]
+    :ivar data: An array of data points representing the metric values. This is only returned if
      a result type of data is specified.
-    :paramtype data: list[~monitor_query_client.models.MetricValue]
+    :vartype data: list[~monitor_query_client.models.MetricValue]
     """
 
     _attribute_map = {
@@ -521,10 +529,10 @@ def _from_generated(cls, generated):
 class MetricsMetadataValue(object):
     """Represents a metric metadata value.
 
-    :keyword name: the name of the metadata.
-    :paramtype name: str
-    :keyword value: the value of the metadata.
-    :paramtype value: str
+    :ivar name: The name of the metadata.
+    :vartype name: str
+    :ivar value: The value of the metadata.
+    :vartype value: str
     """
     def __init__(
         self,
@@ -574,7 +582,7 @@ def _from_generated(cls, generated):
 
 
 class AggregationType(str, Enum):
-    """the aggregation type of the metric.
+    """The aggregation type of the metric.
     """
 
     NONE = "None"

sdk/monitor/azure-monitor-query/azure/monitor/query/aio/_logs_query_client_async.py

@@ -134,6 +134,7 @@ async def batch_query(
             queries = [LogsBatchQueryRequest(**q) for q in queries]
         except (KeyError, TypeError):
             pass
+        queries = [q._to_generated() for q in queries] # pylint: disable=protected-access
         try:
             request_order = [req.id for req in queries]
         except AttributeError: