SQL Server용 확장성 프레임워크 API

적용 대상: SQL Server 2019(15.x) 이상 버전

확장성 프레임워크를 사용하여 SQL Server용 프로그래밍 언어 확장을 작성할 수 있습니다. SQL Server용 확장성 프레임워크 API는 언어 확장에서 SQL Server와 상호 작용하고 데이터를 교환하는 데 사용할 수 있는 API입니다.

언어 확장 작성자로서 이 참조를 오픈 소스 언어 확장과 함께 사용하여 API를 사용하여 직접 작성하는 방법을 이해할 수 있습니다. aka.ms/mssql-lang-extensions 언어 확장의 소스 코드를 찾을 수 있습니다.

이 문서에서는 모든 API 함수에 대한 구문 및 인수 정보를 찾을 수 있습니다.

반환 값

모든 함수는 매개 변수를 반환합니다 SQLRETURN . 값이 다른 SQL_SUCCESS값이면 값이 오류로 처리되고 스크립트 실행이 중지됩니다.

표준 출력

표준 출력 또는 오류 스트림에 대한 확장의 모든 출력은 세션의 로그 파일로 추적되고 결국 SQL Server로 다시 추적됩니다. 이는 SSMS(SQL Server Management Studio) 메시지 탭에 표시되는 것과 유사합니다.

Init

이 함수는 한 번만 호출되며 실행을 위한 런타임을 초기화하는 데 사용됩니다.

구문

SQLRETURN Init(
    SQLCHAR *ExtensionParams,
    SQLULEN ExtensionParamsLength,
    SQLCHAR *ExtensionPath,
    SQLULEN ExtensionPathLength,
    SQLCHAR *PublicLibraryPath,
    SQLULEN PublicLibraryPathLength,
    SQLCHAR *PrivateLibraryPath,
    SQLULEN PrivateLibraryPathLength
);

인수

인수 입력/출력 설명
ExtensionParams Input 값을 포함하는 PARAMETERS 널 종단 문자열 중 CREATE EXTERNAL LANGUAGE 또는 ALTER EXTERNAL LANGUAGE
ExtensionParamsLength Input 길이( ExtensionParams null 종료 문자 제외)
ExtensionPath Input 확장의 설치 디렉터리에 대한 절대 경로를 포함하는 Null 종료 UTF-8 문자열
ExtensionPathLength Input 길이( ExtensionPath null 종료 문자 제외)
PublicLibraryPath Input 이 외부 언어에 대한 공용 외부 라이브러리 디렉터리에 대한 절대 경로를 포함하는 Null 종료 UTF-8 문자열
PublicLibraryPathLength Input 길이( PublicLibraryPath null 종료 문자 제외)
PrivateLibraryPath Input 이 사용자 및 이 외부 언어에 대한 프라이빗 외부 라이브러리 디렉터리에 대한 절대 경로를 포함하는 Null로 종료된 UTF-8 문자열
PrivateLibraryPathLength Input 길이( PrivateLibraryPath null 종료 문자 제외)

InitSession

이 함수는 세션당 한 번 호출되며 세션별 설정을 초기화합니다.

구문

SQLRETURN InitSession(
    SQLGUID         SessionId,
    SQLUSMALLINT    TaskId,
    SQLCHAR*        Script,
    SQLULEN         ScriptLength,
    SQLUSMALLINT    InputSchemaColumnsNumber,
    SQLUSMALLINT    ParametersNumber
    SQLCHAR*        InputDataName,
    SQLUSMALLINT    InputDataNameLength,
    SQLCHAR*        OutputDataName,
    SQLUSMALLINT    OutputDataNameLength
);

인수

인수 입력/출력 설명
SessionId Input 이 스크립트 세션을 고유하게 식별하는 GUID
TaskId Input 이 실행 프로세스를 고유하게 식별하는 정수입니다.

