Compartilhar via

Criar um perfil de dados usando a quality_monitors API (preterida)

Importante

A API descrita nesta página foi preterida. Consulte Criar um perfil de dados usando a API para obter informações sobre a API atual.

Esta página descreve como criar um perfil de dados no Databricks usando o SDK do Databricks e descreve os parâmetros usados em chamadas à API. Você também pode criar e gerenciar um perfil de dados usando a API REST.

Para obter informações de referência para essa API preterida, consulte a referência do SDK de criação de perfil de dados (preterida) e a referência da API REST (preterida).

Você pode criar um perfil em qualquer tabela Delta gerenciada ou externa registrada no Catálogo do Unity. Somente um único perfil pode ser criado no metastore do Unity Catalog de cada tabela.

Requisitos

A API de criação de perfil de dados é incorporada a databricks-sdk 0,28.0 e superior. Para usar a versão mais recente da API, use o seguinte comando no início do notebook para instalar o cliente Python:

%pip install "databricks-sdk>=0.28.0"

Para autenticar para usar o SDK do Databricks em seu ambiente, consulte Autenticação.

Tipos de perfil

Ao criar um perfil, você seleciona um dos seguintes tipos de perfil: TimeSeries, ou InferenceLogSnapshot. Esta seção descreve brevemente cada opção. Para obter detalhes, consulte a referência do SDK de criação de perfil de dados (preterida) ou a referência da API REST (preterida).

Observação

  • Quando você cria pela primeira vez um perfil de série temporal ou inferência, o Databricks analisa apenas os dados dos 30 dias anteriores à sua criação. Depois que o perfil é criado, todos os novos dados são processados.
  • Perfis definidos em exibições materializadas não dão suporte ao processamento incremental.

Dica

Para os perfis TimeSeries e Inference, é uma prática recomendada habilitar o feed de dados de alteração (CDF) em sua tabela. Quando o CDF está habilitado, somente os dados acrescentados recentemente são processados, em vez de reprocessar toda a tabela a cada atualização. Isso torna a execução mais eficiente e reduz os custos conforme você escala em várias tabelas de dados.

TimeSeries perfil

Um TimeSeries perfil compara distribuições de dados entre janelas de tempo. Para um TimeSeries perfil, você deve fornecer o seguinte:

  • Uma coluna de timestamp (timestamp_col). O tipo de dado da coluna de carimbo de data/hora deve ser TIMESTAMP, ou um tipo que possa ser convertido em carimbos de data/hora usando a to_timestampfunção PySpark.
  • O conjunto de granularities sobre o qual calcular as métricas. As granularidades disponíveis são "5 minutos", "30 minutos", "1 hora", "1 dia", "1 semana", "2 semanas", "3 semanas", "4 semanas", "1 mês", "1 ano".
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorTimeSeries

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  time_series=MonitorTimeSeries(timestamp_col=ts, granularities=["30 minutes"])
)

InferenceLog perfil

Um InferenceLog perfil é semelhante a um TimeSeries perfil, mas também inclui métricas de qualidade do modelo. InferenceLog os perfis usam os seguintes parâmetros:

Parâmetro Descrição
problem_type MonitorInferenceLogProblemType.PROBLEM_TYPE_CLASSIFICATION ou MonitorInferenceLogProblemType.PROBLEM_TYPE_REGRESSION
prediction_col Coluna que contém os valores previstos do modelo.
timestamp_col Coluna que contém o registro de data e hora da solicitação de inferência.
model_id_col Coluna que contém a ID do modelo usado para previsão.
granularities Determina como particionar os dados em janelas ao longo do tempo. Valores possíveis: "5 minutos", "30 minutos", "1 hora", "1 dia", "1 semana", "2 semanas", "3 semanas", "4 semanas", "1 mês", "1 ano".
label_col (Opcional) Coluna que contém a verdade básica para previsões de modelo. 
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorInferenceLog, MonitorInferenceLogProblemType

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  inference_log=MonitorInferenceLog(
        problem_type=MonitorInferenceLogProblemType.PROBLEM_TYPE_CLASSIFICATION,
        prediction_col="preds",
        timestamp_col="ts",
        granularities=["30 minutes", "1 day"],
        model_id_col="model_ver",
        label_col="label", # optional
  )
)

Para perfis InferenceLog, os segmentos são criados automaticamente com base nos valores distintos de model_id_col.

Snapshot perfil

Ao contrário de TimeSeries, um perfil Snapshot mostra como o conteúdo completo da tabela muda ao longo do tempo. As métricas são calculadas em todos os dados da tabela e refletem o estado da tabela sempre que o perfil é atualizado.

Observação

O tamanho máximo da tabela para um perfil de instantâneo é 4 TB. Em vez disso, para tabelas maiores, use perfis de série temporal.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorSnapshot

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  snapshot=MonitorSnapshot()
)

