+++
title = "MySQL"
description = "Руководство по использованию MySQL в Harvest"
keywords = ["harvest", "mysql", "guide"]
aliases = ["/docs/harvest/latest/features/datasources/mysql/"]
weight = 1000
+++
# Использование MySQL в Графане

> Начиная с Harvest v5.1 вы можете назвать столбец времени *time* в дополнение к ранее поддерживаемому *time_sec*. Использование *time_sec* в конечном итоге будет объявлено устаревшим.

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

## Добавление источника данных

1. Откройте боковое меню, щелкнув значок Harvest в верхнем заголовке.
1. В боковом меню под ссылкой «Информационные панели» вы должны найти ссылку «Источники данных».
1. Нажмите кнопку «+ Добавить источник данных» в верхнем заголовке.
1. Выберите *MySQL* в раскрывающемся списке *Тип*.
### Параметры источника данных

Имя          | Описание
-------------- | -------------
`Name`         | Имя источника данных. Именно так вы обращаетесь к источнику данных в панелях и запросах.
`Default`      | Источник данных по умолчанию означает, что он будет предварительно выбран для новых панелей.
`Host`         | IP-адрес/имя хоста и необязательный порт вашего экземпляра MySQL.
`Database`     | Имя вашей базы данных MySQL.
`User`           Логин/имя пользователя базы данных
`Password`       Пароль пользователя базы данных 
`Max open`     |Максимальное количество открытых подключений к базе данных, по умолчанию «неограничено» (Harvest v5.4+).
`Max idle`     | Максимальное количество подключений в пуле незанятых подключений, по умолчанию 2 (Harvest v5.4+).
`Max lifetime` | Максимальное количество времени в секундах, в течение которого соединение может быть повторно использовано, по умолчанию `14400`/4 часа. Это значение всегда должно быть меньше настроенного [wait_timeout](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_wait_timeout) в MySQL (Harvest v5.4+).

### Минимальный временной интервал

Нижний предел для [$__interval]({{< relref "../variables/variable-types/_index.md#the-interval-variable" >}}) и [$__interval_ms]({{< relref ". ./variables/variable-types/_index.md#the-interval-ms-variable" >}}) переменных.
Рекомендуется установить частоту записи, например `1m`, если ваши данные записываются каждую минуту.
Этот параметр также можно переопределить/настроить на панели инструментов в разделе параметров источника данных. Важно отметить, что это значение **должно** быть отформатировано как
число, за которым следует действительный идентификатор времени, например. `1m` (1 минута) или `30s` (30 секунд). Поддерживаются следующие идентификаторы времени:
|Идентификатор | Описание |
| ---------- | ----------- |
| `y`        | год|
| `M`        | месяц      |
| `w`          неделя        |
| `d`        | день        |
| `h`        | час       |
| `m`        | минута     |
| `s`        | секунда     |
| `ms`       | миллисекунда|

### Разрешения пользователя базы данных (важно!)

Пользователю базы данных, которого вы укажете при добавлении источника данных, должны быть предоставлены разрешения SELECT только на
указанную базу данных и таблицы, которые вы хотите запросить. Harvest не проверяет безопасность запроса. Запрос
может включать любой оператор SQL. Например, такие операторы, как `USE otherdb;` и `DROP TABLE user;`, будут
казнен. Чтобы защититься от этого, мы **настоятельно** рекомендуем вам создать конкретного пользователя mysql с ограниченными разрешениями.

Пример:

```sql
 CREATE USER 'harvestReader' IDENTIFIED BY 'password';
 GRANT SELECT ON mydatabase.mytable TO 'harvestReader';
```

Вы можете использовать подстановочные знаки (`*`) вместо базы данных или таблицы, если хотите предоставить доступ к большему количеству баз данных и таблиц.

## Редактор запросов

> Доступно только в Harvest v5.4+.

{{< рисунок src="/static/img/docs/v54/mysql_query_still.png" class="docs-image--no-shadow" анимированный-gif="/static/img/docs/v54/mysql_query.gif" >}}

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

В редакторе запросов есть ссылка «Сгенерированный SQL», которая появляется после выполнения запроса в режиме редактирования панели. Нажмите на нее, и она развернется и покажет необработанную интерполированную строку SQL, которая была выполнена.

