+++
title = "Фреймы данных"
+++

# Фреймы данных

Harvest поддерживает множество различных источников данных, каждый из которых имеет свою собственную модель данных. Чтобы сделать это возможным, Harvest объединяет результаты запроса из каждого из этих источников данных в одну единую структуру данных, называемую _data frame_.

Структура фрейма данных - это концепция, заимствованная из инструментов анализа данных, таких как [язык программирования R](https://www.r-project.org ), и [Панды](https://pandas.pydata.org /).

> Фреймы данных доступны в Harvest 7.0+ и заменили временные ряды и структуры таблиц более общей структурой данных, которая может поддерживать более широкий спектр типов данных.

В этом документе дается обзор структуры фрейма данных и того, как обрабатываются данные в Harvest.

## Фрейм данных

Фрейм данных представляет собой табличную структуру, ориентированную на столбцы, что означает, что в ней данные хранятся по столбцам, а не по строкам. Чтобы понять, что это значит, давайте посмотрим на определение TypeScript, используемое Harvest:
```ts
interface DataFrame {
    name?:  string;
    // reference to query that create the frame
    refId?: string;

    fields: []Field;
}
```

По сути, фрейм данных представляет собой набор _fields_, где каждое поле соответствует столбцу. Каждое поле, в свою очередь, состоит из набора значений вместе с метаинформацией, такой как тип данных этих значений.
```ts
interface Field {
    name:    string;
     // Prometheus like Labels / Tags
    labels?: Record<string, string>;

    // For example string, number, time (or more specific primitives in the backend)
    type:   FieldType;
    // Array of values all of the same type
    values: Vector<T>;

    // Optional display data for the field (e.g. unit, name over-ride, etc)
    config: FieldConfig;
}
```

Давайте рассмотрим пример. В таблице ниже показан фрейм данных с двумя полями _time_ и _temperature_.

| время | температура |
| ------------------- | ----------- |
| 2020-01-02 03:04:00 | 45.0        |
| 2020-01-02 03:05:00 | 47.0        |
| 2020-01-02 03:06:00 | 48.0        |

Каждое поле имеет три значения, и каждое значение в поле должно иметь один и тот же тип. В этом случае все значения в поле time являются временными метками, а все значения в поле temperature - числами.

Одним из ограничений для фреймов данных является то, что все поля во фрейме должны быть одинаковой длины, чтобы быть допустимым фреймом данных.

### Конфигурация поля

Каждое поле во фрейме данных содержит необязательную информацию о значениях в поле, такую как единицы измерения, масштабирование и так далее.

Добавляя конфигурации полей во фрейм данных, Harvest может автоматически настраивать визуализации. Например, вы можете настроить Harvest на автоматическую установку единицы измерения, предоставляемой источником данных.

## Преобразования

Наряду с информацией о типе, конфигурации полей позволяют _data transformations_ в Harvest.

Преобразование данных - это любая функция, которая принимает фрейм данных в качестве входных данных и возвращает другой фрейм данных в качестве выходных данных. Используя фреймы данных в вашем плагине, вы получаете целый ряд бесплатных преобразований.

## Фреймы данных как временные ряды

Фрейм данных, содержащий хотя бы одно поле времени, считается _time series_.

Для получения дополнительной информации о временных рядах обратитесь к нашему [Введение во временные ряды] ({{< relref "../../basics/timeseries.md" >}}).

### Широкий формат

Когда набор временных рядов имеет один и тот же _time index_ — поля времени в каждом временном ряду идентичны — они могут храниться вместе в _wide формате. Повторно используя поле времени, мы можем уменьшить объем данных, отправляемых в браузер.

В этом примере загрузка ЦП с каждого хоста имеет общий индекс времени, поэтому мы можем хранить их в одном и том же фрейме данных.

``текст
Название: Широкий
Размеры: 3 поля по 2 строки
+---------------------+-----------------+-----------------+
| Имя: время | Имя: процессор | Имя: процессор |
| Метки: | Метки: хост=a | Метки: хост=b |
| Тип: []время.Время | Тип: []float64 | Тип: []float64 |
+---------------------+-----------------+-----------------+
| 2020-01-02 03:04:00 | 3               | 4               |
| 2020-01-02 03:05:00 | 6               | 7               |
+---------------------+-----------------+-----------------+
```

Однако, если два временных ряда не имеют одинаковых значений времени, они представляются в виде двух разных фреймов данных.

``текст
Имя: процессор
Размеры: 2 поля по 2 строки
+---------------------+-----------------+
| Имя: время | Имя: процессор |
| Метки: | Метки: хост=a |
| Тип: []время.Время | Тип: []float64 |
+---------------------+-----------------+
| 2020-01-02 03:04:00 | 3               |
| 2020-01-02 03:05:00 | 6               |
+---------------------+-----------------+

Имя: процессор
Размеры: 2 поля по 2 строки
+---------------------+-----------------+
| Имя: время | Имя: процессор |
| Метки: | Метки: хост=b |
| Тип: []время.Время | Тип: []float64 |
+---------------------+-----------------+
| 2020-01-02 03:04:01 | 4               |
| 2020-01-02 03:05:01 | 7               |
+---------------------+-----------------+
```

Широкий формат обычно можно использовать, когда одним и тем же процессом собирается несколько временных рядов. В этом случае каждое измерение производится с одним и тем же интервалом и, следовательно, будет иметь одни и те же значения времени.

### Длинный формат

Некоторые источники данных возвращают данные в формате _long_ (также называемом _narrow_ format). Это обычный формат, возвращаемый, например, базами данных SQL.

В длинном формате строковые значения представлены в виде отдельных полей, а не в виде меток. В результате форма данных в длинной форме может иметь повторяющиеся значения времени.

Harvest может обнаруживать и преобразовывать фреймы данных в длинном формате в широкий формат.

> ** Примечание: ** Формат Long в настоящее время поддерживается только в серверной части: [Проблема Harvest #22219](https://github.com/harvest/harvest/issues/22219 ).

Например, следующий фрейм данных в длинном формате:

``текст
Имя: Длинный
Размеры: 4 поля по 4 строки
+---------------------+-----------------+-----------------+----------------+
| Имя: время | Имя: aMetric | Имя: bMetric | Имя: хост |
| Этикетки: | Этикетки: | Этикетки: | Этикетки: | Этикетки: /
| Тип: []время.Время | Тип: []float64 | Тип: []float64 | Тип: []строка |
+---------------------+-----------------+-----------------+----------------+
| 2020-01-02 03:04:00 | 2 | 10 | foo  |
| 2020-01-02 03:04:00 | 5 | 15 | bar |
| 2020-01-02 03:05:00 | 3 | 11 | foo  |
| 2020-01-02 03:05:00 | 6 | 16 | bar |
+---------------------+-----------------+-----------------+----------------+
```

может быть преобразован в фрейм данных в широком формате:

``текст
Название: Широкий
Размеры: 5 полей по 2 строки
+---------------------+------------------+------------------+------------------+------------------+
| Имя: время | Имя: aMetric | Имя: bMetric | Имя: aMetric | Имя: bMetric |
| Метки: | Метки: host=foo | Метки: host=foo | Метки: host=bar | Метки: host=bar |
| Тип: []время.Время | Тип: []float64 | Тип: []float64 | Тип: []float64 | Тип: []float64 |
+---------------------+------------------+------------------+------------------+------------------+
| 2020-01-02 03:04:00 | 2                | 10               | 5                | 15               |
| 2020-01-02 03:05:00 | 3                | 11               | 6                | 16               |
+---------------------+------------------+------------------+------------------+------------------+
```

## Технические рекомендации

Этот раздел содержит ссылки на техническую справку и реализации фреймов данных.

### Стрела Апача

Структура фрейма данных вдохновлена и использует [проект Apache Arrow](https://arrow.apache.org /). Фреймы данных Javascript используют таблицы со стрелками в качестве базовой структуры, а внутренний код Go сериализует свои фреймы в таблицах со стрелками для передачи.

### Javascript

Реализация фреймов данных на Javascript находится в папке [`/src/dataframe`](https://github.com/harvest/harvest/tree/master/packages/harvest-data/src/dataframe) и [`/src/types/dataframe.ts`](https://github.com/harvest/harvest/blob/master/packages/harvest-data/src/types/dataFrame.ts ) пакета [`@harvest/data`](https://github.com/harvest/harvest/tree/master/packages/harvest-data ).

### Уходи

Для получения документации по реализации фреймов данных Go обратитесь к [github.com/harvest/harvest-plugin-sdk-go/data посылка](https://pkg.go.dev/github.com/harvest/harvest-plugin-sdk-go/data?tab=doc ).