共用方式為

設定及使用適用於 Azure Cosmos DB 的 Azure Synapse Link

  • 適用於: ✅ NoSQL

重要事項

Synapse Link for Cosmos DB 已不再支援新專案。 不要使用這個功能。

請為 Microsoft Fabric 使用 Azure Cosmos DB 鏡像，該 Fabric 現在已是正式發行版。 鏡像提供相同的零 ETL 優勢，且與 Microsoft Fabric 完全整合。 想了解更多，請參閱 Cosmos DB 鏡像概覽。

適用於 Azure Cosmos DB 的 Azure Synapse Link 是雲端原生混合式交易與分析處理 (HTAP) 功能，其可供對 Azure Cosmos DB 中的操作資料執行近乎即時分析。 Synapse Link 會在 Azure Cosmos DB 與 Azure Synapse Analytics 之間建立緊密順暢的整合。

Azure Synapse Link 可用於 Azure Cosmos DB SQL API，或可用於適用於 Mongo DB 帳戶的 Azure Cosmos DB API。 且其為 Gremlin API 的預覽版狀態，並透過 CLI 命令啟用。 使用下列步驟，利用適用於 Azure Cosmos DB 的 Azure Synapse Link 來執行分析查詢：

您也可以查看訓練模組，以了解如何設定適用於 Azure Cosmos DB 的 Azure Synapse Link。

使用 Synapse Link 的第一個步驟是為您的 Azure Cosmos DB 資料庫帳戶啟用它。

附註

如果您想要將客戶自控金鑰與 Azure Synapse Link 一起搭配使用，您必須先在 Azure Key Vault 存取原則中設定您帳戶的受控識別，然後才能啟用您帳戶的 Synapse Link 功能。 如需詳細資訊，請參閱如何使用 Azure Cosmos DB 帳戶的受控識別來設定客戶自控金鑰一文中的內容。

附註

如果您想要使用適用於 NoSQL 帳戶的 API 的完整精確度結構描述，就無法使用 Azure 入口網站來啟用 Synapse Link。 當您在帳戶中啟用 Synapse Link 後，就無法變更此選項；您必須使用 Azure CLI 或 PowerShell 才能設定此選項。 如需詳細資訊，請參閱分析存放區結構描述表示法文件。

附註

您需要參與者角色，才能在帳戶等級啟用 Synapse Link。 而且您至少需要操作員，才能在容器或集合中啟用 Synapse Link。

Azure 入口網站

  1. 登入 Azure 入口網站。

  2. 建立新的 Azure 帳戶，或選取現有的 Azure Cosmos DB 帳戶。

  3. 瀏覽至您的 Azure Cosmos DB 帳戶，然後開啟左側窗格中整合底下的 Azure Synapse Link。

  4. 選取 [啟用]。 此程序最多可能需要 1 到 5 分鐘才能完成。

    顯示如何啟用 Synapse Link 功能的螢幕截圖。

  5. 您的帳戶現在已啟用，可使用 Synapse Link。 接下來，請參閱如何建立已啟用分析存放區的容器，以自動開始將操作資料從交易存放區複寫到分析存放區。

附註

開啟 Synapse Link 並不會自動開啟分析存放區。 啟用 Cosmos DB 帳戶的 Synapse Link 後，啟用容器上的分析存放區，即可開始使用 Synapse Link。

附註

您也可以透過使用 Power BI 和左側導覽功能表整合區段中的 Synapse Link 窗格，為您的帳戶啟用 Synapse Link。

命令列工具

使用 Azure CLI 或 PowerShell，在適用於 NoSQL 的 Azure Cosmos DB API 或 MongoDB 帳戶中啟用 Synapse Link。

Azure CLI

--enable-analytical-storage true或更新作業均可使用。 您還必須選擇表示法結構描述類型。 針對適用於 NoSQL 帳戶的 API ，您可以--analytical-storage-schema-type搭配值FullFidelity或WellDefined來使用 。 對於適用於 MongoDB 帳戶的 API，請一律使用--analytical-storage-schema-type FullFidelity。

適用於 Gremlin API 的 Synapse Link 目前處於預覽版狀態。 您可以使用 Azure CLI，在新的或現有的圖中啟用 Synapse Link。 使用下列 CLI 命令，為您的 Gremlin API 帳戶啟用 Synapse Link：

az cosmosdb create --capabilities EnableGremlin --name MyCosmosDBGremlinDatabaseAccount --resource-group MyResourceGroup --enable-analytical-storage true

對於現有的 Gremlin API 帳戶，請將create取代為update。

PowerShell

EnableAnalyticalStorage true或更新作業均可使用。 您還必須選擇表示法結構描述類型。 針對適用於 NoSQL 帳戶的 API ，您可以--analytical-storage-schema-type搭配值FullFidelity或WellDefined來使用 。 對於適用於 MongoDB 帳戶的 API，請一律使用-AnalyticalStorageSchemaType FullFidelity。

Azure Resource Manager 範本

