Подключаемый модуль Python

Статья
01/10/2024

Подключаемый модуль Python запускает определяемую пользователем функцию (UDF) с помощью скрипта Python. Скрипт Python получает табличные данные в качестве входных данных и создает табличные выходные данные. Среда выполнения подключаемого модуля размещается в песочницах, работающих на узлах кластера.

Синтаксис

T|evaluate [hint.distribution= ()singleper_node | ] [hint.remote= (auto | local)] python(output_schema,скрипт [,script_parameters] [,external_artifacts][,spill_to_disk])

Дополнительные сведения о соглашениях о синтаксисе.

Параметры

Имя	Тип	Обязательно	Описание
output_schema	`string`	✔️	Литерал `type` , определяющий схему вывода табличных данных, возвращаемых кодом Python. Формат: `typeof(`ColumnName`:`ColumnType[, ...]`)`. Например, `typeof(col1:string, col2:long)`. Чтобы расширить входную схему, используйте следующий синтаксис: `typeof(*, col1:string, col2:long)`.
script	`string`	✔️	Допустимый скрипт Python для выполнения. Сведения о создании многостроковых строк см. в разделе Советы по использованию.
script_parameters	`dynamic`		Контейнер свойств с парами значений имен, которые передаются в скрипт Python в качестве зарезервированного `kargs` словаря. Дополнительные сведения см. в разделе Зарезервированные переменные Python.
hint.distribution	`string`		Указание для распределения выполнения подключаемого модуля между несколькими узлами кластера. Значение по умолчанию — `single`. `single` означает, что один экземпляр скрипта будет выполняться по всем данным запроса. `per_node` означает, что если запрос до распространения блока Python, экземпляр скрипта будет выполняться на каждом узле на основе содержащихся в нем данных.
hint.remote	`string`		Это указание относится только к межкластикционным запросам. Значение по умолчанию — `auto`. `auto` означает, что сервер автоматически решает, в каком кластере выполняется код Python. При установке значения принудительно `local` выполняется код Python в локальном кластере. Используйте его в случае, если подключаемый модуль Python отключен в удаленном кластере.
external_artifacts	`dynamic`		Набор свойств, в который входят пары имен и URL-адресов для артефактов, доступных из облачного хранилища. Дополнительные сведения см. в статье Использование внешних артефактов.
spill_to_disk	`bool`		Задает альтернативный метод сериализации входной таблицы в песочницу Python. Для сериализации больших таблиц установите значение , `true` чтобы ускорить сериализацию и значительно сократить потребление памяти в песочнице. По умолчанию — `true`.

Зарезервированные переменные Python

Следующие переменные зарезервированы для взаимодействия между язык запросов Kusto и кодом Python.

df: входные табличные данные (значения T выше) в виде кадра pandas данных.
kargs: значение аргумента script_parameters в виде словаря Python.
resultpandas: кадр данных, созданный скриптом Python, значение которого становится табличными данными, которые отправляются оператору запроса Kusto, который следует за подключаемым модулем.

Включение подключаемого модуля

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

Изображение песочницы Python

Сведения об изменении версии образа Python см. в статье Изменение образа расширений языка Python в кластере.

Список пакетов для различных образов Python см. в справочнике по пакетам Python.

Примечание

По умолчанию подключаемый модуль импортирует numpy как np , а pandas — как pd. При необходимости можно импортировать другие модули.
Некоторые пакеты могут быть несовместимы с ограничениями, применяемыми песочницей, в которой выполняется подключаемый модуль.

Использование приема из запроса и политики обновления

Используйте подключаемый модуль в запросах, которые:
- Определяется как часть политики обновления, исходная таблица которой подается с помощью приема без потоковой передачи .
- Выполните как часть команды, которая используется для приема из запроса, например .set-or-append.
Вы не можете использовать подключаемый модуль в запросе, который определен как часть политики обновления, исходная таблица которого подается с помощью приема потоковой передачи.

Примеры

range x from 1 to 360 step 1
| evaluate python(
//
typeof(*, fx:double),               //  Output schema: append a new fx column to original table 
```
result = df
n = df.shape[0]
g = kargs["gain"]
f = kargs["cycles"]
result["fx"] = g * np.sin(df["x"]/n*2*np.pi*f)
```
, bag_pack('gain', 100, 'cycles', 4)    //  dictionary of parameters
)
| render linechart

