使用線上資料表提供即時特徵服務

發行項
10/15/2024

重要

線上資料表在下列區域中為公開預覽版：westus、eastus、eastus2、northeurope、westeurope。在預覽期間，將資料內嵌到線上資料表會消耗 SQL Serverless DBU。線上資料表的最終定價將在將來的日期提供。

線上資料表是差異資料表的唯讀複本，以資料列導向格式儲存，針對線上存取進行最佳化。線上資料表是完全無伺服器資料表，可自動調整要求負載的輸送量容量，並提供對任何規模的資料的低延遲和高輸送量存取。線上資料表旨在與 Mosaic AI 模型服務、特徵服務以及擷取擴增產生 (RAG) 應用程式配合使用，用於快速查詢資料。

您也可以使用 Lakehouse 同盟在查詢中使用線上資料表。使用 Lakehouse 同盟時，您必須使用無伺服器 SQL 倉儲來存取線上資料表。僅支援讀取作業 (SELECT)。此功能僅用於互動或偵錯用途，不應用於生產或任務關鍵性工作負載。

使用 Databricks UI 建立線上資料表是單一步驟程序。只需從目錄總管中選取差異資料表，然後選取 [建立線上資料表]。您也可以使用 REST API 或 Databricks SDK 來建立和管理線上資料表。請參閱使用 API 處理線上資料表。

需求

必須為 Unity Catalog 啟用工作區。請遵循文件來建立 Unity Catalog 中繼存放區、在工作區中加以啟用及建立目錄。
必須在 Unity Catalog 中註冊模型，才能存取線上資料表。

使用 UI 處理線上資料表

本節說明如何建立和刪除線上資料表，以及如何檢查線上資料表的狀態和觸發更新。

使用 UI 建立線上資料表

您可以使用目錄總管建立線上資料表。如需有關必要權限的資訊，請參閱使用者權限。

若要建立線上資料表，來源差異資料表必須具有主索引鍵。如果要使用的差異資料表沒有主索引鍵，請遵循下列指示建立主索引鍵：使用 Unity Catalog 中的現有差異資料表作為特徵資料表。
在目錄總管中，瀏覽至要同步至線上資料表的來源資料表。從 [建立] 功能表中，選取 [線上資料表]。

使用對話方塊中的選取器設定線上資料表。

設定線上資料表對話方塊

名稱：用於 Unity Catalog 中線上資料表的名稱。

主索引鍵：要用作線上資料表中主索引鍵的來源資料表中的資料行。

時間序索引鍵：(選用)。要用作時間序索引鍵的來源資料表中的資料行。指定時，線上資料表僅包含每個主索引鍵具有最新時間序索引鍵值的資料列。

同步模式：指定同步管線如何更新線上資料表。選取 [快照]、[觸發] 或 [連續] 之一。

原則	描述
Snapshot	管線執行一次，以建立來源資料表的快照，並將其複製到線上資料表。對來源資料表的後續變更透過建立來源的新快照並建立新複本，自動反映在線上資料表中。線上資料表的內容會以不可部分完成方式更新。
觸發	管線執行一次，以在線上資料表中建立來源資料表的初始快照複本。與快照同步模式不同，重新整理線上資料表時，僅擷取至最後一次管線執行以來的變更，並將其套用於線上資料表。您可以根據排程手動觸發或自動觸發累加式重新整理。
連續	管線持續執行。對來源資料表的後續變更在即時串流模式下以累加方式套用於線上資料表。無需手動重新整理。

注意

若要支援 [觸發] 或 [連續] 同步模式，來源資料表必須啟用變更資料摘要。

完成時，按一下 [確認]。線上資料表頁面隨即出現。
新的線上資料表是在 [建立] 對話方塊中指定的目錄、結構描述和名稱下建立的。在目錄總管中，線上資料表以表示。

使用 UI 取得狀態並觸發更新