sp_execute_external_script 이 값의 범위는 @parallel 쿼리의 병렬 처리 수준까지 1 입니다.0
Script Input in sp_execute_external_script 포함하는 @script Null로 종료된 UTF-8 문자열
ScriptLength Input 길이( ScriptScript null 종료 문자 제외)
InputSchemaColumnsNumber Input sp_execute_external_script 결과 집합 @input_data_1의 열 수
ParametersNumber Input sp_execute_external_script 입력 매개 변수 @params
InputDataName Input in sp_execute_external_script 포함하는 @input_data_1_name Null로 종료된 UTF-8 문자열
InputDataNameLength Input 길이( InputDataName null 종료 문자 제외)
OutputDataName Input in sp_execute_external_script 포함하는 @output_data_1_name Null로 종료된 UTF-8 문자열
OutputDataNameLength Input 길이( OutputDataName null 종료 문자 제외)

InitColumn

특정 세션에 대해 지정된 열에 대한 정보를 초기화합니다.

이 함수는 sp_execute_external_script 결과 집합 @input_data_1 의 각 열에 대해 호출됩니다.

이 결과 집합의 열 구조를 입력 스키마라고 합니다.

구문

SQLRETURN InitColumn(
    SQLGUID       SessionId,
    SQLUSMALLINT  TaskId,
    SQLUSMALLINT  ColumnNumber,
    SQLCHAR*      ColumnName,
    SQLSMALLINT   ColumnNameLength,
    SQLSMALLINT   DataType,
    SQLULEN       ColumnSize,
    SQLSMALLINT   DecimalDigits,
    SQLSMALLINT   Nullable,
    SQLSMALLINT   PartitionByNumber,
    SQLSMALLINT   OrderByNumber
);

인수

인수 입력/출력 설명
SessionId Input 이 스크립트 세션을 고유하게 식별하는 GUID
TaskId Input 이 실행 프로세스를 고유하게 식별하는 정수입니다.

sp_execute_external_script 이 값의 범위는 @parallel 쿼리의 병렬 처리 수준까지 1 입니다.0
ColumnNumber Input 입력 스키마에서 이 열의 인덱스를 식별하는 정수입니다. 열은 순차적으로 번호가 매겨집니다. 0
ColumnName Input 열 이름을 포함하는 Null로 종료된 UTF-8 문자열
ColumnNameLength Input 길이( ColumnName null 종료 문자 제외)
Data type Input 이 열의 데이터 형식을 식별하는 ODBC C 형식
ColumnSize Input 이 열에 있는 기본 데이터의 최대 크기(바이트)입니다.

SQL_C_CHARSQL_C_WCHAR 데이터 형식의 경우 SQL_C_BINARY8,000보다 큰 값은 이 열이 LOB 개체를 나타내며 크기는 최대 2GB입니다.
DecimalDigits Input 10진수로 정의된 이 열의 기본 데이터의 10진수입니다.
Nullable Input 이 열에 값이 포함될 NULL 수 있는지 여부를 나타내는 값입니다. 가능한 값:

- SQL_NO_NULLS: 열에 값을 포함 NULL 할 수 없습니다.
- SQL_NULLABLE: 열에 값이 포함될 NULL 수 있습니다.
PartitionByNumber Input sp_execute_external_script 시퀀스에서 이 열 @input_data_1_partition_by_columns 의 인덱스를 나타내는 값입니다. 열은 순차적으로 0번호가 매겨집니다. 이 열이 시퀀스에 포함되지 않은 경우 값은 -1입니다.
OrderByNumber Input sp_execute_external_script 시퀀스에서 이 열 @input_data_1_order_by_columns 의 인덱스를 나타내는 값입니다. 열은 순차적으로 0번호가 매겨집니다. 이 열이 시퀀스에 포함되지 않은 경우 값은 -1입니다.

InitParam

특정 세션의 지정된 입력 매개 변수와 관련된 정보를 초기화합니다.

이 함수는 sp_execute_external_script 각 매개 변수에 @params대해 호출됩니다.

구문

SQLRETURN InitParam(
    SQLGUID      SessionId,
    SQLUSMALLINT TaskId,
    SQLUSMALLINT ParamNumber,
    SQLCHAR*     ParamName,
    SQLSMALLINT  ParamNameLength,
    SQLSMALLINT  DataType,
    SQLULEN      ParamSize,
    SQLSMALLINT  DecimalDigits,
    SQLPOINTER   ParamValue,
    SQLINTEGER   StrLen_or_Ind,
    SQLSMALLINT  InputOutputType
);

