Python 플러그 인

아티클
10/15/2024

적용 대상: ✅Microsoft Fabric ✅Azure Data Explorer

Python 플러그 인은 Python 스크립트를 사용하여 UDF(사용자 정의 함수)를 실행합니다. Python 스크립트는 테이블 형식 데이터를 입력으로 가져오고 테이블 형식 출력을 생성합니다. 플러그 인의 런타임은 클러스터의 노드에서 실행되는 샌드박스에서 호스트됩니다.

구문

T evaluate | [hint.distribution = (singleper_node | )] [hint.remote = (autolocal | )] python(output_schema, 스크립트 [ , script_parameters] [, external_artifacts][, spill_to_disk])

구문 규칙에 대해 자세히 알아봅니다.

매개 변수

이름	Type	필수	설명
output_schema	`string`	✔️	`type` Python 코드에서 반환하는 테이블 형식 데이터의 출력 스키마를 정의하는 리터럴입니다. 형식은 ColumnName ColumnType[, ...]`)`입니다`typeof(`.`:` 예를 들면 다음과 같습니다`typeof(col1:string, col2:long)`. 입력 스키마를 확장하려면 다음 구문을 `typeof(*, col1:string, col2:long)`사용합니다.
스크립트	`string`	✔️	실행할 유효한 Python 스크립트입니다. 여러 줄 문자열을 생성하려면 사용량 팁을 참조 하세요.
script_parameters	`dynamic`		Python 스크립트에 예약된 `kargs` 사전으로 전달할 이름 값 쌍의 속성 모음입니다. 자세한 내용은 예약된 Python 변수를 참조 하세요.
hint.distribution	`string`		여러 클러스터 노드에 분산될 플러그 인의 실행에 대한 힌트입니다. 기본값은 `single`입니다. `single` 는 스크립트의 단일 인스턴스가 전체 쿼리 데이터를 통해 실행될 것임을 의미합니다. `per_node` 는 Python 블록 앞의 쿼리가 분산되면 스크립트의 인스턴스가 포함된 데이터에서 각 노드에서 실행된다는 것을 의미합니다.
hint.remote	`string`		이 힌트는 클러스터 간 쿼리에만 관련됩니다. 기본값은 `auto`입니다. `auto` 는 서버가 Python 코드가 실행되는 클러스터를 자동으로 결정한다는 것을 의미합니다. 로컬 클러스터에서 Python 코드를 강제로 실행하도록 `local` 값을 설정합니다. 원격 클러스터에서 Python 플러그 인을 사용하지 않도록 설정한 경우에 사용합니다.
external_artifacts	`dynamic`		클라우드 스토리지에서 액세스할 수 있는 아티팩트용 이름 및 URL 쌍의 속성 모음입니다. 외부 아티팩트 사용에 대한 자세한 내용을 참조하세요.
spill_to_disk	`bool`		입력 테이블을 Python 샌드박스로 직렬화하는 대체 방법을 지정합니다. 큰 테이블을 직렬화하려면 직렬화 속도를 높이고 샌드박스 메모리 사용량을 크게 줄이도록 `true` 설정합니다. 기본값은 `true`입니다.

예약된 Python 변수

다음 변수는 Kusto 쿼리 언어 Python 코드 간의 상호 작용을 위해 예약되어 있습니다.

df: 데이터 프레임으로 pandas 입력 테이블 형식 데이터(위의 값T)입니다.
kargs: python 사전으로 script_parameters 인수의 값입니다.
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"})
)

파일	크기
this_is_a_script	120
this_is_my_first_file	105

성능 팁

플러그 인의 입력 데이터 세트를 필요한 최소 크기(열/행)로 줄입니다.
- 가능한 경우 원본 데이터 세트에 대한 필터를 Kusto의 쿼리 언어로 사용합니다.
- 원본 열의 하위 집합에 대해 계산을 수행하려면 플러그 인을 호출하기 전에 해당 열만 프로젝팅합니다.
스크립트의 논리를 배포할 수 있을 때마다 사용합니다 hint.distribution = per_node .
- 파티션 연산자를 사용하여 입력 데이터 세트를 분할할 수도 있습니다.
가능하면 Kusto의 쿼리 언어를 사용하여 Python 스크립트의 논리를 구현합니다.

사용 팁

쿼리 편집기에서 Python 스크립트가 포함된 여러 줄 문자열을 생성하려면 즐겨 사용하는 Python 편집기(Jupyter, Visual Studio Code, PyCharm 등)에서 Python 스크립트를 복사하고 쿼리 편집기에서 붙여넣은 다음 3개의 연속 백틱이 포함된 줄 사이에 전체 스크립트를 묶습니다. 예시:

```
python code
```
연산자를 externaldata 사용하여 Azure Blob Storage와 같은 외부 위치에 저장한 스크립트의 콘텐츠를 가져옵니다.

예시

    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은 다음이어야 합니다.

클러스터의 설명선 정책에 포함됩니다.
스토리지 연결 문자열 설명한 대로 공개적으로 사용 가능한 위치에서 또는 필요한 자격 증명을 제공합니다.

참고 항목

관리 ID를 사용하여 외부 아티팩트를 인증하는 경우 사용량은 SandboxArtifacts 클러스터 수준 관리 ID 정책에 정의되어야 합니다.

아티팩트를 로컬 임시 디렉터리 .\Temp에서 스크립트에서 사용할 수 있습니다. 속성 모음에 제공된 이름은 로컬 파일 이름으로 사용됩니다. 예제를 참조하세요.

외부 패키지 참조에 대한 자세한 내용은 Python 플러그 인용 패키지 설치를 참조하세요.

외부 아티팩트 캐시 새로 고침

쿼리에 사용된 외부 아티팩트 파일은 클러스터에 캐시됩니다. 클라우드 스토리지의 파일을 업데이트하고 클러스터와 즉시 동기화해야 하는 경우 .clear 클러스터 캐시 외부 아티팩트 명령을 사용할 수 있습니다. 이 명령은 캐시된 파일을 지우고 후속 쿼리가 최신 버전의 아티팩트와 함께 실행되도록 합니다.