sqlrutils (пакет R в Службах машинного обучения SQL Server)

  • Статья

Применимо к: SQL Server 2016 (13.x) и более поздних версий

sqlrutils — это пакет R от корпорации Майкрософт, который предоставляет пользователям R механизм для помещения скриптов R в хранимую процедуру T-SQL, регистрации этой хранимой процедуры в базе данных и ее запуска из среды разработки R. Этот пакет входит в состав Служб машинного обучения SQL Server и служб SQL Server 2016 R Services.

Преобразование кода R для выполнения в рамках одной хранимой процедуры позволяет более эффективно использовать службы SQL Server R Services, которые требуют внедрить скрипт R в качестве параметра в sp_execute_external_script. Пакет sqlrutils помогает создать такой внедренный скрипт R и правильно настроить соответствующие параметры.

Пакет sqlrutils выполняет следующие задачи.

  • Сохраняет созданный скрипт T-SQL в виде строки внутри структуры данных R.
  • При необходимости создает SQL-файл для скрипта T-SQL, который можно изменить или выполнить, чтобы создать хранимую процедуру.
  • Регистрирует созданную хранимую процедуру в экземпляре SQL Server из среды разработки R.

Вы также можете выполнить хранимую процедуру из среды R, передав параметры с правильным форматом и обработав результаты. Или вы можете использовать хранимую процедуру из SQL Server для поддержки стандартных сценариев интеграции базы данных, таких как извлечение, преобразование и загрузка, обучение модели и оценка большого объема.

Примечание

Если планируется выполнить хранимую процедуру из среды R путем вызова функции executeStoredProcedure , следует использовать поставщик ODBC 3.8, например драйвер ODBC 13 для SQL Server.

Полная справочная документация

Пакет sqlrutils распространяется в нескольких продуктах Майкрософт, но его использование не зависит от того, получили ли вы его в SQL Server или в другом продукте. Если для конкретных продуктов функции будут действовать иначе, выявленные расхождения будут приведены на странице справки по функциям.

Список функций

Ниже представлен обзор функций, которые можно вызывать из пакета sqlrutils в целях разработки хранимой процедуры, содержащей встроенный код R. Сведения о параметрах для каждого метода или каждой функции см. в справке R для этого пакета: help(package="sqlrutils")

Функция Описание
executeStoredProcedure Выполнение хранимой процедуры SQL.
getInputParameters Получение списка входных параметров в хранимой процедуре.
InputData Определяет источник данных в SQL Server, который будет использоваться в кадре данных R. Укажите имя data.frame для хранения входных данных и запрос для получения данных или значение по умолчанию. Поддерживаются только простые запросы SELECT.
InputParameter Определяет отдельный входной параметр, который будет внедрен в скрипт T-SQL. Необходимо указать имя параметра и его тип данных R.
OutputData Cоздает объект промежуточных данных, который требуется, когда функция R возвращает список, содержащий data.frame. Объект OutputData используется для хранения имени отдельного data.frame, полученного из списка.
OutputParameter Cоздает объект промежуточных данных, который требуется, когда функция R возвращает список. Объект OutputParameter хранит имя и тип данных для одного элемента списка при условии, что он не является кадром данных.
registerStoredProcedure Регистрация хранимой процедуры в базе данных.
setInputDataQuery Назначение запроса параметру входных данных хранимой процедуры.
setInputParameterValue Назначение значения входному параметру хранимой процедуры.
StoredProcedure Объект хранимой процедуры.

Как использовать sqlrutils

Функции пакета sqlrutils должны выполняться на компьютере со службами машинного обучения SQL Server с R. Если вы работаете на клиентской рабочей станции, задайте для удаленного контекста вычислений сдвиг выполнения на SQL Server. Рабочий процесс для использования этого пакета включает следующие шаги:

  • Определение параметров хранимой процедуры (входные и выходные данные или и то, и другое)
  • Создание и регистрация хранимой процедуры
  • Выполнение хранимой процедуры

В сеансе R загрузите sqlrutils из командной строки, введя library(sqlrutils).

Примечание

Этот пакет можно загрузить на компьютер, на котором нет SQL Server (например, в экземпляр клиента R), если изменить контекст вычислений на SQL Server и выполнить код в этом контексте вычислений.

Определение параметров и входных данных хранимой процедуры

StoredProcedure является основным конструктором, используемым для создания хранимой процедуры. Этот конструктор создает объект хранимой процедуры SQL Server и при необходимости создает текстовый файл, содержащий запрос, который можно использовать для создания хранимой процедуры с помощью команды T-SQL.

При необходимости функция StoredProcedure может зарегистрировать хранимую процедуру с помощью указанного экземпляра и базы данных.

  • Используйте аргумент func для указания допустимой функции R. Все переменные, которые использует функция, должны быть определены внутри функции либо представления в виде входных параметров. Эти параметры могут включать не более одного кадра данных.

  • Функция R должна возвращать кадр данных, именованный список или значение NULL. Если функция возвращает список, он может содержать не более одного data.frame.

  • Используйте аргумент spName для указания имени создаваемой хранимой процедуры.

  • Можно передать необязательные входные и выходные параметры с помощью объектов, созданных следующими вспомогательными функциями: setInputData, setInputParameterи setOutputParameter.

  • При необходимости используйте filePath для указания пути и имени создаваемого SQL-файла. Этот файл можно запустить на экземпляре SQL Server для создания хранимой процедуры с помощью T-SQL.

  • Для определения сервера и базы данных, где будет сохранена хранимая процедура, используйте аргументы dbName и connectionString.

  • Чтобы получить список объектов InputData и InputParameter , которые использовались для создания определенного объекта StoredProcedure , вызовите getInputParameters.

  • Чтобы зарегистрировать хранимую процедуру в указанной базе данных, используйте registerStoredProcedure.

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

Указание входных данных и выполнение

  • Используйте setInputDataQuery для назначения запроса объекту InputParameter . Например, если вы создали объект хранимой процедуры в R, можно использовать setInputDataQuery для передачи аргументов в StoredProcedure для выполнения хранимой процедуры с нужными входными данными.

  • Используйте setInputValue для назначения конкретного значения параметру, сохраненному в виде объекта InputParameter . Затем передайте объект параметра и его назначение значения в StoredProcedure , чтобы выполнить хранимую процедуру с заданными значениями.

  • Используйте executeStoredProcedure для выполнения хранимой процедуры, определенной в виде объекта StoredProcedure . Вызывайте эту функцию только при выполнении хранимой процедуры из кода R. Не используйте ее при запуске хранимой процедуры из SQL Server с помощью T-SQL.

Примечание

Функции executeStoredProcedure требуется поставщик ODBC 3.8, например драйвер ODBC 13 для SQL Server.

См. также раздел

Создание хранимой процедуры с помощью sqlrutils