此 Azure 資源管理者範本會為 SQL API 建立已啟用 Synapse Link 的 Azure Cosmos DB 帳戶。 此範本會在一個區域中建立 Core (SQL) API 帳戶，以及已設定為啟用分析 TTL、且有選項可使用手動或自動縮放輸送量的容器。 若要部署此範本，請在 readme 頁面上，點選部署至 Azure。

啟用適用於您的容器的 Azure Synapse Link

第二個步驟是為您的容器或集合啟用 Synapse Link。 這可透過將analytical TTL屬性設定為-1以無限保留，或設定為正整數，也就是您想要保留在分析存放區中的秒數來完成。 此設定可於稍後變更。 如需詳細資訊，請參閱分析 TTL 所支援的值一文。

在現有的 SQL API 容器上啟用 Azure Synapse Link 時，請注意下列詳細資料：

  • 相同的分析存放區自動同步流程效能隔離會套用到初始同步處理，且不會對您的 OLTP 工作負載造成影響。
  • 分析存放區與容器的初始同步處理所需的總時間將隨資料量和文件的複雜度不同而有所差異。 這項流程有可能在幾秒鐘內完成，也可能需要數天的時間。 請使用 Azure 入口網站來監控移轉的進度。
  • 容器或資料庫帳戶的輸送量也會影響初始同步處理的總時間。 雖然此次移轉中未使用 RU/s，但可用的 RU/s 總數仍會影響流程的效能。 您可以暫時增加環境的可用 RU，以加速整個流程。
  • 當該容器上已啟用 Synapse Link 時，您將無法查詢現有容器的分析存放區。 您的 OLTP 工作負載不會受到影響，且您可以繼續正常讀取資料。 啟動初始同步處理後，資料內嵌將會透過一般分析存放區的自動同步流程合併至分析存放區中。

附註

現在，您可以使用 Azure CLI 或 PowerShell，在現有的 MongoDB API 集合上啟用 Synapse Link。

Azure 入口網站

新增容器

  1. 登入 Azure 入口網站或 Azure Cosmos DB 總管。

  2. 瀏覽至 Azure Cosmos DB 帳戶並開啟資料總管索引標籤。

  3. 選取新容器，然後輸入資料庫的名稱、容器、分割區索引鍵和輸送量詳細資料。 開啟分析存放區選項。 啟用分析存放區後，它會建立一個容器，並將analytical TTL屬性設為預設值 -1 (無限保留)。 此分析存放區會保留記錄的所有歷程記錄版本，並可於稍後變更。

    開啟適用於 Azure Cosmos DB 容器的分析存放區

  4. 如果您先前未在此帳戶上啟用 Synapse Link，系統將會提示您這麼做，因為在建立已啟用分析存放區的容器時，這是先決條件。 若出現提示，請選取啟用 Synapse Link。 此程序最多可能需要 1 到 5 分鐘才能完成。

  5. 選取確定，以建立已啟用分析存放區的 Azure Cosmos DB 容器。

  6. 建立容器後，請點擊資料總管中文件正下方的設定，然後檢查是否已開啟分析存放區存留時間選項，以驗證是否已啟用分析存放區。

現有的容器

  1. 登入 Azure 入口網站或 Azure Cosmos DB 總管。

  2. 瀏覽至 Azure Cosmos DB 帳戶，並開啟 Azure Synapse Link 索引標籤。

  3. 在為您的容器啟用 Azure Synapse Link 區段底下，選取容器。

    顯示如何開啟適用於 Azure Cosmos DB 現有容器之分析存放區的螢幕截圖。

  4. 啟用容器後，請點擊資料總管中文件正下方的設定，然後檢查是否已開啟分析存放區存留時間選項，以驗證是否已啟用分析存放區。

附註

您也可以透過使用 Power BI 和左側導覽功能表整合區段中的 Synapse Link 窗格，為您的帳戶啟用 Synapse Link。

命令列工具

Azure CLI

下列選項會透過使用 Azure CLI 並設定--analytical-storage-ttl屬性，在容器中啟用 Synapse Link。

適用於 Gremlin API 的 Synapse Link 目前處於預覽版狀態。 您可以使用 Azure CLI，在新的或現有的圖中啟用 Synapse Link。 使用下列 CLI 命令，為您的 Gremlin API 圖啟用 Synapse Link：

az cosmosdb gremlin graph create --g MyResourceGroup --a MyCosmosDBGremlinDatabaseAccount --d MyGremlinDB --n MyGraph --analytical-storage-ttl –1

對於現有的圖，請將create取代為update。

PowerShell

下列選項會透過使用 Azure CLI 並設定-AnalyticalStorageTtl屬性，在容器中啟用 Synapse Link。

Azure Cosmos DB SDK - 僅限 SQL API

.NET SDK

下列 .NET 程式碼會透過設定AnalyticalStoreTimeToLiveInSeconds屬性來建立已啟用 Synapse Link 的容器。 若要更新現有的容器，請使用Container.ReplaceContainerAsync方法。

CosmosClient cosmosClient = new CosmosClient(
    accountEndpoint: "<nosql-account-endpoint>",
    tokenCredential: new DefaultAzureCredential()
);