Снимок экрана: демонстрация синуса с результатом запроса.

print "This is an example for using 'external_artifacts'"
| evaluate python(
    typeof(File:string, Size:string), ```if 1:
    import os
    result = pd.DataFrame(columns=['File','Size'])
    sizes = []
    path = '.\\\\Temp'
    files = os.listdir(path)
    result['File']=files
    for file in files:
        sizes.append(os.path.getsize(path + '\\\\' + file))
    result['Size'] = sizes
    ```,
    external_artifacts = 
        dynamic({"this_is_my_first_file":"https://kustoscriptsamples.blob.core.windows.net/samples/R/sample_script.r",
                 "this_is_a_script":"https://kustoscriptsamples.blob.core.windows.net/samples/python/sample_script.py"})
)

File	Размер
this_is_a_script	120
this_is_my_first_file	105

Советы по улучшению производительности

Уменьшите входной набор данных подключаемого модуля до минимально необходимого количества (столбцов или строк).
- По возможности используйте фильтры для исходного набора данных с помощью языка запросов Kusto.
- Чтобы выполнить вычисление для подмножества исходных столбцов, проецирование только этих столбцов перед вызовом подключаемого модуля.
Используйте hint.distribution = per_node каждый раз, когда логика в скрипте распространяется.
- Для секционирования входного набора данных можно также использовать оператор секционирования .
По возможности используйте язык запросов Kusto для реализации логики скрипта Python.

Советы по использованию

Чтобы создать многострочный код, содержащий скрипт Python, в редакторе запросов скопируйте скрипт Python из предпочитаемого редактора Python (Jupyter, Visual Studio Code, PyCharm и т. д.), вставьте его в редактор запросов, а затем заключите полный скрипт между строками, содержащими три последовательных обратных символа. Пример:

```
python code
```
Используйте оператор ,externaldata чтобы получить содержимое скрипта, хранящегося во внешнем расположении, например в хранилище BLOB-объектов Azure.

Пример

    let script = 
        externaldata(script:string)
        [h'https://kustoscriptsamples.blob.core.windows.net/samples/python/sample_script.py']
        with(format = raw);
    range x from 1 to 360 step 1
    | evaluate python(
        typeof(*, fx:double),
        toscalar(script), 
        bag_pack('gain', 100, 'cycles', 4))
    | render linechart

Использование внешних артефактов

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

URL-адреса, на которые ссылается свойство external artifacts, должны быть следующими:

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

Примечание

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

Артефакты становятся доступными для использования скриптом из локального временного каталога .\Temp. Имена, указанные в контейнере свойств, используются в качестве имен локальных файлов. См. примеры.

Сведения о ссылках на внешние пакеты см. в разделе Установка пакетов для подключаемого модуля Python.

Обновление кэша внешних артефактов

Файлы внешних артефактов, используемые в запросах, кэшируются в кластере. Если вы обновляете файлы в облачном хранилище и требуете немедленной синхронизации с кластером, можно использовать команду .clear cluster cache external-artifacts. Эта команда очищает кэшированные файлы и гарантирует, что последующие запросы выполняются с последней версией артефактов.

Установка пакетов для подключаемого модуля Python

Может потребоваться установить пакеты самостоятельно по следующим причинам:

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

Установите пакеты следующим образом:

Предварительные требования

Создайте контейнер больших двоичных объектов для размещения пакетов, желательно в том же месте, что и кластер. Например, предполагается, https://artifactswestus.blob.core.windows.net/pythonчто кластер находится в западной части США.
Измените политику выноски кластера, чтобы разрешить доступ к такому расположению.
- Для этого изменения требуются разрешения AllDatabasesAdmin .
- Например, чтобы разрешить доступ к большому двоичному объекту, расположенному в https://artifactswestus.blob.core.windows.net/python, выполните следующую команду:
```
.alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/python/","CanCall": true } ]'
```

Установка пакетов

