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

Применимо к:Applies to: даSQL Server 2016 (13.x);SQL Server 2016 (13.x)yesSQL Server 2016 (13.x);SQL Server 2016 (13.x) и более поздние версииПрименимо к:Applies to: даSQL Server 2016 (13.x);SQL Server 2016 (13.x)yesSQL Server 2016 (13.x);SQL Server 2016 (13.x) and later

sqlrutils — это пакет R от корпорации Майкрософт, который предоставляет пользователям R механизм для помещения скриптов R в хранимую процедуру T-SQL, регистрации этой хранимой процедуры в базе данных и ее запуска из среды разработки R.sqlrutils is an R package from Microsoft that provides a mechanism for R users to put their R scripts into a T-SQL stored procedure, register that stored procedure with a database, and run the stored procedure from an R development environment. Этот пакет входит в состав Служб машинного обучения SQL Server и служб SQL Server 2016 R Services.The package is included in SQL Server Machine Learning Services and SQL Server 2016 R Services.

Преобразование кода R для выполнения в рамках одной хранимой процедуры позволяет более эффективно использовать службы SQL Server R Services, которые требуют внедрить скрипт R в качестве параметра в sp_execute_external_script.By converting your R code to run within a single stored procedure, you can make more effective use of SQL Server R Services, which requires that R script be embedded as a parameter to sp_execute_external_script. Пакет sqlrutils помогает создать такой внедренный скрипт R и правильно настроить соответствующие параметры.The sqlrutils package helps you build this embedded R script and set related parameters appropriately.

Пакет sqlrutils выполняет следующие задачи.The sqlrutils package performs these tasks:

  • Сохраняет созданный скрипт T-SQL в виде строки внутри структуры данных R.Saves the generated T-SQL script as a string inside an R data structure
  • При необходимости создает SQL-файл для скрипта T-SQL, который можно изменить или выполнить, чтобы создать хранимую процедуру.Optionally, generate a .sql file for the T-SQL script, which you can edit or run to create a stored procedure
  • Регистрирует созданную хранимую процедуру в экземпляре SQL Server из среды разработки R.Registers the newly created stored procedure with the SQL Server instance from your R development environment

Вы также можете выполнить хранимую процедуру из среды R, передав параметры с правильным форматом и обработав результаты.You can also execute the stored procedure from an R environment, by passing well-formed parameters and processing the results. Или вы можете использовать хранимую процедуру из SQL Server для поддержки стандартных сценариев интеграции базы данных, таких как извлечение, преобразование и загрузка, обучение модели и оценка большого объема.Or, you can use the stored procedure from SQL Server to support common database integration scenarios such as ETL, model training, and high-volume scoring.

Примечание

Если планируется выполнить хранимую процедуру из среды R путем вызова функции executeStoredProcedure , следует использовать поставщик ODBC 3.8, например драйвер ODBC 13 для SQL Server.If you intend to run the stored procedure from an R environment by calling the executeStoredProcedure function, you must use an ODBC 3.8 provider, such as ODBC Driver 13 for SQL Server.

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

Пакет sqlrutils распространяется в нескольких продуктах Майкрософт, но его использование не зависит от того, получили ли вы его в SQL Server или в другом продукте.The sqlrutils package is distributed in multiple Microsoft products, but usage is the same whether you get the package in SQL Server or another product. Благодаря сходству функций документация по отдельным функциям sqlrutils опубликована только в одном разделе в справочнике по R для Microsoft Machine Learning Server.Because the functions are the same, documentation for individual sqlrutils functions is published to just one location under the R reference for Microsoft Machine Learning Server. Если для конкретных продуктов функции будут действовать иначе, выявленные расхождения будут приведены на странице справки по функциям.Should any product-specific behaviors exist, discrepancies will be noted in the function help page.

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

Ниже представлен обзор функций, которые можно вызывать из пакета sqlrutils в целях разработки хранимой процедуры, содержащей встроенный код R.The following section provides an overview of the functions that you can call from the sqlrutils package to develop a stored procedure containing embedded R code. Сведения о параметрах для каждого метода или каждой функции см. в справке R для этого пакета: help(package="sqlrutils")For details of the parameters for each method or function, see the R help for the package: help(package="sqlrutils")