Atualizar e exibir resultados

Para ver o histórico de atualização, você deve usar o espaço de trabalho do Databricks em que a criação de perfil de dados foi habilitada.

Para atualizar tabelas de métricas, use run_refresh. Por exemplo:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.run_refresh(
    table_name=f"{catalog}.{schema}.{table_name}"
)

Quando você chama run_refresh de um notebook, as tabelas de métricas são criadas ou atualizadas. Esse cálculo é executado na computação sem servidor, não no cluster ao qual o notebook está anexado. Você pode continuar a executar comandos no notebook enquanto as estatísticas são atualizadas.

Para obter informações sobre as estatísticas armazenadas em tabelas de métricas, consulte Monitor de Tabelas de Métricas. As tabelas de métricas são tabelas do Catálogo do Unity. Você pode consultá-los em notebooks ou no gerenciador de consultas SQL e exibi-los no Gerenciador de Catálogos.

Para exibir o histórico de todas as atualizações associadas a um perfil, use list_refreshes.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.list_refreshes(
    table_name=f"{catalog}.{schema}.{table_name}"
)

Para obter o status de uma execução específica que foi enfileirada, em execução ou concluída, use get_refresh.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
run_info = w.quality_monitors.run_refresh(table_name=f"{catalog}.{schema}.{table_name}")

w.quality_monitors.get_refresh(
    table_name=f"{catalog}.{schema}.{table_name}",
    refresh_id = run_info.refresh_id
)

Para cancelar uma atualização enfileirada ou em execução, use cancel_refresh.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
run_info = w.quality_monitors.run_refresh(table_name=f"{catalog}.{schema}.{table_name}")

w.quality_monitors.cancel_refresh(
    table_name=f"{catalog}.{schema}.{table_name}",
    refresh_id=run_info.refresh_id
)

Exibir configurações de perfil

Você pode examinar as configurações de perfil usando a API get_monitor.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.get(f"{catalog}.{schema}.{table_name}")

Cronograma

Para configurar um perfil para ser executado de forma agendada, use o schedule parâmetro de create_monitor:

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorTimeSeries, MonitorCronSchedule

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  time_series=MonitorTimeSeries(timestamp_col=ts, granularities=["30 minutes"]),
  schedule=MonitorCronSchedule(
        quartz_cron_expression="0 0 12 * * ?", # schedules a refresh every day at 12 noon
        timezone_id="PST",
    )
)

Consulte expressões cron para obter mais informações.

Notificações

Para configurar notificações para um perfil, use o notifications parâmetro de create_monitor:

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorTimeSeries, MonitorNotifications, MonitorDestination

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  time_series=MonitorTimeSeries(timestamp_col=ts, granularities=["30 minutes"]),
  notifications=MonitorNotifications(
        # Notify the given email when a monitoring refresh fails or times out.
        on_failure=MonitorDestination(
            email_addresses=["your_email@domain.com"]
        )
    )
)

Há suporte para no máximo 5 endereços de email por tipo de evento (por exemplo, "on_failure").

Controlar o acesso a tabelas de métricas

As tabelas de métrica e o painel criados por um perfil pertencem ao usuário que criou o perfil. Você pode usar privilégios do Catálogo do Unity para controlar o acesso a tabelas de métricas. Para compartilhar dashboards em um workspace, use o botão Compartilhar no canto superior direito do painel.

Excluir um perfil

Para excluir um perfil:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.delete(table_name=f"{catalog}.{schema}.{table_name}")

Esse comando não exclui as tabelas de perfil e o painel criado pelo perfil. Você deve excluir esses ativos em uma etapa separada ou salvá-los em um local diferente.

Exemplos de notebooks

Os notebooks de exemplo a seguir ilustram como criar um perfil, atualizar o perfil e examinar as tabelas de métrica que ele cria.

Exemplo de bloco de anotações: perfil de série temporal

Este bloco de anotações ilustra como criar um TimeSeries perfil de tipo.

Notebook de exemplo do perfil TimeSeries

Obter laptop

Exemplo de bloco de anotações: perfil de inferência (regressão)

Este notebook ilustra como criar um InferenceLog perfil de tipo para um problema de regressão.

Notebook de exemplo de regressão de perfil de inferência

Obter laptop

Exemplo de bloco de anotações: perfil de inferência (classificação)

Este notebook ilustra como criar um InferenceLog perfil de tipo para um problema de classificação.

Notebook de exemplo de classificação de perfil de inferência

Obter laptop

Exemplo de notebook: perfil de instantâneo

Este bloco de anotações ilustra como criar um Snapshot perfil de tipo.

Notebook de exemplo de perfil de instantâneo

Obter laptop

  • Last updated on