Для общедоступных пакетов в PyPi или других каналах скачайте пакет и его зависимости.
- В окне cmd в локальной среде Windows Python выполните следующую команду:
```
pip wheel [-w download-dir] package-name.
```
Создайте ZIP-файл, содержащий необходимый пакет и его зависимости.
- Для частных пакетов запакуйте папку пакета и папки его зависимостей.
- Для общедоступных пакетов запакуйте файлы, скачанные на предыдущем шаге.
Примечание
- Скачайте пакет, совместимый с подсистемой Python и платформой среды выполнения песочницы (в настоящее время — 3.6.5 в Windows).
- Обязательно запакуйте .whl сами файлы, а не их родительскую папку.
- Вы можете пропустить .whl файлы для пакетов, которые уже существуют с той же версией в базовом образе песочницы.
Отправьте ZIP-файл в большой двоичный объект в расположении артефактов (из шага 1).
Вызовите подключаемый python модуль.
- external_artifacts Укажите параметр с именем контейнера свойств и ссылкой на ZIP-файл (URL-адрес BLOB-объекта, включая маркер SAS).
- Во встроенном коде Python импортируйте Zipackage из sandbox_utils и вызовите его install() метод с именем ZIP-файла.

Пример

Установите пакет Faker , который создает поддельные данные.

range ID from 1 to 3 step 1 
| extend Name=''
| evaluate python(typeof(*), ```if 1:
    from sandbox_utils import Zipackage
    Zipackage.install("Faker.zip")
    from faker import Faker
    fake = Faker()
    result = df
    for i in range(df.shape[0]):
        result.loc[i, "Name"] = fake.name()
    ```,
    external_artifacts=bag_pack('faker.zip', 'https://artifacts.blob.core.windows.net/kusto/Faker.zip?*** REPLACE WITH YOUR SAS TOKEN ***'))

ID	Имя
1	Гэри Тапиа
2	Эмма Эванс
3	Эшли Боуэн

Дополнительные примеры функций UDF, использующих подключаемый модуль Python, см. в библиотеке функций.

Синтаксис

T|evaluate [hint.distribution= ()per_nodesingle | ] [hint.remote= (auto | local)] python(скрипт output_schema,[,script_parameters] [,spill_to_disk])

Дополнительные сведения о соглашениях о синтаксисе.

Параметры

Имя	Тип	Обязательно	Описание
output_schema	`string`	✔️	Литерал `type` , определяющий схему вывода табличных данных, возвращаемых кодом Python. Формат: `typeof(`ColumnName`:`ColumnType[, ...]`)`. Например, `typeof(col1:string, col2:long)`. Чтобы расширить входную схему, используйте следующий синтаксис: `typeof(*, col1:string, col2:long)`.
script	`string`	✔️	Допустимый скрипт Python для выполнения. Сведения о создании многостроковых строк см. в разделе Советы по использованию.
script_parameters	`dynamic`		Контейнер свойств с парами значений имен, которые передаются в скрипт Python в качестве зарезервированного `kargs` словаря. Дополнительные сведения см. в разделе Зарезервированные переменные Python.
hint.distribution	`string`		Указание для распределения выполнения подключаемого модуля между несколькими узлами кластера. Значение по умолчанию — `single`. `single` означает, что один экземпляр скрипта будет выполняться по всем данным запроса. `per_node` означает, что если запрос до распространения блока Python, экземпляр скрипта будет выполняться на каждом узле на основе содержащихся в нем данных.
hint.remote	`string`		Это указание относится только к межкластикционным запросам. Значение по умолчанию — `auto`. `auto` означает, что сервер автоматически решает, в каком кластере выполняется код Python. При установке значения принудительно `local` выполняется код Python в локальном кластере. Используйте его в случае, если подключаемый модуль Python отключен в удаленном кластере.
spill_to_disk	`bool`		Задает альтернативный метод сериализации входной таблицы в песочницу Python. Для сериализации больших таблиц установите значение , `true` чтобы ускорить сериализацию и значительно сократить потребление памяти в песочнице. По умолчанию — `true`.

Зарезервированные переменные Python

Следующие переменные зарезервированы для взаимодействия между язык запросов Kusto и кодом Python.

df: входные табличные данные (значения T выше) в виде кадра pandas данных.
kargs: значение аргумента script_parameters в виде словаря Python.
resultpandas: кадр данных, созданный скриптом Python, значение которого становится табличными данными, которые отправляются оператору запроса Kusto, который следует за подключаемым модулем.

Включение подключаемого модуля

Подключаемый модуль отключен по умолчанию. Прежде чем начать, включите подключаемый модуль Python в базе данных KQL.

Изображение песочницы Python

Список пакетов для различных образов Python см. в справочнике по пакетам Python.

