Python 플러그 인

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

구문

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

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

매개 변수

예약된 Python 변수

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

• df: 데이터 프레임으로 pandas 입력 테이블 형식 데이터(위의 값T)입니다.
• kargs: python 사전으로 script_parameters 인수의 값입니다.
• resultpandas: Python 스크립트에서 만든 데이터 프레임으로, 해당 값은 플러그 인 뒤에 있는 Kusto 쿼리 연산자에게 전송되는 테이블 형식 데이터가 됩니다.

플러그 인 사용

플러그 인은 기본값으로 사용 중지됩니다. 시작하기 전에 필수 구성 요소 목록을 검토합니다. 플러그 인을 사용하도록 설정하고 Python 이미지 버전을 선택하려면 클러스터에서 언어 확장 사용을 참조하세요.

Python 샌드박스 이미지

Python 이미지의 버전을 다른 관리형 이미지 또는 사용자 지정 이미지로 변경하려면 클러스터에서 Python 언어 확장 이미지 변경을 참조하세요.

다른 Python 이미지에 대한 패키지 목록을 보려면 Python 패키지 참조를 참조하세요.

쿼리 및 업데이트 정책에서 수집 사용

• 다음과 같은 쿼리에서 플러그 인을 사용합니다.
  • 소스 테이블이 스트리밍이 아닌 수집을 사용하도록 수집되는 업데이트 정책의 일부로 정의됩니다.
  • 쿼리에서 수집하는 명령의 일부로 실행합니다(예: .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"})
)

성능 팁

• 플러그 인의 입력 데이터 세트를 필요한 최소 크기(열/행)로 줄입니다.
  • 가능한 경우 원본 데이터 세트에 대한 필터를 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은 다음이어야 합니다.

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

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

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

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

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

Python 플러그 인용 패키지 설치

대부분의 사용 사례에서는 사용자 지정 이미지를 만드는 것이 좋습니다.

다음과 같은 이유로 패키지를 직접 설치할 수 있습니다.

• 사용자 지정 이미지를 만들 수 있는 권한이 없습니다.
• 패키지는 프라이빗입니다.
• 테스트를 위해 임시 패키지 설치를 만드는 것을 선호하며 사용자 지정 이미지를 만드는 오버헤드를 원하지 않습니다.

다음과 같이 패키지를 설치합니다.

필수 조건

1. 클러스터와 동일한 위치에서 패키지를 호스트하는 Blob 컨테이너를 만듭니다. 예를 들어 https://artifactswestus.blob.core.windows.net/python클러스터가 미국 서부에 있다고 가정합니다.

2. 해당 위치에 대한 액세스를 허용하도록 클러스터의 설명선 정책을 변경합니다.

   • 이 변경에는 AllDatabasesAdmin 권한이 필요합니다.

   • 예를 들어, Blob https://artifactswestus.blob.core.windows.net/python에 대한 액세스를 사용하도록 설정하려면 다음 명령을 실행합니다.

   .alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/python/","CanCall": true } ]'
   

패키지 설치

1. PyPi 또는 다른 채널의 퍼블릭 패키지의 경우 패키지 및 해당 종속성을 다운로드합니다.

   • 로컬 Windows Python 환경의 cmd 창에서 다음을 실행합니다.

   pip wheel [-w download-dir] package-name.
   

2. 필요한 패키지와 해당 종속성이 포함된 zip 파일을 만듭니다.

   • 프라이빗 패키지의 경우 패키지의 폴더와 해당 종속성의 폴더를 압축합니다.
   • 퍼블릭 패키지의 경우 이전 단계에서 다운로드한 파일을 압축합니다.

   참고 항목

   • Python 엔진 및 샌드박스 런타임 플랫폼과 호환되는 패키지를 다운로드해야 합니다(현재 Windows의 경우 3.6.5).
   • 부모 폴더가 .whl 아닌 파일 자체를 압축해야 합니다.
   • 기본 샌드박스 이미지에 동일한 버전이 이미 있는 패키지의 파일을 건너뛸 .whl 수 있습니다.

3. 1단계부터 아티팩트 위치의 Blob에 압축된 파일을 업로드합니다.

4. 플러그 인을 python 호출합니다.

   • external_artifacts 이름의 속성 모음과 zip 파일(SAS 토큰을 포함한 Blob의 URL)에 대한 참조를 사용하여 매개 변수를 지정합니다.
   • 인라인 Python 코드에서 zip 파일의 이름으로 해당 install() 메서드를 sandbox_utils 가져오 Zipackage 고 호출합니다.

예시

가짜 데이터를 생성하는 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/Faker.zip?*** REPLACE WITH YOUR SAS TOKEN ***'))

관련 콘텐츠

Python 플러그 인을 사용하는 UDF 함수의 더 많은 예제는 Functions 라이브러리를 참조하세요.

Python 플러그 인은 Python 스크립트를 사용하여 UDF(사용자 정의 함수)를 실행합니다. Python 스크립트는 테이블 형식 데이터를 입력으로 가져오고 테이블 형식 출력을 생성합니다.

구문

T evaluate | [hint.distribution = (single | per_node)] [hint.remote = (auto | local)] python(output_schema , 스크립트 [, script_parameters] [, spill_to_disk])

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

매개 변수

예약된 Python 변수

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

• df: 데이터 프레임으로 pandas 입력 테이블 형식 데이터(위의 값T)입니다.
• kargs: python 사전으로 script_parameters 인수의 값입니다.
• resultpandas: Python 스크립트에서 만든 데이터 프레임으로, 해당 값은 플러그 인 뒤에 있는 Kusto 쿼리 연산자에게 전송되는 테이블 형식 데이터가 됩니다.

플러그 인 사용

플러그 인은 기본값으로 사용 중지됩니다. 시작하기 전에 KQL 데이터베이스에서 Python 플러그 인 을 사용하도록 설정합니다.

Python 샌드박스 이미지

다른 Python 이미지에 대한 패키지 목록을 보려면 Python 패키지 참조를 참조하세요.

쿼리 및 업데이트 정책에서 수집 사용

• 다음과 같은 쿼리에서 플러그 인을 사용합니다.
  • 소스 테이블이 스트리밍이 아닌 수집을 사용하도록 수집되는 업데이트 정책의 일부로 정의됩니다.
  • 쿼리에서 수집하는 명령의 일부로 실행합니다(예: .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 편집기(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 

관련 콘텐츠

Python 플러그 인을 사용하는 UDF 함수의 더 많은 예제는 Functions 라이브러리를 참조하세요.