ФункцияFunction ОписаниеDescription
executeStoredProcedureexecuteStoredProcedure Выполнение хранимой процедуры SQL.Execute a SQL stored procedure.
getInputParametersgetInputParameters Получение списка входных параметров в хранимой процедуре.Get a list of input parameters to the stored procedure.
InputDataInputData Определяет источник данных в SQL Server, который будет использоваться в кадре данных R.Defines the source of data in SQL Server that will be used in the R data frame. Укажите имя data.frame для хранения входных данных и запрос для получения данных или значение по умолчанию.You specify the name of the data.frame in which to store the input data, and a query to get the data, or a default value. Поддерживаются только простые запросы SELECT.Only simple SELECT queries are supported.
InputParameterInputParameter Определяет отдельный входной параметр, который будет внедрен в скрипт T-SQL.Defines a single input parameter that will be embedded in the T-SQL script. Необходимо указать имя параметра и его тип данных R.You must provide the name of the parameter and its R data type.
OutputDataOutputData Cоздает объект промежуточных данных, который требуется, когда функция R возвращает список, содержащий data.frame.Generates an intermediate data object that is needed if your R function returns a list that contains a data.frame. Объект OutputData используется для хранения имени отдельного data.frame, полученного из списка.The OutputData object is used to store the name of a single data.frame obtained from the list.
OutputParameterOutputParameter Cоздает объект промежуточных данных, который требуется, когда функция R возвращает список.Generates an intermediate data object that is needed if your R function returns a list. Объект OutputParameter хранит имя и тип данных для одного элемента списка при условии, что он не является кадром данных.The OutputParameter object stores the name and data type of a single member of the list, assuming that member is not a data frame.
registerStoredProcedureregisterStoredProcedure Регистрация хранимой процедуры в базе данных.Register the stored procedure with a database.
setInputDataQuerysetInputDataQuery Назначение запроса параметру входных данных хранимой процедуры.Assign a query to an input data parameter of the stored procedure.
setInputParameterValuesetInputParameterValue Назначение значения входному параметру хранимой процедуры.Assign a value to an input parameter of the stored procedure.
StoredProcedureStoredProcedure Объект хранимой процедуры.A stored procedure object.

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

Функции пакета sqlrutils должны выполняться на компьютере со службами машинного обучения SQL Server с R. Если вы работаете на клиентской рабочей станции, задайте для удаленного контекста вычислений сдвиг выполнения на SQL Server.The sqlrutils package functions must run on a computer having SQL Server Machine Learning with R. If you are working on a client workstation, set a remote compute context to shift execution to SQL Server. Рабочий процесс для использования этого пакета включает следующие шаги:The workflow for using this package includes the following steps:

  • Определение параметров хранимой процедуры (входные и выходные данные или и то, и другое)Define stored procedure parameters (inputs, outputs, or both)
  • Создание и регистрация хранимой процедурыGenerate and register the stored procedure
  • Выполнение хранимой процедурыExecute the stored procedure

В сеансе R загрузите sqlrutils из командной строки, введя library(sqlrutils).In an R session, load sqlrutils from the command line by typing library(sqlrutils).

Примечание

Этот пакет можно загрузить на компьютер, на котором нет SQL Server (например, в экземпляр клиента R), если изменить контекст вычислений на SQL Server и выполнить код в этом контексте вычислений.You can load this package on computer that does not have SQL Server (for example, on an R Client instance) if you change the compute context to SQL Server and execute the code in that compute context.

Определение параметров и входных данных хранимой процедурыDefine stored procedure parameters and inputs

StoredProcedure является основным конструктором, используемым для создания хранимой процедуры.StoredProcedure is the main constructor used to build the stored procedure. Этот конструктор создает объект хранимой процедуры SQL Server и при необходимости создает текстовый файл, содержащий запрос, который можно использовать для создания хранимой процедуры с помощью команды T-SQL.This constructor generates a SQL Server Stored Procedure object, and optionally creates a text file containing a query that can be used to generate the stored procedure using a T-SQL command.