Примечание

По умолчанию подключаемый модуль импортирует numpy как np , а pandas — как pd. При необходимости можно импортировать другие модули.
Некоторые пакеты могут быть несовместимы с ограничениями, применяемыми песочницей, в которой выполняется подключаемый модуль.

Использование приема из запроса и политики обновления

Используйте подключаемый модуль в запросах, которые:
- Определяется как часть политики обновления, исходная таблица которой подается с помощью приема без потоковой передачи .
- Выполните как часть команды, которая используется для приема из запроса, например .set-or-append.
Вы не можете использовать подключаемый модуль в запросе, который определен как часть политики обновления, исходная таблица которого подается с помощью приема потоковой передачи.

Примеры

range x from 1 to 360 step 1
| evaluate python(
//
typeof(*, fx:double),               //  Output schema: append a new fx column to original table 
```
result = df
n = df.shape[0]
g = kargs["gain"]
f = kargs["cycles"]
result["fx"] = g * np.sin(df["x"]/n*2*np.pi*f)
```
, bag_pack('gain', 100, 'cycles', 4)    //  dictionary of parameters
)
| render linechart

Снимок экрана: демонстрация синуса с результатом запроса.

Советы по улучшению производительности

Уменьшите входной набор данных подключаемого модуля до минимально необходимого количества (столбцов или строк).
- По возможности используйте фильтры для исходного набора данных с помощью языка запросов Kusto.
- Чтобы выполнить вычисление для подмножества исходных столбцов, проецирование только этих столбцов перед вызовом подключаемого модуля.
Используйте hint.distribution = per_node каждый раз, когда логика в скрипте распространяется.
- Для секционирования входного набора данных можно также использовать оператор секционирования .
По возможности используйте язык запросов Kusto для реализации логики скрипта Python.

Советы по использованию

Чтобы создать многострочный код, содержащий скрипт Python, в редакторе запросов скопируйте скрипт Python из предпочитаемого редактора Python (Jupyter, Visual Studio Code, PyCharm и т. д.), вставьте его в редактор запросов, а затем заключите полный скрипт между строками, содержащими три последовательных обратных символа. Пример:

```
python code
```
Используйте оператор ,externaldata чтобы получить содержимое скрипта, хранящегося во внешнем расположении, например в хранилище BLOB-объектов Azure.

Пример

    let script = 
        externaldata(script:string)
        [h'https://kustoscriptsamples.blob.core.windows.net/samples/python/sample_script.py']
        with(format = raw);
    range x from 1 to 360 step 1
    | evaluate python(
        typeof(*, fx:double),
        toscalar(script), 
        bag_pack('gain', 100, 'cycles', 4))
    | render linechart

Дополнительные примеры функций UDF, использующих подключаемый модуль Python, см. в библиотеке функций.

Эта возможность не поддерживается.

Подключаемый модуль Python

Синтаксис

Параметры

Зарезервированные переменные Python

Включение подключаемого модуля

Изображение песочницы Python

Использование приема из запроса и политики обновления

Примеры

Советы по улучшению производительности

Советы по использованию

Пример

Использование внешних артефактов

Обновление кэша внешних артефактов

Установка пакетов для подключаемого модуля Python

Предварительные требования

Установка пакетов

Пример

Синтаксис

Параметры

Зарезервированные переменные Python

Включение подключаемого модуля

Изображение песочницы Python

Использование приема из запроса и политики обновления

Примеры

Советы по улучшению производительности

Советы по использованию

Пример

Обратная связь

Обратная связь

Дополнительные ресурсы

Подключаемый модуль Python

Синтаксис

Параметры

Зарезервированные переменные Python

Включение подключаемого модуля

Изображение песочницы Python

Использование приема из запроса и политики обновления

Примеры

Советы по улучшению производительности

Советы по использованию

Пример

Использование внешних артефактов

Обновление кэша внешних артефактов

Установка пакетов для подключаемого модуля Python

Предварительные требования

Установка пакетов

Пример

См. также

Синтаксис

Параметры

Зарезервированные переменные Python

Включение подключаемого модуля

Изображение песочницы Python

Использование приема из запроса и политики обновления

Примеры

Советы по улучшению производительности

Советы по использованию

Пример

См. также

Обратная связь

Обратная связь

Дополнительные ресурсы