若要檢查線上資料表的狀態，請按一下 [目錄] 中的資料表名稱以將其開啟。線上資料表頁面隨即出現，並開啟 [概觀] 索引標籤。 [資料內嵌] 區段會顯示最新更新的狀態。若要觸發更新，請按一下 [立即同步]。 [資料內嵌] 區段也包含更新資料表之 [差異即時資料表] 管線的連結。

目錄中線上資料表頁面的檢視

使用 UI 刪除線上資料表

從線上資料表頁面，從 kebab 功能表中選取 [刪除]。

使用 API 處理線上資料表

您也可以使用 Databricks SDK 或 REST API 來建立和管理線上資料表。

如需參考資訊，請參閱適用於 Python 的 Databricks SDK 或 REST API 的參考文件。

需求

Databricks SDK 0.20 版或更新版本。

使用 API 建立線上資料表

Databricks SDK - Python

from pprint import pprint
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import *

w = WorkspaceClient(host='https://xxx.databricks.com', token='xxx')

# Create an online table
spec = OnlineTableSpec(
  primary_key_columns=["pk_col"],
  source_table_full_name="main.default.source_table",
  run_triggered=OnlineTableSpecTriggeredSchedulingPolicy.from_dict({'triggered': 'true'})
)

w.online_tables.create(name='main.default.my_online_table', spec=spec)

REST API

curl --request POST "https://xxx.databricks.com/api/2.0/online-tables" \
--header "Authorization: Bearer xxx" \
--data '{
    "name": "main.default.my_online_table",
    "spec": {
        "run_triggered": {},
        "source_table_full_name": "main.default.source_table",
        "primary_key_columns": ["a"]
    }
  }'

線上資料表會在建立後自動開始同步。

使用 API 取得狀態和觸發重新整理

您可以遵循下列範例來檢視線上資料表的狀態和規格。如果您的線上資料表不是連續的，而且您想要觸發其資料的手動重新整理，您可以使用管線 API 來執行此動作。

使用與線上資料表規格中的線上資料表關聯的管線識別碼，並在管線上啟動新的更新以觸發重新整理。這相當於在目錄總管的線上資料表 UI 中按一下 [立即同步]。

Databricks SDK - Python

pprint(w.online_tables.get('main.default.my_online_table'))

# Sample response
OnlineTable(name='main.default.my_online_table',
    spec=OnlineTableSpec(perform_full_copy=None,
        pipeline_id='some-pipeline-id',
        primary_key_columns=['pk_col'],
        run_continuously=None,
        run_triggered={},
        source_table_full_name='main.default.source_table',
        timeseries_key=None),
    status=OnlineTableStatus(continuous_update_status=None,
        detailed_state=OnlineTableState.PROVISIONING,
        failed_status=None,
        message='Online Table creation is '
            'pending. Check latest status in '
            'Delta Live Tables: '
            'https://xxx.databricks.com/pipelines/some-pipeline-id',
        provisioning_status=None,
        triggered_update_status=None))

# Trigger an online table refresh by calling the pipeline API. To discard all existing data
# in the online table before refreshing, set "full_refresh" to "True". This is useful if your
# online table sync is stuck due to, for example, the source table being deleted and recreated
# with the same name while the sync was running.
w.pipelines.start_update(pipeline_id='some-pipeline-id', full_refresh=True)

REST API

curl --request GET \
  "https://xxx.databricks.com/api/2.0/online-tables/main.default.my_online_table" \
  --header "Authorization: Bearer xxx"

# Sample response
{
  "name": "main.default.my_online_table",
  "spec": {
    "run_triggered": {},
    "source_table_full_name": "main.default.source_table",
    "primary_key_columns": ["pk_col"],
    "pipeline_id": "some-pipeline-id"
  },
  "status": {
    "detailed_state": "PROVISIONING",
    "message": "Online Table creation is pending. Check latest status in Delta Live Tables: https://xxx.databricks.com#joblist/pipelines/some-pipeline-id"
  }
}