인수

인수 입력/출력 설명
SessionId Input 이 스크립트 세션을 고유하게 식별하는 GUID
TaskId Input 이 실행 프로세스를 고유하게 식별하는 정수입니다.

sp_execute_external_script 이 값의 범위는 @parallel 쿼리의 병렬 처리 수준까지 1 입니다.0
ParamNumber Input 이 매개 변수의 인덱스 식별 정수입니다. 매개 변수는 순서가 증가하여 순차적으로 번호가 매겨집니다. 0
ParamName Input 매개 변수의 이름을 포함하는 Null로 종료된 UTF-8 문자열
ParamNameLength Input 길이( ParamName null 종료 문자 제외)
Data type Input 이 매개 변수의 데이터 형식을 식별하는 ODBC C 형식
ParamSize Input 이 매개 변수의 기본 데이터의 최대 크기(바이트)입니다.

SQL_C_CHARSQL_C_WCHAR 데이터 형식의 경우 SQL_C_BINARY8000보다 큰 값은 이 매개 변수가 LOB 개체를 나타내고 크기가 최대 2GB임을 나타냅니다.
DecimalDigits Input 10진수로 정의된 이 매개 변수의 기본 데이터의 10진수입니다.
ParamValue Input 매개 변수의 값이 포함된 버퍼에 대한 포인터
StrLen_or_Ind Input 길이를 바이트 ParamValue단위로 나타내거나 SQL_NULL_DATA 데이터가 됨을 나타내는 정수 값입니다 NULL.

StrLen_or_Ind[col]열이 null을 허용하지 않고 다음 데이터 형식 SQL_C_CHARSQL_C_WCHARSQL_C_BINARYSQL_C_NUMERICSQL_C_TYPE_TIMESTAMP중 하나를 나타내지 않는 경우 무시될 수 있습니다. 그렇지 않으면 요소가 있는 유효한 배열 RowsNumber 을 가리키며, 각 요소에는 길이 또는 null 표시기 데이터가 포함됩니다.
InputOutputType Input 매개 변수의 형식입니다. 인수는 InputOutputType 다음 값 중 하나입니다.

- SQL_PARAM_INPUT
- SQL_PARAM_INPUT_OUTPUT

실행

in sp_execute_external_script @script실행합니다.

이 함수는 여러 번 호출될 수 있습니다. 각 스팀 청크 및 in sp_execute_external_script@input_data_1_partition_by_columns 대해 한 번.

구문

SQLRETURN Execute(
    SQLGUID         SessionId,
    SQLUSMALLINT    TaskId,
    SQLULEN         RowsNumber,
    SQLPOINTER*     Data,
    SQLINTEGER**    StrLen_or_Ind,
    SQLUSMALLINT*   OutputSchemaColumnsNumber
);

인수

인수 입력/출력 설명
SessionId Input 이 스크립트 세션을 고유하게 식별하는 GUID
TaskId Input 이 실행 프로세스를 고유하게 식별하는 정수입니다.

sp_execute_external_script 이 값의 범위는 @parallel 쿼리의 병렬 처리 수준까지 1 입니다.0
RowsNumber Input 의 행 수 Data
Data Input sp_execute_external_script 결과 집합 @input_data_1을 포함하는 2차원 배열입니다.

총 열 수는 InitSessionInputSchemaColumnsNumber수신된 열 입니다. 각 열에는 RowsNumber InitColumn의 열 형식에 따라 해석되어야 하는 요소가 포함됩니다.
있는 것으로 NULLStrLen_or_Ind 표시된 요소는 유효하지 않으며 무시해야 합니다.
StrLen_or_Ind Input 의 각 값 Data에 대한 길이/NULL 표시기를 포함하는 2차원 배열입니다. 각 셀의 가능한 값:

- n, 여기서 n > 0. 데이터의 길이(바이트)를 나타냅니다.
- SQL_NULL_DATA- 값을 나타냅니다 NULL .
총 열 수는 InitSessionInputSchemaColumnsNumber수신된 열 입니다. 각 열에는 RowsNumber InitColumn의 열 형식에 따라 해석되어야 하는 요소가 포함됩니다.
StrLen_or_Ind[col]한 열이 null을 허용하지 않고 다음 데이터 형식 SQL_C_CHARSQL_C_WCHARSQL_C_BINARYSQL_C_NUMERICSQL_C_TYPE_TIMESTAMP중 하나를 나타내지 않는 경우 무시될 수 있습니다. 그렇지 않으면 요소가 있는 유효한 배열 RowsNumber 을 가리키고 각 요소에는 길이 또는 null 표시기 데이터가 포함됩니다.
OutputSchemaColumnsNumber 출력 in sp_execute_external_script 예상 결과 집합의 열 수를 반환할 버퍼에 대한 @script포인터입니다.

GetResultColumn

특정 세션에 대해 지정된 출력 열에 대한 정보를 검색합니다.

이 함수는 sp_execute_external_script 결과 집합 @script 의 각 열에 대해 호출됩니다.

이 결과 집합의 열 구조를 출력 스키마라고 합니다.

구문

SQLRETURN GetResultColumn(
    SQLGUID         SessionId,
    SQLUSMALLINT    TaskId,
    SQLUSMALLINT    ColumnNumber,
    SQLSMALLINT*    DataType,
    SQLINTEGER*     ColumnSize,
    SQLSMALLINT*    DecimalDigits,
    SQLSMALLINT*    Nullable
);

인수

인수 입력/출력 설명
SessionId Input 이 스크립트 세션을 고유하게 식별하는 GUID
TaskId Input 이 실행 프로세스를 고유하게 식별하는 정수입니다.

sp_execute_external_script 이 값의 범위는 @parallel 쿼리의 병렬 처리 수준까지 1 입니다.0
ColumnNumber Input 출력 스키마에서 이 열의 인덱스를 식별하는 정수입니다. 열은 순차적으로 번호가 매겨집니다. 0
Data type 출력 이 열의 데이터 형식을 식별하는 ODBC C 형식이 포함된 버퍼에 대한 포인터입니다.
ColumnSize 출력 이 열에 있는 기본 데이터의 최대 크기(바이트)를 포함하는 버퍼에 대한 포인터입니다.
DecimalDigits 출력 10진수로 정의된 대로 이 열에 있는 기본 데이터의 10진수를 포함하는 버퍼에 대한 포인터입니다. 소수 자릿수를 확인할 수 없거나 적용할 수 없는 경우 값은 삭제됩니다.
Nullable 출력 값이 들어 있는 버퍼에 대한 포인터로, 이 열에 값이 포함될 NULL 수 있는지 여부를 나타냅니다. 가능한 값:

- SQL_NO_NULLS: 열에 값을 포함 NULL 할 수 없습니다.
- SQL_NULLABLE: 열에 값이 포함될 NULL 수 있습니다.
다른 값이 전달되면 실행이 중지됩니다.

GetResults

in @script 실행하여 결과 집합을 검색합니다.

이 함수는 여러 번 호출될 수 있습니다. 각 스팀 청크 및 in sp_execute_external_script@input_data_1_partition_by_columns 대해 한 번.

구문

SQLRETURN GetResults(
    SQLGUID         SessionId,
    SQLUSMALLINT    TaskId,
    SQLULEN*        RowsNumber,
    SQLPOINTER**    Data,
    SQLINTEGER***   StrLen_or_Ind
);

인수

인수 입력/출력 설명
SessionId Input 이 스크립트 세션을 고유하게 식별하는 GUID
TaskId Input 이 실행 프로세스를 고유하게 식별하는 정수입니다.

sp_execute_external_script 이 값의 범위는 @parallel 쿼리의 병렬 처리 수준까지 1 입니다.0
RowsNumber 출력 의 행 수를 포함하는 버퍼에 대한 포인터입니다. Data
Data 출력 sp_execute_external_script@script대한 포인터입니다.

실행OutputSchemaColumnsNumber검색된 총 열 수입니다. 각 열에는 GetResultColumn의 열 형식에 따라 해석되어야 하는 요소가 포함되어 RowsNumber 야 합니다.
StrLen_or_Ind 출력 의 각 값에 대한 길이/NULL 표시기를 포함하는 확장에서 할당한 2차원 배열에 Data대한 포인터입니다. 각 셀의 가능한 값:

- n, 여기서 n > 0. 데이터의 길이(바이트)를 나타냅니다.
- SQL_NULL_DATA- 값을 나타냅니다 NULL .
실행OutputSchemaColumnsNumber받은 총 열 수입니다. 각 열에는 RowsNumber GetResultColumn의 열 형식에 따라 해석되어야 하는 요소가 포함되어 있습니다.
StrLen_or_Ind[col] 는 무시됩니다. 한 열이 null을 허용하지 않고 다음 데이터 형식 SQL_C_CHAR중 하나를 나타내지 않는 경우 , SQL_C_WCHARSQL_C_BINARY[add dates]. 그렇지 않으면 요소가 있는 유효한 배열 RowsNumber 을 가리키고 각 요소에는 길이 또는 null 표시기 데이터가 포함됩니다.

GetOutputParam

특정 세션에 대해 지정된 출력 매개 변수에 대한 정보를 검색합니다.

이 함수는 로 표시된 @paramssp_execute_external_scriptOUTPUT대해 호출됩니다.

구문

SQLRETURN GetOutputParam(
    SQLGUID        SessionId,
    SQLUSMALLINT   ParamNumber,
    SQLPOINTER*    ParamValue,
    SQLINTEGER*    StrLen_or_Ind
);

인수

인수 입력/출력 설명
SessionId Input 이 스크립트 세션을 고유하게 식별하는 GUID
ParamValue 출력 매개 변수의 값이 포함된 버퍼에 대한 포인터
StrLen_or_Ind 출력 길이(바이트 ParamValue)를 나타내는 정수 값이 들어 있거나 SQL_NULL_DATA 데이터가 인 버퍼에 대한 포인터입니다. NULL

GetInterfaceVersion

인터페이스 버전을 검색합니다.

이 함수는 확장의 인터페이스 버전을 나타내는 정수를 반환합니다.

지원되는 값:

  1. 버전 1은 초기 API 버전입니다. SQL Server 2019(15.x) RTM에서 지원됩니다.
  2. 버전 2는 지원 및 InstallExternalLibrary API를 UninstallExternalLibrary 추가했으며 SQL Server 2019(15.x) CU 3에서 지원됩니다.

구문

SQLUSMALLINT GetInterfaceVersion();

CleanupSession

세션별 정보를 정리합니다.

구문

SQLRETURN CleanupSession(
    SQLGUID        SessionId,
    SQLUSMALLINT   TaskId
);

인수

인수 입력/출력 설명
SessionId Input 이 스크립트 세션을 고유하게 식별하는 GUID
TaskId Input 이 실행 프로세스를 고유하게 식별하는 정수입니다.

sp_execute_external_script 이 값의 범위는 @parallel 쿼리의 병렬 처리 수준까지 1 입니다.0

정리

전역 공유 정보(예: JVM)를 정리합니다.

구문

SQLRETURN Cleanup();

GetTelemetryResults

확장에서 원격 분석(키-값 쌍) 데이터를 검색합니다. 이 함수는 선택 사항으로, 구현이 필요하지 않습니다. 원격 분석은 DMV(동적 관리 뷰)에 의해 dm_db_external_script_execution_stats 노출됩니다.

프레임워크에서 보내는 명명 script_executions된 카운터가 있습니다. 확장은 이 이름을 사용하면 안 됩니다.

각 원격 분석 항목은 키-값 쌍입니다. 키는 문자열입니다. 값은 64비트 정수 또는 카운터입니다. 따라서 출력은 이름과 해당 카운터의 두 논리 배열로 구성됩니다. 각 배열은 출력입니다.

각 배열의 길이는 RowsNumber출력입니다. 첫 번째 논리 출력에는 문자열에 대한 포인터가 포함됩니다. 두 배열 CounterNames (실제 문자열 데이터) 및 CounterNamesLength (각 문자열의 길이)로 표시됩니다. 두 번째 논리 출력은 포인터에 CounterValues 저장됩니다.

구문

