Azure Data Explorer에서 Jupyter Notebook 및 kqlmagic 확장을 사용하여 데이터 분석

  • 아티클

Jupyter Notebook 라이브 코드, 수식, 시각화 및 내러티브 텍스트가 포함된 문서를 만들고 공유할 수 있는 오픈 소스 웹 애플리케이션입니다. 데이터 정리 및 변환, 숫자 시뮬레이션, 통계 모델링, 데이터 시각화 및 기계 학습과 같은 광범위한 작업에 유용합니다.

Kqlmagic은 Jupyter Notebook에서 Python 커널의 기능을 확장하므로 KQL(Kusto 쿼리 언어) 쿼리를 기본적으로 실행할 수 있습니다. Python과 KQL을 결합하여 render 연산자가 통합된 Plot.ly 라이브러리로 데이터를 쿼리하고 시각화할 수 있습니다. kqlmagic 확장은 Jupyter Lab, Visual Studio Code Jupyter 확장 및 Azure Data Studio와 호환되며 지원되는 데이터 원본에는 Azure Data Explorer, Azure Monitor 로그 및 Application Insights가 포함됩니다.

이 문서에서는 Jupyter Notebook kqlmagic을 사용하여 Azure Data Explorer 저장된 데이터에 연결하고 쿼리하는 방법을 알아봅니다.

사전 요구 사항

  • Microsoft 계정 또는 Microsoft Entra 사용자 ID. Azure 구독이 필요하지 않습니다.
  • Jupyter Notebook 로컬 컴퓨터에 설치됩니다. 그렇지 않으면 Azure Data Studio를 사용합니다.
  • Python 3.6. Jupyter Notebook 커널 버전을 Python 3.6으로 변경하려면 커널커널>>Python 3.6 변경을 선택합니다.

kqlmagic 설치

kqlmagic 확장을 설치하고 로드한 후에는 Notebook에서 KQL 쿼리를 작성할 수 있습니다. 커널이 중지되거나 결과가 예상대로 되지 않으면 kqlmagic 확장을 다시 로드합니다.

  1. kqlmagic을 설치하려면 다음 명령을 실행합니다.

    !pip install Kqlmagic --no-cache-dir  --upgrade

  2. kqlmagic 확장을 로드하려면 다음 명령을 실행합니다.

    %reload_ext Kqlmagic

클러스터에 연결

원하는 방법으로 클러스터에 연결할 탭을 선택합니다.

Microsoft Entra 코드 메서드는 MSAL 대화형 로그인을 묻는 메시지를 표시합니다. 인증을 위해 입력할 코드를 받게 됩니다.

%kql AzureDataExplorer://code;cluster='<cluster-name>';database='<database-name>'

팁

  • 연결 문자열 매개 변수화하려면 Python 식으로 해석될 때 따옴표가 지정되지 않은 값을 사용합니다.
  • 자격 증명을 가져오는 프로세스를 간소화하려면 연결 옵션을 참조하세요.

클러스터 연결의 예

다음 명령은 Microsoft Entra 코드 메서드를 사용하여 클러스터에서 호스트되는 Samples 데이터베이스에 인증합니다help. Microsoft Entra 아닌 사용자의 경우 테넌트 이름을 Microsoft.com Microsoft Entra 테넌트로 바꿉다.

%kql AzureDataExplorer://tenant="Microsoft.com";code;cluster='help';database='Samples'

연결 옵션

자격 증명을 가져오는 프로세스를 간소화하기 위해 연결 문자열 다음에 다음 옵션 플래그 중 하나를 추가할 수 있습니다.

옵션 Description 구문 예
try_azcli_login Azure CLI에서 인증 자격 증명을 가져옵니다. -try_azcli_login
try_azcli_login_subscription 지정된 구독에 따라 Azure CLI에서 인증 자격 증명을 가져옵니다. -try_azcli_login_subscription=<subscription_id>
try_vscode_login Visual Studio Code Azure 계정 로그인에서 인증 자격 증명을 가져옵니다. -try_vscode_login
try_msi MSI 로컬 엔드포인트에서 인증 자격 증명을 가져옵니다. 선택적 MSI 매개 변수resource인 , ,/client_idobject_idmis_res_id/ , cloud_environment가 timeout있는 사전이 예상됩니다. -try_msi={"client_id":<id>}
try_token 지정된 토큰을 사용하여 인증합니다. Azure AD v1 또는 v2 토큰 속성이 있는 사전이 예상됩니다. -try_token={"tokenType":"bearer","accessToken":"<token>"}

연결 옵션의 예

