使用 API 创建数据剖析

本页介绍如何使用 Databricks SDK 在 Databricks 中创建数据配置文件，并描述 API 调用中使用的所有参数。 还可以使用 REST API 创建和管理数据配置文件。 有关参考信息，请参阅 数据分析 SDK 参考 和 REST API 参考。

您可以在注册于 Unity Catalog 的任何托管或外部 Delta 表上创建一个配置文件。 在 Unity Catalog 元存储中，对于任何表只能创建一个概况。

要求

数据分析 API 内置于 databricks-sdk 0.28.0 及更高版本中。 若要使用最新版本的 API，请使用笔记本开头的以下命令安装 Python 客户端：

%pip install "databricks-sdk>=0.28.0"

若要进行身份验证以在环境中使用 Databricks SDK，请参阅 “身份验证”。

配置文件类型

创建配置文件时，请选择以下配置文件类型之一：TimeSeries、InferenceLog 或 Snapshot。 本部分简要介绍了每个选项。 有关详细信息，请参阅 API 参考 或 REST API 参考。

TimeSeries 轮廓

TimeSeries配置文件比较跨时间窗口的数据分布。 对于TimeSeries配置文件，必须提供以下内容：

• 时间戳列 （timestamp_col）。 时间戳列数据类型必须是TIMESTAMP或可以使用 to_timestamp转换为时间戳的类型。
• 要计算指标的 granularities 集合。 可用的粒度为“5 分钟”、“30 分钟”、“1 小时”、“1 天”、“1 周”、“2 周”、“3 周”、“4 周”、“1 个月”、“1 年”。

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 轮廓

配置文件 InferenceLog 类似于配置文件 TimeSeries，但也包括模型质量指标。 对于InferenceLog配置文件，需要以下参数：

还有一个可选参数：

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

对于 InferenceLog 配置文件，会根据model_id_col的不同值自动创建切片。

Snapshot 轮廓

与TimeSeries不同，Snapshot描述了表格的完整内容如何随时间变化。 指标针对表中的所有数据进行计算，并在每次刷新概况时反映表状态。

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

刷新和查看结果

若要查看刷新历史记录，必须使用启用了数据分析的 Databricks 工作区。

若要刷新指标表，请使用 run_refresh。 例如：

from databricks.sdk import WorkspaceClient

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

从笔记本调用 run_refresh 时，会创建或更新指标表。 此计算在无服务器计算上运行，而不是在笔记本附加到的群集上运行。 更新统计信息时，可以继续在笔记本中运行命令。

有关存储在指标表中的统计信息的信息，请参阅 监视指标表。指标表是 Unity 目录表。 可以在笔记本或 SQL 查询资源管理器中查询它们，并在目录资源管理器中查看它们。

若要显示与配置文件关联的所有刷新的历史记录，请使用 list_refreshes。

from databricks.sdk import WorkspaceClient

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

若要获取已排队、正在运行或已完成的特定运行的状态，请使用 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
)

若要取消已排队或正在执行的刷新，请使用 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
)

查看个人资料设置

可以使用 get_monitor API 查看用户资料设置。

from databricks.sdk import WorkspaceClient

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

时间表

若要设置配置文件以在指定时间运行，请使用 schedule 的 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",
    )
)

有关详细信息，请参阅 cron 表达式 。

Notifications

若要为配置文件设置通知，请使用 notifications 参数 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"]
        )
    )
)

每个事件类型最多支持 5 个电子邮件地址（例如，“on_failure”）。

控制对指标表的访问

配置文件创建的指标表和仪表板由创建配置文件的用户拥有。 可以使用 Unity 目录特权来控制对指标表的访问。 若要在工作区中共享仪表板，请使用仪表板右上角的 “共享 ”按钮。

删除配置文件

删除用户配置：

from databricks.sdk import WorkspaceClient

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

此命令不会删除个人资料表和由个人资料创建的仪表板。 必须在单独的步骤中删除这些资产，也可以将它们保存在其他位置。

示例笔记本

以下示例笔记本演示了如何创建配置文件、刷新配置文件以及检查所创建的指标表。

笔记本示例：时序特征

此笔记本演示如何创建 TimeSeries 类型配置文件。

TimeSeries 概述示例笔记本

获取笔记本

笔记本示例：推理分析（回归）

此笔记本演示如何为回归问题创建 InferenceLog 类型配置文件。

推理配置回归示例笔记本文件

获取笔记本

笔记本示例：推理概况（分类）

此笔记本演示如何为分类问题创建 InferenceLog 类型配置文件。

推理配置文件分类示例笔记本

获取笔记本

笔记本示例：快照配置文件

此笔记本演示如何创建 Snapshot 类型配置文件。

快照概要示例笔记本

获取笔记本