# Trigger an online table refresh by calling the pipeline API. To discard all existing data
# in the online table before refreshing, set "full_refresh" to "True". This is useful if your
# online table sync is stuck due to, for example, the source table being deleted and recreated
# with the same name while the sync was running.
curl --request POST "https://xxx.databricks.com/api/2.0/pipelines/some-pipeline-id/updates" \
  --header "Authorization: Bearer xxx" \
  --data '{
    "full_refresh": true
  }'

使用 API 刪除線上資料表

Databricks SDK - Python

w.online_tables.delete('main.default.my_online_table')

REST API

curl --request DELETE \
  "https://xxx.databricks.com/api/2.0/online-tables/main.default.my_online_table" \
  --header "Authorization: Bearer xxx"

刪除線上資料表會停止任何進行中的資料同步並釋放其所有資源。

使用特徵服務端點提供線上資料表資料

對於在 Databricks 外部裝載的模型和應用程式，您可以建立一個特徵服務端點來提供線上資料表中的特徵。端點使用 REST API 以低延遲提供特徵。

建立特徵規格。

建立特徵規格時，您可以指定來源差異資料表。這允許同時在離線和線上案例中使用特徵規格。對於連線查詢，服務端點會自動使用線上資料表來執行低延遲特徵查詢。

來源差異資料表和線上資料表必須使用相同的主索引鍵。

您可以在目錄總管的 [函數] 索引標籤中檢視特徵規格。
```
from databricks.feature_engineering import FeatureEngineeringClient, FeatureLookup

fe = FeatureEngineeringClient()
fe.create_feature_spec(
  name="catalog.default.user_preferences_spec",
  features=[
    FeatureLookup(
      table_name="user_preferences",
      lookup_key="user_id"
    )
  ]
)
```

建立特徵服務端點。

此步驟假設您已建立一個名為 user_preferences_online_table 的線上資料表，用於同步差異資料表 user_preferences 中的資料。使用特徵規格來建立特徵服務端點。端點使用關聯的線上資料表透過 REST API 提供資料。

注意

執行此作業的使用者必須同時是離線資料表和線上資料表的擁有者。

Databricks SDK - Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import EndpointCoreConfigInput, ServedEntityInput

workspace = WorkspaceClient()

# Create endpoint
endpoint_name = "fse-location"

workspace.serving_endpoints.create_and_wait(
  name=endpoint_name,
  config=EndpointCoreConfigInput(
    served_entities=[
      ServedEntityInput(
        entity_name=feature_spec_name,
        scale_to_zero_enabled=True,
        workload_size="Small"
      )
    ]
  )
)

Python API

from databricks.feature_engineering.entities.feature_serving_endpoint import (
  ServedEntity,
  EndpointCoreConfig,
)

fe.create_feature_serving_endpoint(
  name="user-preferences",
  config=EndpointCoreConfig(
    served_entities=ServedEntity(
      feature_spec_name="catalog.default.user_preferences_spec",
      workload_size="Small",
      scale_to_zero_enabled=True
    )
  )
)

從特徵服務端點取得資料。

若要存取 API 端點，請將 HTTP GET 要求傳送至端點 URL。此範例顯示如何使用 Python API 執行此作業。如需其他語言和工具，請參閱特徵服務。

# Set up credentials
export DATABRICKS_TOKEN=...

url = "https://{workspace_url}/serving-endpoints/user-preferences/invocations"

headers = {'Authorization': f'Bearer {DATABRICKS_TOKEN}', 'Content-Type': 'application/json'}

data = {
  "dataframe_records": [{"user_id": user_id}]
}
data_json = json.dumps(data, allow_nan=True)

response = requests.request(method='POST', headers=headers, url=url, data=data_json)
if response.status_code != 200:
  raise Exception(f'Request failed with status {response.status_code}, {response.text}')