SQLRETURN GetTelemetryResults(
    SQLGUID        SessionId,
    SQLUSMALLINT   TaskId,
    SQLUINTEGER    *RowsNumber,
    SQLCHAR        ***CounterNames,
    SQLINTEGER     **CounterNamesLength,
    SQLBIGINT      **CounterValues
);

인수

인수 입력/출력 설명
SessionId Input 이 스크립트 세션을 고유하게 식별하는 GUID
TaskId Input 이 실행 프로세스를 고유하게 식별하는 정수입니다.

sp_execute_external_script 이 값의 범위는 @parallel 쿼리의 병렬 처리 수준까지 1 입니다.0
RowsNumber 출력 키-값 쌍의 수
CounterNames 출력 키를 포함하는 문자열 데이터
CounterNamesLength 출력 각 키 문자열의 길이
CounterValues 출력 값을 포함하는 64비트 정수 데이터

InstallExternalLibrary

라이브러리를 설치합니다. 이 함수는 선택 사항으로, 구현이 필요하지 않습니다. 기본 구현은 라이브러리의 내용을 적절한 위치에 있는 파일로 복사하는 것입니다(참조 CREATE EXTERNAL LIBRARY). 파일 이름은 라이브러리 이름입니다.

구문

SQLRETURN InstallExternalLibrary(
    SQLGUID    SetupSessionId,
    SQLCHAR    *LibraryName,
    SQLINTEGER LibraryNameLength,
    SQLCHAR    *LibraryFile,
    SQLINTEGER LibraryFileLength,
    SQLCHAR    *LibraryInstallDirectory,
    SQLINTEGER LibraryInstallDirectoryLength,
    SQLCHAR    **LibraryError,
    SQLINTEGER *LibraryErrorLength
);

인수

인수 입력/출력 설명
SetupSessionId Input 이 스크립트 세션을 고유하게 식별하는 GUID
LibraryName Input 라이브러리 이름
LibraryNameLength Input 라이브러리 이름의 길이
LibraryFile Input 지정된 이진 콘텐츠를 포함하는 라이브러리 파일의 경로(문자열)입니다. CREATE EXTERNAL LIBRARY
LibraryFileLength Input 문자열의 LibraryFile 길이
LibraryInstallDirectory Input 라이브러리를 설치할 루트 디렉터리
LibraryInstallDirectoryLength Input 문자열의 LibraryInstallDirectory 길이
LibraryError 출력 선택적 출력 매개 변수입니다. 라이브러리 LibraryError 를 설치하는 동안 오류가 발생하는 경우 오류를 설명하는 문자열을 가리킵니다.
LibraryErrorLength 출력 문자열의 LibraryError 길이

UninstallExternalLibrary

라이브러리를 제거합니다. 이 함수는 선택 사항으로, 구현이 필요하지 않습니다. 기본 구현은 기본 구현에 의해 수행된 작업을 실행 취소하는 InstallExternalLibrary것입니다. 기본 구현은 아래 LibraryName파일의 LibraryInstallDirectory 콘텐츠를 삭제합니다.

구문

SQLRETURN UninstallExternalLibrary(
    SQLGUID    SetupSessionId,
    SQLCHAR    *LibraryName,
    SQLINTEGER LibraryNameLength,
    SQLCHAR    *LibraryInstallDirectory,
    SQLINTEGER LibraryInstallDirectoryLength,
    SQLCHAR    **LibraryError,
    SQLINTEGER *LibraryErrorLength
);

인수

인수 입력/출력 설명
SetupSessionId Input 이 스크립트 세션을 고유하게 식별하는 GUID
LibraryName Input 라이브러리 이름
LibraryNameLength Input 라이브러리 이름의 길이
LibraryFile Input 지정된 이진 콘텐츠를 포함하는 라이브러리 파일의 경로(문자열)입니다. CREATE EXTERNAL LIBRARY
LibraryFileLength Input 문자열의 LibraryFile 길이
LibraryInstallDirectory Input 라이브러리를 설치할 루트 디렉터리
LibraryInstallDirectoryLength Input 문자열의 LibraryInstallDirectory 길이
LibraryError 출력 라이브러리 오류 문자열
LibraryErrorLength 출력 문자열의 LibraryError 길이