使用在線數據表提供即時功能

發行項
05/01/2024

重要

在線數據表處於公開預覽狀態。在預覽期間，將數據內嵌至在線數據表會取用SQL Serverless DBU。在線數據表的最終定價將在未來的日期提供。

線上資料表預覽可在下列區域中使用：westus、、eastuseastus2、northeurope、 westeurope。

在線數據表是 Delta 數據表的唯讀複本，以針對在線存取優化的數據列導向格式儲存。在線數據表是完全無伺服器數據表，可透過要求負載自動調整輸送量容量，並提供低延遲和高輸送量存取任何規模的數據。在線數據表的設計目的是要與 Databricks 模型服務、功能服務及擷取增強式產生（RAG）應用程式搭配使用，以用於快速數據查閱。

您也可以使用 Lakehouse 同盟在查詢中使用在線數據表。使用 Lakehouse 同盟時，您必須使用無伺服器 SQL 倉儲來存取在線數據表。僅支援讀取作業（SELECT）。這項功能僅供互動式或偵錯之用，不應用於生產或任務關鍵性工作負載。

使用 Databricks UI 建立在線數據表是一個步驟的程式。只要在目錄總管中選取 Delta 數據表，然後選取 [ 建立在線數據表]。您也可以使用 REST API 或 Databricks SDK 來建立和管理在線數據表。請參閱使用 API 使用線上數據表。

需求

必須啟用 Unity 目錄的工作區。請遵循檔來建立 Unity 目錄中繼存放區、在工作區中啟用它，以及建立目錄。
模型必須在 Unity 目錄中註冊，才能存取在線數據表。

使用UI使用線上數據表

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

使用UI建立線上數據表

您可以使用目錄總管建立線上數據表。如需必要許可權的相關信息，請參閱用戶許可權。

若要建立在線數據表，來源 Delta 數據表必須有主鍵。如果您想要使用的 Delta 資料表沒有主鍵，請依照下列指示建立一個數據表：使用 Unity 目錄中的現有 Delta 資料表做為功能數據表。
在 [目錄總管] 中，流覽至您要同步至在線數據表的源數據表。從 [ 建立] 功能表中，選取 [ 在線] 數據表。

使用對話框中的選取器來設定在線數據表。

設定在線數據表對話框

名稱：用於 Unity 目錄中在線數據表的名稱。

主鍵：源數據表中的數據行（s）在在線數據表中做為主鍵。