### Выберите таблицу, столбец времени и столбец показателей (ОТ)

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

В поле FROM Harvest предложит таблицы, находящиеся в настроенной базе данных. Чтобы выбрать таблицу или представление в другой базе данных, к которой у пользователя базы данных есть доступ, вы можете вручную ввести полное имя (database.table), например `otherDb.metrics`.

Поле столбца «Время» относится к имени столбца, содержащего ваши значения времени. Выбор значения для поля столбца «Метрика» не является обязательным. Если выбрано значение, поле столбца «Метрика» будет использоваться в качестве имени ряда.

Предлагаемые столбцы метрик будут содержать только столбцы с текстовым типом данных (текст, крошечный текст, средний текст, длинный текст, varchar, char).
Если вы хотите использовать столбец с другим типом данных в качестве столбца метрики, вы можете ввести имя столбца с приведением: `CAST(numericColumn as CHAR)`.
Вы также можете ввести произвольные SQL-выражения в поле столбца метрики, которые оцениваются как текстовый тип данных, например
`CONCAT(column1, " ", CAST(numericColumn as CHAR))`.

### Столбцы и функции агрегирования (SELECT)

В строке `SELECT` вы можете указать, какие столбцы и функции вы хотите использовать.
В поле столбца вы можете писать произвольные выражения вместо имени столбца, например `столбец1 * столбец2 / столбец3`.

Если вы используете агрегатные функции, вам необходимо сгруппировать набор результатов. Редактор автоматически добавит `GROUP BY time`, если вы добавите агрегатную функцию.

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

### Данные фильтра (ГДЕ)
Чтобы добавить фильтр, щелкните значок плюса справа от условия «ГДЕ». Вы можете удалить фильтры, нажав на
фильтр и выбрав «Удалить». К новым запросам автоматически добавляется фильтр для текущего выбранного временного диапазона.

### Группа по
Чтобы сгруппировать по времени или любым другим столбцам, щелкните значок плюса в конце строки СГРУППИРОВАТЬ ПО. В раскрывающемся списке предложений будут отображаться только текстовые столбцы выбранной таблицы, но вы можете ввести любой столбец вручную.
Вы можете удалить группу, щелкнув элемент и выбрав «Удалить».

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

#### Заполнение промежутка

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

### Режим текстового редактора (RAW)
Вы можете переключиться в режим редактора необработанных запросов, щелкнув значок гамбургера и выбрав «Переключить режим редактора» или нажав «Редактировать SQL» под запросом.

> Если вы используете редактор необработанных запросов, убедитесь, что ваш запрос как минимум имеет `ORDER BY time` и фильтр для возвращаемого временного диапазона.

## Макросы

