Crie um perfil de dados usando a API.

Esta página descreve como criar um perfil de dados no Databricks usando o SDK do Databricks e descreve todos os parâmetros usados nas chamadas da API. Você também pode criar e gerenciar perfis de dados usando a API REST . Para informações de referência, consulte a referência SDK do perfil de dados e a referência API REST.

Você pode criar um perfil em qualquer tabela Delta administrativa ou externa registrada no Unity Catalog. Apenas um único perfil pode ser criado em um metastore Unity Catalog para qualquer tabela.

Requisitos

A API de perfil de dados está integrada em databricks-sdk 0.28.0 e acima. Para usar a versão mais recente da API, utilize o seguinte comando no início do seu Notebook para instalar o cliente Python :

Python

%pip install "databricks-sdk>=0.28.0"

Para autenticar e 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, InferenceLog ou Snapshot. Esta seção descreve brevemente cada opção. Para obter detalhes, consulte a referência da API ou a referência da API REST.

nota

• Ao criar uma série temporal ou um perfil de inferência pela primeira vez, o Databricks analisa apenas os dados dos 30 dias anteriores à sua criação. Após a criação do perfil, todos os novos dados são processados.
• Os perfis definidos na visão materializada não suportam processamento incremental.

dica

Para perfis TimeSeries e Inference , é uma boa prática habilitar o feed de dados de alteração (CDF) em sua tabela. Quando o CDF está ativado, apenas os dados adicionados recentemente são processados, em vez de reprocessar a tabela inteira a cada refresh. Isso torna a execução mais eficiente e reduz os custos à medida que você escala para várias tabelas.

PerfilTimeSeries

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

• Uma coluna de carimbo de data/hora (timestamp_col). O tipo de dados da coluna de carimbo de data/hora deve ser TIMESTAMP ou um tipo que possa ser convertido em carimbos de data/hora usando a função to_timestamp do PySpark.
• O conjunto 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”.

Python

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"])
)

PerfilInferenceLog

Um perfil InferenceLog é semelhante a um perfil TimeSeries , mas também inclui métricas de qualidade do modelo. Para um perfil InferenceLog , os seguintes parâmetros são necessários:

Parâmetro	Descrição
problem_type	MonitorInferenceLogProblemType.PROBLEM_TYPE_CLASSIFICATION ou MonitorInferenceLogProblemType.PROBLEM_TYPE_REGRESSION
prediction_col	Coluna contendo os valores previstos pelo modelo.
timestamp_col	Coluna contendo o registro de data e hora da solicitação de inferência.
model_id_col	Coluna contendo o ID do modelo usado para a 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”.

Existe também um parâmetro opcional:

Parâmetro opcional	Descrição
label_col	Coluna contendo os valores reais das previsões do modelo.

Python

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, fatias são criadas automaticamente com base nos valores distintos de model_id_col.

PerfilSnapshot

Em contraste com TimeSeries, um Snapshot descreve como todo o conteúdo da tabela muda ao longo do tempo. As métricas são calculadas com base em todos os dados da tabela e refletem o estado da tabela a cada vez que o perfil é atualizado.

Python

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()
)

Atualize e view os resultados

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

Python

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 métricas são criadas ou atualizadas. Essa execução de cálculo ocorre em compute serverless , não no cluster ao qual o Notebook está conectado. Você pode continuar a executar o comando no Notebook enquanto as estatísticas são atualizadas.

Para obter informações sobre as estatísticas que estão armazenadas nas tabelas de métricas, consulte Monitorar tabelas de métricas. As tabelas de métricas são tabelas Unity Catalog . Você pode consultá-los no Notebook ou no explorador de consultas SQL e view -los no Explorador de Catálogo.

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

Python

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.

Python

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 refresh que está na fila ou em execução, use cancel_refresh.

Python

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
)

visualizar configurações de perfil

Você pode revisar as configurações do perfil usando a API get_monitor.

Python

from databricks.sdk import WorkspaceClient

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

programar

Para configurar um perfil para execução agendada, use o parâmetro schedule de create_monitor:

Python

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",
    )
)

Veja expressões cron para mais informações.

Notificações

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

Python

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"]
        )
    )
)

É possível utilizar no máximo 5 endereços email por tipo de evento (por exemplo, “on_failure”).

Controlar o acesso às tabelas de métricas

As tabelas de métricas e o painel de controle criados por um perfil pertencem ao usuário que criou o perfil. Você pode usar os privilégios Unity Catalog para controlar o acesso às tabelas de instrumentos. Para compartilhar painéis dentro de um workspace, use o botão Compartilhar no canto superior direito do painel.

Excluir um perfil

Para excluir um perfil:

Python

from databricks.sdk import WorkspaceClient

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

Este comando não exclui as tabelas de perfil e o painel de controle criados pelo perfil. Você deve excluir os itens ativos em uma pasta separada ou salvá-los em um local diferente.

Exemplo de caderno

O seguinte exemplo de Notebook ilustra como criar um perfil, refresh o perfil e examinar as tabelas de métricas que ele cria.

ExemploNotebook : Perfil de série temporal

Este Notebook ilustra como criar um perfil do tipo TimeSeries .

Exemplo de perfil de série temporal em formato de notebook.

Open notebook in new tab

ExemploNotebook : Perfil de inferência (regressão)

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

Exemplo de regressão de perfil de inferência em formato de notebook.

Open notebook in new tab

ExemploNotebook : Perfil de inferência (classificação)

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

Exemplo de classificação de perfil de inferência em formato de notebook

Open notebook in new tab

ExemploNotebook : Perfil Snapshot

Este Notebook ilustra como criar um perfil do tipo Snapshot .

Exemplo de perfil Snapshot Notebook

Open notebook in new tab