feat(api): dataset fields statistics (#1360)

Solves apify/apify-core#18807 - proposal for
new API endpoint `/v2/datasets/{datasetId}/field-statistics` which
should return [dataset field
statistics](https://docs.apify.com/platform/actors/development/actor-definition/dataset-schema/validation#dataset-field-statistics)

Author: mfori

apify-api/openapi/components/schemas/datasets/DatasetFieldStatistics.yaml

@@ -0,0 +1,19 @@
+title: DatasetFieldStatistics
+type: object
+properties:
+  min:
+    type: number
+    description: 'Minimum value of the field. For numbers, this is calculated directly. For strings, this is the length of the shortest string. For arrays, this is the length of the shortest array. For objects, this is the number of keys in the smallest object.'
+    nullable: true
+  max:
+    type: number
+    description: 'Maximum value of the field. For numbers, this is calculated directly. For strings, this is the length of the longest string. For arrays, this is the length of the longest array. For objects, this is the number of keys in the largest object.'
+    nullable: true
+  nullCount:
+    type: number
+    description: 'How many items in the dataset have a null value for this field.'
+    nullable: true
+  emptyCount:
+    type: number
+    description: 'How many items in the dataset are `undefined`, meaning that for example empty string is not considered empty.'
+    nullable: true

apify-api/openapi/components/schemas/datasets/GetDatasetStatisticsResponse.yaml

@@ -0,0 +1,16 @@
+title: GetDatasetStatisticsResponse
+required:
+  - data
+type: object
+properties:
+  data:
+    type: object
+    properties:
+      fieldStatistics:
+        type: object
+        nullable: true
+        additionalProperties:
+          $ref: ./DatasetFieldStatistics.yaml
+        description: 'When you configure the dataset [fields schema](https://docs.apify.com/platform/actors/development/actor-definition/dataset-schema/validation), we measure the statistics such as `min`, `max`, `nullCount` and `emptyCount` for each field.
+        This property provides statistics for each field from dataset fields schema.
+        <br/></br>See dataset field statistics [documentation](https://docs.apify.com/platform/actors/development/actor-definition/dataset-schema/validation#dataset-field-statistics) for more information.'

apify-api/openapi/components/tags.yaml

@@ -762,6 +762,10 @@
   x-legacy-doc-urls:
   - '#/reference/datasets/item-collection'
   x-trait: 'true'
+- name: Datasets/Statistics
+  x-displayName: Statistics
+  x-parent-tag-name: Datasets
+  x-trait: 'true'
 - name: Request queues
   x-displayName: Request queues
   x-legacy-doc-urls:

apify-api/openapi/components/x-tag-groups.yaml

@@ -63,6 +63,7 @@
   - Datasets/Dataset collection
   - Datasets/Dataset
   - Datasets/Item collection
+  - Datasets/Statistics
 - name: Request queues
   tags:
   - Request queues

apify-api/openapi/openapi.yaml

@@ -568,6 +568,8 @@ paths:
     $ref: 'paths/datasets/datasets@{datasetId}.yaml'
   '/v2/datasets/{datasetId}/items':
     $ref: 'paths/datasets/datasets@{datasetId}@items.yaml'
+  '/v2/datasets/{datasetId}/statistics':
+    $ref: 'paths/datasets/datasets@{datasetId}@statistics.yaml'
   /v2/request-queues:
     $ref: paths/request-queues/request-queues.yaml
   '/v2/request-queues/{queueId}':

apify-api/openapi/paths/datasets/datasets@{datasetId}@statistics.yaml

@@ -0,0 +1,40 @@
+get:
+  tags:
+    - Datasets/Statistics
+  summary: Get dataset statistics
+  description: |
+    Returns statistics for given dataset.
+    Currently provides only [field statistics](https://docs.apify.com/platform/actors/development/actor-definition/dataset-schema/validation#dataset-field-statistics).
+
+  operationId: dataset_statistics_get
+  parameters:
+    - name: datasetId
+      in: path
+      description: Dataset ID or `username~dataset-name`.
+      required: true
+      style: simple
+      schema:
+        type: string
+        example: WkzbQMuFYuamGv3YF
+  responses:
+    '200':
+      description: ''
+      content:
+        application/json:
+          schema:
+            $ref: "../../components/schemas/datasets/GetDatasetStatisticsResponse.yaml"
+          example:
+            data:
+              fieldStatistics:
+                name:
+                  nullCount: 122
+                price:
+                  min: 59
+                  max: 89
+# TODO: add clients methods
+#  x-js-parent: DatasetClient
+#  x-js-name: statistics
+#  x-js-doc-url: https://docs.apify.com/api/client/js/reference/class/DatasetClient#statistics
+#  x-py-parent: DatasetClientAsync
+#  x-py-name: statistics
+#  x-py-doc-url: https://docs.apify.com/api/client/python/reference/class/DatasetClientAsync#statistics