Чтобы упростить синтаксис и разрешить динамические части, такие как фильтры диапазона дат, запрос может содержать макросы.
Пример макроса                                       | Описание
------------------------------------------------------ | -------------
`$__time(dateColumn)`                                  | Будет заменено выражением для преобразования в метку времени UNIX и переименования столбца в `time_sec`. Например, *UNIX_TIMESTAMP(dateColumn) как time_sec*
`$__timeEpoch(dateColumn)`                             | Будет заменено выражением для преобразования в метку времени UNIX и переименования столбца в `time_sec`. Например, *UNIX_TIMESTAMP(dateColumn) как time_sec*
`$__timeFilter(dateColumn)`                            |Будет заменен фильтром временного диапазона, использующим указанное имя столбца. Например, *dateColumn МЕЖДУ FROM_UNIXTIME(1494410783) И FROM_UNIXTIME(1494410983)*
`$__timeFrom()`                                        | Будет заменено началом текущего активного выбора времени. Например, *FROM_UNIXTIME(1494410783)*
`$__timeTo()`                                          |Будет заменено к концу текущего активного выбора времени. Например, *FROM_UNIXTIME(1494410983)*
`$__timeGroup(dateColumn,'5m')`                        | Будет заменено выражением, которое можно использовать в предложении GROUP BY. Например, *cast(cast(UNIX_TIMESTAMP(dateColumn)/(300) со знаком)*300 со знаком),*
`$__timeGroup(dateColumn,'5m', 0)`                     | То же, что и выше, но с параметром заполнения, поэтому недостающие точки в этой серии будут добавлены графаной, а 0 будет использоваться в качестве значения.
`$__timeGroup(dateColumn,'5m', NULL)`                  | То же, что и выше, но NULL будет использоваться как значение для отсутствующих точек.
`$__timeGroup(dateColumn,'5m', previous)`              | То же, что и выше, но предыдущее значение в этой серии будет использоваться в качестве значения заполнения, если значение не было видно, но будет использоваться NULL (доступно только в Harvest 5.3+).
`$__timeGroupAlias(dateColumn,'5m')`                   | Будет заменено идентично $__timeGroup, но с добавленным псевдонимом столбца (доступно только в Harvest 5.3+).
`$__unixEpochFilter(dateColumn)`                       | Будет заменен фильтром временного диапазона с использованием указанного имени столбца со временем, представленным в виде временной метки Unix. Например, *dateColumn > 1494410783 AND dateColumn < 1494497183*
`$__unixEpochFrom()`                                   | Будет заменено началом текущего активного выбора времени в виде временной метки Unix. Например, *1494410783*
`$__unixEpochTo()`                                     | Будет заменено окончанием текущего активного выбора времени в виде временной метки Unix. Например, *1494497183*
`$__unixEpochNanoFilter(dateColumn)`                   | Будет заменен фильтром временного диапазона с использованием указанного имени столбца со временем, представленным в виде отметки времени в наносекундах. Например, *dateColumn > 1494410783152415214 AND dateColumn < 1494497183142514872*
`$__unixEpochNanoFrom()`                               | Будет заменено началом текущего активного выбора времени в виде отметки времени в наносекундах. Например, *1494410783152415214*
`$__unixEpochNanoTo()`                                 |Будет заменено концом текущего активного выбора времени в виде отметки времени в наносекундах. Например, *1494497183142514872*
`$__unixEpochGroup(dateColumn,'5m', [fillmode])`       |То же, что и $__timeGroup, но для времени, хранящегося как метка времени Unix (доступно только в Harvest 5.3+).
`$__unixEpochGroupAlias(dateColumn,'5m', [fillmode])`  | То же, что и выше, но также добавляет псевдоним столбца (доступно только в Harvest 5.3+).

