Uso de un cuaderno y kqlmagic para analizar datos en Azure Data Explorer

Jupyter Notebook es una aplicación web de código abierto que le permite crear y compartir documentos que contengan código activo, ecuaciones, visualizaciones y texto narrativo. Resulta útil para una amplia gama de tareas, como la limpieza y transformación de datos, la simulación numérica, el modelado estadístico, la visualización de datos y el aprendizaje automático.

Kqlmagic amplía las funciones del kernel de Python en Jupyter Notebook para que pueda ejecutar consultas del lenguaje de consulta Kusto (KQL) de forma nativa. Puede combinar Python y KQL para hacer consultas y visualizar datos mediante la biblioteca Plot.ly enriquecida integrada con el operador render. La extensión Kqlmagic es compatible con Jupyter Lab, la extensión jupyter de Visual Studio Code y Azure Data Studio, y los orígenes de datos admitidos incluyen Azure Data Explorer, registros de Azure Monitor y Application Insights.

En este artículo, aprenderá a usar la extensión Kqlmagic en un cuaderno para conectarse a datos almacenados en Azure Data Explorer y consultarlos.

Requisitos previos

• Una cuenta de Microsoft o una identidad de usuario de Microsoft Entra. No se necesita una suscripción a Azure.
• Un cuaderno instalado en el equipo local. De lo contrario, utilice Azure Data Studio.
• Python 3.6. Para cambiar la versión del kernel de Jupyter Notebook a Python 3.6, selecciona Kernel>Cambiar Kernel>Python 3.6.

Instalar kqlmagic

Una vez instalada y cargada la extensión kqlmagic, puede escribir consultas KQL en su cuaderno. Si el kernel se detiene o los resultados no son los esperados, vuelve a cargar la extensión kqlmagic.

1. Para instalar kqlmagic, ejecute el siguiente comando:

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

2. Para cargar la extensión kqlmagic, ejecute el siguiente comando:

   %reload_ext Kqlmagic
   

Conectarse a un clúster

Seleccione la pestaña del método que prefiera para conectarse a su clúster.

%kql AzureDataExplorer://tenant='<tenant-id>';certificate='<certificate>';certificate_thumbprint='<thumbprint>';cluster='<cluster-name>';database='<database-name>'

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

%kql AzureDataExplorer://tenant='<tenant-id>';clientid='<aad-appid>';clientsecret='<aad-appkey>';cluster='<cluster-name>';database='<database-name>'

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

%kql azureDataExplorer://anonymous;cluster='<cluster-name>';database='<database-name>'

Ejemplo de una conexión de clúster

El siguiente comando utiliza el método de código de Microsoft Entra para autenticarse en la base de datos Samples hospedada en el clúster help. Para los usuarios que no sean de Microsoft Entra, sustituya el nombre de inquilino Microsoft.com por su inquilino de Microsoft Entra.

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

Opciones de conexión

Para simplificar el proceso de obtención de credenciales, puede añadir uno de los siguientes indicadores de opción después de la cadena de conexión.

Ejemplo de una conexión mediante la CLI de Azure

Cualquiera de las opciones descritas en la tabla anterior puede añadirse después de una cadena de conexión. En el ejemplo siguiente se usa la opción de inicio de sesión de la CLI de Azure como método de autenticación:

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

Mostrar información de conexión

Para ver todas las conexiones existentes, ejecute el siguiente comando:

%kql --conn

Para consultar los detalles de una conexión específica, ejecute el siguiente comando:

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

Consultar y visualizar

Consulte datos mediante el operador “render” y visualice datos mediante la biblioteca de ploy.ly. Esta consulta y visualización proporciona una experiencia integrada que usa KQL de forma nativa.

Kqlmagic admite la mayoría de los gráficos, excepto timepivot, pivotchart y ladderchart. La representación se admite con todos los atributos, excepto kind, ysplit y accumulate.

Consultar y representar un gráfico circular

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

Consultar y representar un gráfico de tiempo

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

Personalizar los colores del gráfico

Si no le gusta la paleta de colores predeterminada, puede personalizar los gráficos con opciones de paleta. Aquí encontrará las paletas disponibles: Elige la paleta de colores para el resultado de tu gráfico de consulta kqlmagic

1. Para obtener una lista de paleta:

   %kql --palettes -popup_window
   

2. Seleccione la paleta de colores cool y vuelva a representar la consulta:

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

Parametrizar una consulta con Python

Kqlmagic permite un intercambio sencillo entre Kusto Query Language y Python. Para saber más: Parametrice su consulta kqlmagic con Python

Usar una variable de Python en una consulta KQL

Puede usar el valor de una variable de Python en una consulta para filtrar los datos:

statefilter = ["TEXAS", "KANSAS"]

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

Convertir resultados de la consulta en Pandas DataFrame

Puede acceder a los resultados de una consulta KQL en Pandas DataFrame. Accederá a los resultados de la última consulta ejecutada mediante la variable _kql_raw_result_ y podrá convertir fácilmente los resultados en Pandas DataFrame, como se indica a continuación:

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

Ejemplo

En muchos escenarios de análisis, puede que quiera crear blocs de notas reutilizables que contengan un gran número de consultas y pasar los resultados de una consulta a consultas posteriores. En el ejemplo siguiente, se usa la variable de Python statefilter para filtrar los datos.

1. Ejecute la consulta para ver los 10 estados principales con un máximo de DamageProperty:

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

2. Ejecute una consulta para extraer el estado principal y establecerlo en una variable de Python:

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

3. Ejecute una consulta con la instrucción let y la variable de Python:

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

4. Ejecute el comando de ayuda:

   %kql --help "help"
   

Cuadernos de ejemplo

• Introducción a kqlmagic para Azure Data Explorer
• Introducción a kqlmagic para Application Insights
• Introducción a kqlmagic para registros de Azure Monitor
• Parametrizar una consulta de kqlmagic con Python
• Seleccionar la paleta de colores para el resultado del gráfico de la consulta de kqlmagic

Contenido relacionado

• Aprenda Kusto Query Language (KQL)