// Create a container with a partition key, and analytical TTL configured to -1 (infinite retention)
ContainerProperties properties = new ContainerProperties()
{
    Id = "myContainerId",
    PartitionKeyPath = "/id",
    AnalyticalStoreTimeToLiveInSeconds = -1,
};
await cosmosClient.GetDatabase("myDatabase").CreateContainerAsync(properties);

Java V4 SDK

下列 Java 程式碼會透過設定setAnalyticalStoreTimeToLiveInSeconds屬性來建立已啟用 Synapse Link 的容器。 若要更新現有的容器，請使用container.replace類別。

// Create a container with a partition key and  analytical TTL configured to  -1 (infinite retention) 
CosmosContainerProperties containerProperties = new CosmosContainerProperties("myContainer", "/myPartitionKey");

containerProperties.setAnalyticalStoreTimeToLiveInSeconds(-1);

container = database.createContainerIfNotExists(containerProperties, 400).block().getContainer();

Python V4 SDK

下列 Python 程式碼會透過設定analytical_storage_ttl屬性來建立已啟用 Synapse Link 的容器。 若要更新現有的容器，請使用replace_container方法。

# Client

client = cosmos_client.CosmosClient(HOST,  KEY )

# Database client
try:
    db = client.create_database(DATABASE)

except exceptions.CosmosResourceExistsError:
    db = client.get_database_client(DATABASE)

# Creating the container with analytical store enabled
try:
    container = db.create_container(
        id=CONTAINER,
        partition_key=PartitionKey(path='/id', kind='Hash'),analytical_storage_ttl=-1
    )
    properties = container.read()
    print('Container with id \'{0}\' created'.format(container.id))
    print('Partition Key - \'{0}\''.format(properties['partitionKey']))

except exceptions.CosmosResourceExistsError:
    print('A container with already exists')

連接至 Synapse 工作區

使用連線至 Azure Synapse Link 中的指示，了解如何使用 Azure Synapse Link 從 Azure Synapse Analytics Studio 存取 Azure Cosmos DB 資料庫。

使用 Azure Synapse Analytics 來查詢分析存放區

使用適用於 Azure Synapse Analytics 的 Apache Spark 來查詢分析存放區

請參閱使用 Spark 3 查詢 Azure Cosmos DB 分析存放區一文中的指示，了解如何使用 Synapse Spark 3 進行查詢。 該文章會提供一些範例，說明如何從 Synapse 手勢與分析存放區互動。 當您以滑鼠右鍵點擊容器時，就可以看到這些手勢。 您可以透過手勢快速產生程式碼，並依據您的需求進行調整。 這些手勢也非常適合透過滑鼠單一點擊來探索資料。

針對 Spark 2 整合，請參閱使用 Spark 2 查詢 Azure Cosmos DB 分析存放區一文中的指示。

使用 Azure Synapse Analytics 中的無伺服器 SQL 集區來查詢分析存放區

無伺服器 SQL 集區可讓您在已啟用 Azure Synapse Link 的 Azure Cosmos DB 容器中查詢及分析資料。 您可以在不影響交易工作負載效能的情況下，以近即時的方式分析資料。 它提供熟悉的 T-SQL 語法，以查詢分析存放區中的資料，並透過 T-SQL 介面為多種 BI 和即席查詢工具提供整合的連線能力。 如需詳細資訊，請參閱使用無伺服器 SQL 集區來查詢分析存放區一文。

使用無伺服器 SQL 集區來分析和視覺化 Power BI 中的資料

您可以在 Azure Cosmos DB 入口網站中使用整合式 BI 體驗，只需點擊幾下就可使用 Synapse Link 來建置 BI 儀表板。 如需詳細資訊，請參閱如何使用 Synapse Link 來建置 BI 儀表板。 此整合式體驗將會在 Synapse 無伺服器 SQL 集區中為您的 Azure Cosmos DB 容器建立簡單的 T-SQL 視圖。 您可以透過這些視圖來建置 BI 儀表板，這將即時查詢您的 Azure Cosmos DB 容器、使用直接查詢，和反映資料的最新變更。 這對您的交易工作負載不會造成效能或成本上的影響，也不會增加管理 ETL 管線的複雜度。

如果您想要跨容器搭配使用進階 T-SQL 視圖與聯結，或以匯入模式建置 Power BI 儀表板，則請參閱使用無伺服器 SQL 集區透過 Synapse Link 來分析 Azure Cosmos DB 資料。

使用最佳做法來改善效能

自訂分割

自訂分割可讓您依照欄位來分割分析存放區資料，這些欄位通常會在分析查詢中作為篩選條件使用，進而改善查詢效能。 若要深入了解，請參考自訂資料分割簡介與如何設定自訂資料分割文章。

針對您的 SQL 無伺服器查詢，請使用這個 (英文) 強制最佳做法。

您可以在GitHub上找到開始使用 Azure Synapse Link 的樣本。 這些樣本會展示 IoT 和零售情境的端對端解決方案。 您也可以在 MongoDB 資料夾底下的相同存放庫中，找到與 Azure Cosmos DB for MongoDB 相對應的樣本。

後續步驟

如需詳細資訊，請參閱下列文件。

  • Last updated on