Timeseries 機碼:(選擇性）。源數據表中要當做時間順序索引鍵使用的數據行。指定時，在線數據表只會包含每個主鍵具有最新時間索引鍵值的數據列。

同步模式：指定同步處理管線如何更新在線數據表。選取其中一個快照集、觸發或連續。

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

注意

若要支援觸發或連續同步模式，源數據表必須啟用變更數據摘要。

完成時，按兩下 [ 確認]。在線數據表頁面隨即出現。
新的在線數據表會在建立對話框中指定的目錄、架構和名稱下建立。在目錄總管中，在線數據表會以表示。

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

若要檢查在線數據表的狀態，請按兩下 Catalog 中資料表的名稱以開啟它。在線數據表頁面隨即出現，並開啟 [ 概觀 ] 索引標籤。 [ 數據內嵌 ] 區段會顯示最新更新的狀態。若要觸發更新，請按兩下 [ 立即同步處理]。 [數據內嵌] 區段也包含更新數據表之 Delta Live Tables 管線的連結。

目錄中在線數據表頁面的檢視

使用UI刪除線上資料表

從在線數據表頁面，從 Kebab 功能表中選取 [刪除]。

使用 API 使用線上數據表

您也可以使用 Databricks SDK 或 REST API 來建立和管理在線數據表。

如需參考資訊，請參閱 Databricks SDK for Python 或 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 以低延遲提供功能。

建立功能規格。

當您建立功能規格時，您可以指定來源 Delta 資料表。這可讓功能規格在離線案例中使用。針對在線查閱，服務端點會自動使用在線數據表來執行低延遲功能查閱。

來源 Delta 數據表和在線數據表必須使用相同的主鍵。

功能規格可以在目錄總管的 [函式] 索引標籤中檢視。
```
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 的在線數據表，以同步處理 Delta 數據表 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

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 應用程式會使用提供端點的功能來查閱在線數據表的相關數據。

一般步驟如下：

建立提供端點的功能。
建立使用端點來查閱相關數據的 LangChainTool。
使用 LangChain 代理程式中的工具來擷取相關數據。
建立提供端點的模型來裝載 LangChain 應用程式。

如需逐步指示，請參閱下列範例筆記本。

筆記本範例

下列筆記本說明如何將功能發佈至在線數據表，以進行即時服務和自動化功能查閱。

在線數據表示范筆記本

取得筆記本

下列筆記本說明如何使用 Databricks 在線數據表和功能提供端點，以擷取增強世代（RAG）應用程式。

使用RAG應用程式示範筆記本的在線數據表

取得筆記本

搭配 Databricks 模型服務使用在線數據表

您可以使用線上數據表來查閱 Databricks 模型服務的功能。當您將功能數據表同步至在線數據表時，使用該功能數據表的功能定型模型會在推斷期間自動從在線數據表查詢特徵值。不需要進行其他組態設定。

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'],
)

使用 Databricks 模型服務來提供模型。模型會自動從在線數據表查閱功能。如需詳細資訊，請參閱在 Databricks 上使用 MLflow 模型的自動功能查閱。

用戶權力

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

SELECT 源數據表的許可權。
USE_CATALOG 目的地目錄的許可權。
USE_SCHEMA 目的地架構的和 CREATE_TABLE 許可權。

若要管理在線數據表的數據同步處理管線，您必須是在線數據表的擁有者，或被授與在線數據表的 REFRESH 許可權。沒有目錄USE_CATALOG和USE_SCHEMA許可權的使用者將不會在目錄總管中看到在線數據表。

Unity 目錄中繼存放區必須具有許可權模型 1.0 版。

端點許可權模型

系統會自動為功能服務或模型服務端點建立唯一的系統服務主體，並具有查詢數據和執行函式所需的有限許可權。此服務主體可讓端點與建立資源的用戶獨立存取數據和函式資源，並確保當建立者離開工作區時，端點可以繼續運作。

此系統服務主體的存留期是端點的存留期。稽核記錄可能表示系統為 Unity 目錄目錄的擁有者產生記錄，並將必要的許可權授與此系統服務主體。

限制

每個源數據表只支援一個在線數據表。
在線數據表及其源數據表最多可以有1000個數據行。
數據類型ARRAY、MAP或 STRUCT的數據行不能當做在線數據表的主鍵使用。
如果使用數據行做為在線數據表的主鍵，則會忽略數據行包含 Null 值之源數據表中的所有數據列。
不支援外部、系統和內部數據表做為源數據表。
未啟用差異變更數據摘要的源數據表僅 支援快照 集同步模式。
只有快照集同步模式才支援差異共享數據表。
在線數據表的目錄、架構和數據表名稱只能包含英數位元和底線，不得以數字開頭。不允許破折號（-）。
String 類型的數據行長度限制為 64KB。
數據行名稱的長度限制為64個字元。
數據列的大小上限為 2MB。
在閘道公開預覽期間，在線數據表的大小上限是 200GB 未壓縮的用戶數據。
在閘道公開預覽期間，Unity 目錄中繼存放區中所有在線數據表的組合大小是 1TB 未壓縮的用戶數據。
每秒查詢數上限（QPS）為 200。此限制可以增加到 25,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 限制是指以數據列導向格式擴充 Delta 數據表之後未壓縮的大小。數據列格式的數據表大小可以明顯大於目錄總管中顯示的 Delta 資料表大小，這是指以數據行導向格式壓縮的數據表大小。視數據表的內容而定，差異可能高達 100x。

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

Share via

使用在線數據表提供即時功能

需求

使用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應用程式使用在線數據表

筆記本範例

在線數據表示范筆記本

使用RAG應用程式示範筆記本的在線數據表

搭配 Databricks 模型服務使用在線數據表

用戶權力

端點許可權模型

限制

疑難排解

「建立在線數據表」不會出現在目錄總管中。

在建立在線數據表時，我無法選取「已觸發」或「連續」同步模式。

在線數據表更新失敗或狀態顯示為離線

意見反應

意見反應

其他資源