Мы планируем добавить еще много макросов. Если у вас есть предложения по макросам, которые вы хотели бы видеть, [откройте вопрос] (https://github.com/harvest/harvest) в нашем репозитории GitHub.

В редакторе запросов есть ссылка «Сгенерированный SQL», которая появляется после выполнения запроса в режиме редактирования панели. Нажмите на нее, и она развернется и покажет необработанную интерполированную строку SQL, которая была выполнена.

## Табличные запросы

Если для параметра запроса «Форматировать как» установлено значение «Таблица», вы можете выполнять любой тип SQL-запроса. Панель таблицы автоматически покажет результаты любых столбцов и строк, возвращаемых вашим запросом.

Редактор запросов с примером запроса:

{{< рисунок src="/static/img/docs/v45/mysql_table_query.png" >}}

Запрос:

```sql
SELECT
  title as 'Title',
  user.login as 'Created By' ,
  dashboard.created as 'Created On'
 FROM dashboard
INNER JOIN user on user.id = dashboard.created_by
WHERE $__timeFilter(dashboard.created)
```

Вы можете управлять именами столбцов панели «Таблица», используя обычный синтаксис выбора столбца `as ` SQL.

Результирующая табличная панель:

![](/static/img/docs/v43/mysql_table.png)

## Запросы временных рядов

Если вы установите «Форматировать как» на «Временной ряд», например, для использования на панели «График», тогда запрос должен вернуть столбец с именем «время», который возвращает либо дату и время SQL, либо любой числовой тип данных, представляющий эпоху Unix.
Любой столбец, кроме «время» и «метрика», рассматривается как столбец значений.
Вы можете вернуть столбец с именем `metric`, который используется в качестве имени метрики для столбца значений.
Если вы возвращаете несколько столбцов значений и столбец с именем «метрика», то этот столбец используется в качестве префикса для имени серии (доступно только в Harvest 5.3+).

Наборы результатов запросов временных рядов должны быть отсортированы по времени.

**Пример со столбцом `метрика`:**
```sql
SELECT
  $__timeGroup(time_date_time,'5m'),
  min(value_double),
  'min' as metric
FROM test_data
WHERE $__timeFilter(time_date_time)
GROUP BY time
ORDER BY time
```

**Пример использования параметра fill в макросе $__timeGroup для преобразования пустых значений в ноль:**

```sql
SELECT
  $__timeGroup(createdAt,'5m',0),
  sum(value_double) as value,
  measurement
FROM test_data
WHERE
  $__timeFilter(createdAt)
GROUP BY time, measurement
ORDER BY time
```

**Пример с несколькими столбцами:**

```sql
SELECT
  $__timeGroup(time_date_time,'5m'),
  min(value_double) as min_value,
  max(value_double) as max_value
FROM test_data
WHERE $__timeFilter(time_date_time)
GROUP BY time
ORDER BY time
```
В настоящее время не поддерживается динамическая группировка по времени на основе временного диапазона и ширины панели.
Это то, что мы планируем добавить.

## Шаблоны

Эта функция в настоящее время доступна в ночных сборках и будет включена в выпуск 5.0.0.

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

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

### Переменная запроса

Если вы добавите переменную шаблона типа `Query`, вы можете написать запрос MySQL, который может
возвращать такие вещи, как имена измерений, имена ключей или значения ключей, которые отображаются в виде раскрывающегося списка.

Например, у вас может быть переменная, содержащая все значения для столбца `hostname` в таблице, если вы укажете подобный запрос в настройке переменной шаблона *Query*.

```sql
SELECT hostname FROM my_host
```

Запрос может возвращать несколько столбцов, и Harvest автоматически создаст из них список. Например, приведенный ниже запрос вернет список со значениями из `hostname` и `hostname2`.

```sql
SELECT my_host.hostname, my_other_host.hostname2 FROM my_host JOIN my_other_host ON my_host.city = my_other_host.city
```

Чтобы использовать макросы, зависящие от диапазона времени, такие как `$__timeFilter(column)`, в вашем запросе режим обновления переменной шаблона должен быть установлен на*On Time Range Change*.

```sql
SELECT event_name FROM event_log WHERE $__timeFilter(time_column)
```

Другой вариант — это запрос, который может создать переменную ключ/значение. Запрос должен вернуть два столбца с именами __text и __value. Значение столбца `__text` должно быть уникальным (если оно не уникально, то используется первое значение). Параметры в раскрывающемся списке будут иметь текст и значение, которые позволяют вам использовать понятное имя в виде текста и идентификатор в качестве значения. Пример запроса с `hostname` в качестве текста и `id` в качестве значения:
```sql
SELECT hostname AS __text, id AS __value FROM my_host
```
Вы также можете создавать вложенные переменные. Например, если у вас есть другая переменная с именем `region`. Тогда вы могли бы
переменная hosts показывает только хосты из текущего выбранного региона с таким запросом (если `region` является переменной с несколькими значениями, используйте оператор сравнения `IN`, а не `=` для сопоставления с несколькими значениями):

```sql
SELECT hostname FROM my_host  WHERE region IN($region)
```
#### Использование `__searchFilter` для фильтрации результатов в переменной запроса
> Доступно начиная с Harvest 6.5 и выше

Использование `__searchFilter` в поле запроса отфильтрует результат запроса на основе того, что пользователь вводит в раскрывающемся списке.
Когда пользователь ничего не ввел, значением по умолчанию для __searchFilter является %.

> Важно, чтобы выражение `__searchFilter` было заключено в кавычки, поскольку Harvest не сделает этого за вас.

В приведенном ниже примере показано, как использовать `__searchFilter` как часть поля запроса, чтобы включить поиск `hostname`, когда пользователь вводит в раскрывающемся списке.

Запрос
```sql
SELECT hostname FROM my_host  WHERE hostname LIKE '$__searchFilter'
```
### Использование переменных в запросах

Начиная с Harvest 4.3.0 и заканчивая 4.6.0, переменные шаблона всегда автоматически заключаются в кавычки, поэтому, если это строковое значение, не заключайте их в кавычки в предложениях where.

Начиная с Harvest 4.7.0, значения переменных шаблона заключаются в кавычки только в том случае, если переменная шаблона является «многозначной».

Если переменная является переменной с несколькими значениями, используйте оператор сравнения `IN`, а не `=` для сопоставления с несколькими значениями.

Есть два синтаксиса:

`$<varname>`  Пример с переменной шаблона с именем: `hostname`:

```sql
SELECT
  UNIX_TIMESTAMP(atimestamp) as time,
  aint as value,
  avarchar as metric
FROM my_table
WHERE $__timeFilter(atimestamp) and hostname in($hostname)
ORDER BY atimestamp ASC
```

`[[varname]]`  Пример с переменной шаблона с именем`hostname`:

```sql
SELECT
  UNIX_TIMESTAMP(atimestamp) as time,
  aint as value,
  avarchar as metric
FROM my_table
WHERE $__timeFilter(atimestamp) and hostname in([[hostname]])
ORDER BY atimestamp ASC
```
#### Отключение кавычек для многозначных переменных

Harvest автоматически создает строку в кавычках, разделенную запятыми, для многозначных переменных. Например: если выбраны `server01` и `server02`, они будут отформатированы как: `'server01', 'server02'`. Отключите цитирование, используйте параметр форматирования csv для переменных:

`${серверы:csv}`

Подробнее об опциях форматирования переменных читайте в документации [Переменные]({{< relref "../variables/_index.md#advanced-formatting-options" >}}).

## Аннотации

[Аннотации]({{< relref "../dashboards/annotations.md" >}}) позволяют накладывать расширенную информацию о событиях поверх графиков. Вы добавляете запросы аннотаций через меню Dashboard/представление Annotations.

**Пример запроса с использованием столбца времени со значениями эпохи:**

```sql
SELECT
  epoch_time as time,
  metric1 as text,
  CONCAT(tag1, ',', tag2) as tags
FROM
  public.test_data
WHERE
  $__unixEpochFilter(epoch_time)
```

**Пример запроса региона с использованием столбцов time и timeend со значениями эпохи:**

> Доступно только в Harvest v6.6+.

```sql
SELECT
  epoch_time as time,
  epoch_timeend as timeend,
  metric1 as text,
  CONCAT(tag1, ',', tag2) as tags
FROM
  public.test_data
WHERE
  $__unixEpochFilter(epoch_time)
```

**Пример запроса с использованием столбца времени собственного типа данных даты/времени SQL:**

```sql
SELECT
  native_date_time as time,
  metric1 as text,
  CONCAT(tag1, ',', tag2) as tags
FROM
  public.test_data
WHERE
  $__timeFilter(native_date_time)
```

Имя         | Описание
----------- | -------------
`time`      | Имя поля даты/времени. Может быть столбцом с собственным типом данных даты/времени SQL или значением эпохи.
`timeend`   | Необязательное имя поля даты/времени окончания. Может быть столбцом с собственным типом данных даты/времени SQL или значением эпохи. (Harvest v6.6+)
`text`      | Поле описания события.
`tags`      | Необязательное имя поля для использования в тегах событий в виде строки, разделенной запятыми.

## Оповещение

Запросы временных рядов должны работать в условиях оповещения. Запросы в формате таблицы пока не поддерживаются в условиях правил предупреждений.

## Настройте источник данных с предоставлением

Теперь можно настраивать источники данных с помощью конфигурационных файлов в системе обеспечения Harvest. Вы можете узнать больше о том, как это работает, и обо всех настройках, которые вы можете установить для источников данных, на [странице документации по подготовке]({{< relref "../administration/provisioning/#datasources" >}})

Вот несколько примеров подготовки для этого источника данных.
```yaml
apiВерсия: 1

источник данных:
  - name: MySQL
    type: mysql
    url: localhost:3306
    database: harvest
    user: harvest
    password: password
    jsonData:
      maxOpenConns: 0         # Harvest v5.4+
      maxIdleConns: 2         # Harvest v5.4+
      connMaxLifetime: 14400  # Harvest v5.4+
```
