+++
title = "Работа с фреймами данных"
+++

# Работа с фреймами данных

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

Интерфейс [DataFrame]({{< relref "../../packages_api/data/dataframe.md" >}}) содержит "имя" и массив "полей", где каждое поле содержит имя, тип и значения для поля.

> **Примечание:** Если вы хотите перенести существующий плагин для использования формата фрейма данных, обратитесь к [Migrate to data frames]({{< relref "migration-guide.md#migrate-to-data-frames" >}}).

## Создать фрейм данных

Если вы создаете плагин источника данных, то, скорее всего, захотите преобразовать ответ из внешнего API в фрейм данных. Давайте посмотрим, как создать фрейм данных.

Давайте начнем с создания простого фрейма данных, представляющего временной ряд. Самый простой способ создать фрейм данных - использовать функцию [todataframe]({{< relref "../../packages_api/data/todataframe.md" >}}).

```ts
// Need to be of the same length.
const timeValues = [1599471973065, 1599471975729];
const numberValues = [12.3, 28.6];

// Create data frame from values.
const frame = toDataFrame({
    name: "http_requests_total",
    fields: [
        { name: "Time", type: FieldType.time, values: timeValues },
        { name: "Value", type: FieldType.number, values: numberValues }
    ]
});
```

> ** Примечание:** Фреймы данных, представляющие временные ряды, содержат, по крайней мере, поле "время" и поле "число`. По соглашению встроенные плагины используют `Time` и `Value` в качестве имен полей для фреймов данных, содержащих данные временных рядов.

Как вы можете видеть из примера, для создания фреймов данных, подобных этому, требуется, чтобы ваши данные уже хранились в виде столбчатых данных. Если у вас уже есть записи в виде массива объектов, то вы можете передать их в `toDataFrame`, который пытается угадать схему на основе типов и имен объектов в массиве. Если вы создаете сложные фреймы данных таким образом, то обязательно убедитесь, что вы получаете ожидаемую схему.
```ts
const series = [
    { Time: 1599471973065, Value: 12.3 },
    { Time: 1599471975729, Value: 28.6 }
];

const frame = toDataFrame(series);
frame.name = 'http_requests_total'
```

## Считывание значений из фрейма данных

Когда вы создаете плагин панели, фреймы данных, возвращаемые источником данных, доступны из реквизита "данные` в вашем компоненте панели.

```ts
const SimplePanel: React.FC<Props> = ({ data }) => {
  const frame = data.series[0];

  // ...
}
```

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

```ts
const timeField = frame.fields.find(field => field.type === FieldType.time);
const valueField = frame.fields.find(field => field.type === FieldType.number);
```

Для других типов визуализаций может потребоваться несколько измерений. Например, пузырьковая диаграмма, в которой используются три числовых поля: ось X, ось Y и по одному для радиуса каждого пузырька. В этом случае вместо жесткого кодирования имен полей мы рекомендуем разрешить пользователю выбирать поле для каждого измерения.

```ts
const x = frame.fields.find(field => field.name === xField);
const y = frame.fields.find(field => field.name === yField);
const size = frame.fields.find(field => field.name === sizeField);

for (let i = 0; i < frame.length; i++) {
  const row = [x?.values.get(i), y?.values.get(i), size?.values.get(i)];

  // ...
}
```

В качестве альтернативы вы можете использовать [Представление фрейма данных]({{< relref "../../packages_api/data/фрейм данных view.md " >}}), который дает вам массив объектов, содержащих свойство для каждого поля во фрейме.
```ts
const view = new DataFrameView(frame);

view.forEach(row => {
  console.log(row[options.xField], row[options.yField], row[options.sizeField]);
})
```

## Отображение значений из фрейма данных

[[Параметры поля]({{<< "../../panels/field-options/_index.md" >}}) позволяют пользователю управлять тем, как Harvest отображает данные во фрейме данных.

Чтобы применить параметры поля к значению, используйте метод "отобразить` в соответствующем поле. Результат содержит такую информацию, как цвет и суффикс, которые будут использоваться при отображении значения.

```ts
const valueField = frame.fields.find(field => field.type === FieldType.number);

return (
  <div>
    {valueField
      ? valueField.values.toArray().map(value => {
          const displayValue = valueField.display!(value);
          return (
            <p style={{ color: displayValue.color }}>
              {displayValue.text} {displayValue.suffix ? displayValue.suffix : ''}
            </p>
          );
        })
      : null}
  </div>
);
```

Чтобы применить параметры поля к имени поля, используйте [getfielddisplayname]({{<< "../../packages_api/data/getfielddisplayname.md" >}}).

```ts
const valueField = frame.fields.find(field => field.type === FieldType.number);
const valueFieldName = getFieldDisplayName(valueField, frame);
```