print(response.json()['outputs'][0]['hotel_preference'])

將線上資料表與 RAG 應用程式搭配使用

RAG 應用程式是線上資料表的常見使用案例。您可以為 RAG 應用程式所需的結構化資料建立線上資料表，並將它託管在特徵服務端點上。 RAG 應用程式會使用特徵服務端點來查詢線上資料表的相關資料。

常見步驟如下：

建立特徵服務端點。
使用 LangChain 或任何使用端點查詢相關資料的類似套件建立一個工具。
使用 LangChain 代理程式或類似代理程式中的工具來擷取相關資料。
建立模型服務端點來託管應用程式。

如需逐步指示和範例筆記本，請參閱特徵工程範例：結構化 RAG 應用程式。

筆記本範例

下列筆記本說明如何將特徵發佈至線上資料表，以進行即時服務和自動化特徵查詢。

線上資料表示範筆記本

取得筆記本

將線上資料表與 Mosaic AI 模型服務搭配使用

您可以使用線上資料表查詢 Mosaic AI 模型服務的特徵。將特徵資料表同步至線上資料表時，使用該特徵資料表中的特徵訓練的模型在推斷期間會自動查詢線上資料表中的特徵值。不需要進行其他組態設定。

使用 FeatureLookup 訓練模型。

對於模型訓練，請使用模型訓練集中離線特徵資料表中的特徵，如下列範例所示：

training_set = fe.create_training_set(
  df=id_rt_feature_labels,
  label='quality',
  feature_lookups=[
      FeatureLookup(
          table_name="user_preferences",
          lookup_key="user_id"
      )
  ],
  exclude_columns=['user_id'],
)

使用 Mosaic AI 模型服務為模型提供服務。模型會自動查詢線上資料表中的特徵。如需詳細資料，請參閱使用 Databricks 模型服務自動查詢特徵。

使用者權限

您必須具有下列權限才能建立線上資料表：

來源資料表的 SELECT 權限。
目的地目錄的 USE_CATALOG 權限。
目的地結構描述的 USE_SCHEMA 和 CREATE_TABLE 權限。

若要管理線上資料表的資料同步管線，您必須是線上資料表的擁有者，或者被授與線上資料表的 REFRESH 權限。沒有目錄 USE_CATALOG 和 USE_SCHEMA 權限的使用者不會在目錄總管中看到線上資料表。

Unity Catalog 中繼存放區必須具有權限模型 1.0 版。

端點權限模型

為特徵服務或模型服務端點自動建立唯一的服務主體，該端點具有從線上資料表查詢資料所需的有限權限。此服務主體允許端點獨立於建立資源的使用者存取資料，並確保當建立者離開工作區時端點可以繼續運作。

此服務主體的存留期是端點的存留期。稽核記錄可能指示系統為向此服務主體授與所需權限的 Unity Catalog 目錄擁有者產生的記錄。

限制

每個來源資料表僅支援一個線上資料表。
線上資料表及其來源資料表最多可以具有 1000 個資料行。
資料類型 ARRAY、MAP 或 STRUCT 的資料行不能用作線上資料表中的主索引鍵。
如果資料行用作線上資料表中的主索引鍵，則忽略資料行包含 null 值的來源資料表中的所有資料列。
不支援外部、系統和內部資料表作為來源資料表。
未啟用差異變更資料摘要的來源資料表僅支援快照同步模式。
差異共用資料表僅在快照同步模式下受支援。
線上資料表的目錄、結構描述和資料表名稱只能包含英數字元和底線，不得以數字開頭。不允許使用虛線 (-)。
字串類型的資料行長度限制為 64KB。
資料行名稱的長度限制為 64 個字元。
資料列大小上限為 2MB。
在公開預覽期間，Unity Catalog 中繼存放區中所有線上資料表的合併大小是 2TB 未壓縮的使用者資料。
每秒查詢數 (QPS) 上限為 12,000。若要提高限制，請連絡 Databricks 客戶團隊。