이전 표에 설명된 모든 옵션은 연결 문자열 후에 추가할 수 있습니다. 다음 예제에서는 Azure CLI 로그인 옵션을 사용합니다.

%kql azureDataExplorer://code;cluster='help';database='Samples' -try_azcli_login

연결 정보 표시

모든 기존 연결을 보려면 다음 명령을 실행합니다.

%kql --conn

특정 연결의 세부 정보를 검사 다음 명령을 실행합니다.

%kql --conn <database-name>@<cluster-name>

쿼리 및 시각화

렌더링 연산자를 사용하여 데이터를 쿼리하고 ploy.ly 라이브러리를 사용하여 데이터를 시각화합니다. 이 쿼리 및 시각화는 네이티브 KQL을 사용하는 통합 환경을 제공합니다. Kqlmagic은 timepivot, pivotchart 및 ladderchart를 제외한 대부분의 차트를 지원합니다. kind, ysplit 및 accumulate를 제외한 모든 특성에서 렌더링이 지원됩니다.

원형 차트 쿼리 및 렌더링

%%kql
StormEvents
| summarize statecount=count() by State
| sort by statecount 
| take10
| render piechart title="My Pie Chart by State"

시간 차트 쿼리 및 렌더링

%%kql
StormEvents
| summarize count() by bin(StartTime,7d)
| render timechart

참고

이러한 차트는 대화형으로 작동합니다. 시간 범위를 선택하여 특정 시간을 확대합니다.

차트 색 사용자 지정

기본 색상표를 사용하지 않으려면 팔레트 옵션을 사용하여 차트를 사용자 지정합니다. 사용 가능한 팔레트는 다음에서 찾을 수 있습니다. kqlmagic 쿼리 차트 결과에 대한 색상 팔레트 선택

  1. 팔레트 목록의 경우 다음을 수행합니다.

    %kql --palettes -popup_window

  2. cool 색상표를 선택하고 쿼리를 다시 렌더링합니다.

    %%kql -palette_name "cool"
StormEvents
| summarize statecount=count() by State
| sort by statecount
| take10
| render piechart title="My Pie Chart by State"

Python을 사용하여 쿼리를 매개 변수화

Kqlmagic을 사용하면 Kusto 쿼리 언어 Python 간에 간단한 교환이 가능합니다. 자세한 정보: Python을 사용하여 kqlmagic 쿼리 매개 변수화

KQL 쿼리에 Python 변수 사용

쿼리에 Python 변수 값을 사용하여 데이터를 필터링할 수 있습니다.

statefilter = ["TEXAS", "KANSAS"]

%%kql
let _state = statefilter;
StormEvents 
| where State in (_state) 
| summarize statecount=count() by bin(StartTime,1d), State
| render timechart title = "Trend"

쿼리 결과를 Pandas DataFrame으로 변환

Pandas DataFrame에서 KQL 쿼리의 결과에 액세스할 수 있습니다. _kql_raw_result_ 변수를 통해 마지막으로 실행된 쿼리 결과에 액세스하고 다음과 같이 결과를 Pandas DataFrame으로 쉽게 변환합니다.

df = _kql_raw_result_.to_dataframe()
df.head(10)

예제

다양한 분석 시나리오에서 많은 쿼리를 포함하고 한 쿼리의 결과를 후속 쿼리에 피드하는 재사용 가능한 Notebook을 만들 수 있습니다. 아래 예제에서는 Python 변수 statefilter를 사용하여 데이터를 필터링합니다.

  1. 쿼리를 실행하여 DamageProperty가 최댓값인 상위 10개 주를 확인합니다.

    %%kql
StormEvents
| summarize max(DamageProperty) by State
| order by max_DamageProperty desc
| take10

  2. 쿼리를 실행하여 상위 주를 추출하고 Python 변수에 설정합니다.

    df = _kql_raw_result_.to_dataframe()
statefilter =df.loc[0].State
statefilter

  3. let 문과 Python 변수를 사용하여 쿼리를 실행합니다.

    %%kql
let _state = statefilter;
StormEvents 
| where State in (_state)
| summarize statecount=count() by bin(StartTime,1d), State
| render timechart title = "Trend"

  4. help 명령을 실행합니다.

    %kql --help "help"

팁

사용 가능한 모든 구성에 대한 정보를 받으려면 %config Kqlmagic을 사용합니다. 연결 문제 및 잘못된 쿼리와 같은 Kusto 오류를 해결하고 캡처하려면 %config Kqlmagic.short_errors=False를 사용합니다.

샘플 Notebook

관련 콘텐츠