При необходимости функция StoredProcedure может зарегистрировать хранимую процедуру с помощью указанного экземпляра и базы данных.Optionally, the StoredProcedure function can also register the stored procedure with the specified instance and database.

  • Используйте аргумент func для указания допустимой функции R.Use the func argument to specify a valid R function. Все переменные, которые использует функция, должны быть определены внутри функции либо представления в виде входных параметров.All the variables that the function uses must be defined either inside the function or be provided as input parameters. Эти параметры могут включать не более одного кадра данных.These parameters can include a maximum of one data frame.

  • Функция R должна возвращать кадр данных, именованный список или значение NULL.The R function must return either a data frame, a named list, or a NULL. Если функция возвращает список, он может содержать не более одного data.frame.If the function returns a list, the list can contain a maximum of one data.frame.

  • Используйте аргумент spName для указания имени создаваемой хранимой процедуры.Use the argument spName to specify the name of the stored procedure you want to create.

  • Можно передать необязательные входные и выходные параметры с помощью объектов, созданных следующими вспомогательными функциями: setInputData, setInputParameterи setOutputParameter.You can pass in optional input and output parameters, using the objects created by these helper functions: setInputData, setInputParameter, and setOutputParameter.

  • При необходимости используйте filePath для указания пути и имени создаваемого SQL-файла.Optionally, use filePath to provide the path and name of a .sql file to create. Этот файл можно запустить на экземпляре SQL Server для создания хранимой процедуры с помощью T-SQL.You can run this file on the SQL Server instance to generate the stored procedure using T-SQL.

  • Для определения сервера и базы данных, где будет сохранена хранимая процедура, используйте аргументы dbName и connectionString.To define the server and database where the stored procedure will be saved, use the arguments dbName and connectionString.

  • Чтобы получить список объектов InputData и InputParameter , которые использовались для создания определенного объекта StoredProcedure , вызовите getInputParameters.To get a list of the InputData and InputParameter objects that were used to create a specific StoredProcedure object, call getInputParameters.

  • Чтобы зарегистрировать хранимую процедуру в указанной базе данных, используйте registerStoredProcedure.To register the stored procedure with the specified database, use registerStoredProcedure.

Объект хранимой процедуры обычно не имеет связанных с ним данных или значений, если только не указано значение по умолчанию.The stored procedure object typically does not have any data or values associated with it, unless a default value was specified. Данные не извлекаются до выполнения хранимой процедуры.Data is not retrieved until the stored procedure is executed.

Указание входных данных и выполнениеSpecify inputs and execute

  • Используйте setInputDataQuery для назначения запроса объекту InputParameter .Use setInputDataQuery to assign a query to an InputParameter object. Например, если вы создали объект хранимой процедуры в R, можно использовать setInputDataQuery для передачи аргументов в StoredProcedure для выполнения хранимой процедуры с нужными входными данными.For example, if you have created a stored procedure object in R, you can use setInputDataQuery to pass arguments to the StoredProcedure function in order to execute the stored procedure with the desired inputs.

  • Используйте setInputValue для назначения конкретного значения параметру, сохраненному в виде объекта InputParameter .Use setInputValue to assign specific values to a parameter stored as an InputParameter object. Затем передайте объект параметра и его назначение значения в StoredProcedure , чтобы выполнить хранимую процедуру с заданными значениями.You then pass the parameter object and its value assignment to the StoredProcedure function to execute the stored procedure with the set values.

  • Используйте executeStoredProcedure для выполнения хранимой процедуры, определенной в виде объекта StoredProcedure .Use executeStoredProcedure to execute a stored procedure defined as an StoredProcedure object. Вызывайте эту функцию только при выполнении хранимой процедуры из кода R.Call this function only when executing a stored procedure from R code. Не используйте ее при запуске хранимой процедуры из SQL Server с помощью T-SQL.Do not use it when running the stored procedure from SQL Server using T-SQL.

Примечание

Функции executeStoredProcedure требуется поставщик ODBC 3.8, например драйвер ODBC 13 для SQL Server.The executeStoredProcedure function requires an ODBC 3.8 provider, such as ODBC Driver 13 for SQL Server.

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

Создание хранимой процедуры с помощью sqlrutilsHow to create a stored procedure using sqlrutils