疑難排解

我看不到 [建立線上資料表] 選項

原因通常是嘗試從 (來源資料表) 同步的資料表不是受支援的類型。確定來源資料表的安全性實體種類 (顯示在目錄總管 [詳細資料] 索引標籤中) 是下列支援的選項之一：

TABLE_EXTERNAL
TABLE_DELTA
TABLE_DELTA_EXTERNAL
TABLE_DELTASHARING
TABLE_DELTASHARING_MUTABLE
TABLE_STREAMING_LIVE_TABLE
TABLE_STANDARD
TABLE_FEATURE_STORE
TABLE_FEATURE_STORE_EXTERNAL
TABLE_VIEW
TABLE_VIEW_DELTASHARING
TABLE_MATERIALIZED_VIEW

建立線上資料表時，我無法選取 [觸發] 或 [連續] 同步模式

如果來源資料表未啟用差異變更資料摘要，或者它是檢視或具體化檢視，則會發生此情況。若要使用 [累加] 同步模式，請對來源資料表啟用變更資料摘要或使用非檢視資料表。

線上資料表更新失敗或狀態顯示為離線

若要開始對此錯誤進行疑難排解，請按一下目錄總管中線上資料表的 [概觀] 索引標籤中顯示的管線識別碼。

線上資料表管線失敗

在顯示的管線 UI 頁面上，按一下顯示「無法解析流程 ‘__online_table’」的項目。

線上資料表管線錯誤訊息

快顯視窗隨即出現，在 [錯誤詳細資料] 區段中提供了詳細資料。

線上資料表錯誤詳細資料

錯誤的常見原因包括如下：

在線上資料表同步時，來源資料表被刪除，或被刪除並使用相同的名稱重新建立。這在連續線上資料表中特別常見，因為它們會不斷同步。
由於防火牆設定，無法透過無伺服器計算存取來源資料表。在這種情況下，[錯誤詳細資料] 區段可能會顯示錯誤訊息「無法啟動叢集 xxx 上的 DLT 服務...」。
線上資料表的彙總大小超過 1 TiB (未壓縮的大小) 的中繼存放區範圍限制。 1 TiB 限制是指以資料列導向格式擴展差異資料表後未壓縮的大小。使用資料列格式的資料表的大小會明顯大於目錄總管中顯示的差異資料表的大小，後者是指資料列導向格式的資料表的壓縮大小。視資料表的內容而定，此差異可能高達 100 倍。

若要估計差異資料表的未壓縮、資料列擴展的大小，請使用無伺服器 SQL 倉儲中的下列查詢。此查詢會傳回估計的擴展資料表大小 (以位元組為單位)。成功執行此查詢也會確認無伺服器計算可以存取來源資料表。
```
SELECT sum(length(to_csv(struct(*)))) FROM `source_table`;
```

共用方式為

使用線上資料表提供即時特徵服務

需求

使用 UI 處理線上資料表

使用 UI 建立線上資料表

使用 UI 取得狀態並觸發更新

使用 UI 刪除線上資料表

使用 API 處理線上資料表

需求

使用 API 建立線上資料表

Databricks SDK - Python

REST API

使用 API 取得狀態和觸發重新整理

Databricks SDK - Python

REST API

使用 API 刪除線上資料表

Databricks SDK - Python

REST API

使用特徵服務端點提供線上資料表資料

Databricks SDK - Python

Python API

將線上資料表與 RAG 應用程式搭配使用

筆記本範例

線上資料表示範筆記本

將線上資料表與 Mosaic AI 模型服務搭配使用

使用者權限

端點權限模型

限制

疑難排解

我看不到 [建立線上資料表] 選項

建立線上資料表時，我無法選取 [觸發] 或 [連續] 同步模式

線上資料表更新失敗或狀態顯示為離線

意見反應

其他資源