Azure Cosmos DB 和 .NET SDK v2 的效能秘訣Performance tips for Azure Cosmos DB and .NET SDK v2

適用於: SQL API

Azure Cosmos DB 是一個既快速又彈性的分散式資料庫,可在獲得延遲與輸送量保證的情況下順暢地調整。Azure Cosmos DB is a fast and flexible distributed database that scales seamlessly with guaranteed latency and throughput. 您不需要進行主要的架構變更,也不需要撰寫複雜的程式碼以 Azure Cosmos DB 來調整您的資料庫。You don't have to make major architecture changes or write complex code to scale your database with Azure Cosmos DB. 相應增加和減少就像進行單一 API 呼叫一樣簡單。Scaling up and down is as easy as making a single API call. 若要深入了解,請參閱如何佈建容器輸送量如何佈建資料庫輸送量To learn more, see how to provision container throughput or how to provision database throughput. 但因為 Azure Cosmos DB 是透過網路呼叫存取,所以您可以進行用戶端優化以達到使用 SQL .NET SDK時的尖峰效能。But because Azure Cosmos DB is accessed via network calls, there are client-side optimizations you can make to achieve peak performance when you use the SQL .NET SDK.

因此,如果您想要改善資料庫效能,請考慮下列選項:So, if you're trying to improve your database performance, consider these options:

升級至 .NET V3 SDKUpgrade to the .NET V3 SDK

.Net V3 SDK已發行。The .NET v3 SDK is released. 如果您使用 .NET v3 SDK,請參閱 .net v3 效能指南 以取得下列資訊:If you use the .NET v3 SDK, see the .NET v3 performance guide for the following information:

  • 預設為直接 TCP 模式Defaults to Direct TCP mode
  • 串流 API 支援Stream API support
  • 支援自訂序列化程式以允許 System.Text.JS使用方式Support custom serializer to allow System.Text.JSON usage
  • 整合式批次和大量支援Integrated batch and bulk support

裝載建議Hosting recommendations

針對需要大量查詢的工作負載,請使用 Windows 64 位,而不是 Linux 或 Windows 32 位主機處理For query-intensive workloads, use Windows 64-bit instead of Linux or Windows 32-bit host processing

我們建議 Windows 64 位主機處理,以改善效能。We recommend Windows 64-bit host processing for improved performance. SQL SDK 包含原生 ServiceInterop.dll,可在本機剖析和最佳化查詢。The SQL SDK includes a native ServiceInterop.dll to parse and optimize queries locally. ServiceInterop.dll 只能在 Windows x64 平台上受到支援。ServiceInterop.dll is supported only on the Windows x64 platform. 若為 Linux 和其他不支援 ServiceInterop.dll 的平臺,則會對閘道進行額外的網路呼叫,以取得優化的查詢。For Linux and other unsupported platforms where ServiceInterop.dll isn't available, an additional network call is made to the gateway to get the optimized query. 下列類型的應用程式預設會使用32位主機處理。The following types of applications use 32-bit host processing by default. 若要將主機處理變更為64位處理,請根據應用程式的類型,遵循下列步驟:To change host processing to 64-bit processing, follow these steps, based on the type of your application:

  • 針對可執行檔應用程式,您可以在 [專案屬性] 視窗的 [組建] 索引標籤中,將 [平臺目標] 設定為 [ x64 ] 來變更主機處理For executable applications, you can change host processing by setting the platform target to x64 in the Project Properties window, on the Build tab.

  • 針對以 VSTest 為基礎的測試專案,您可以在 > [Visual Studio 測試] 功能表上選取 [測試 測試設定 > 預設處理器架構為 X64 ] 來變更主處理。For VSTest-based test projects, you can change host processing by selecting Test > Test Settings > Default Processor Architecture as X64 on the Visual Studio Test menu.

  • 針對本機部署的 ASP.NET web 應用程式,您可以在 [工具 選項專案和方案 Web 專案] 下,選取 [使用適用于網站和專案的64位版本 IIS Express ] 來變更主機處理 > > > ****。For locally deployed ASP.NET web applications, you can change host processing by selecting Use the 64-bit version of IIS Express for web sites and projects under Tools > Options > Projects and Solutions > Web Projects.

  • 針對部署在 Azure 上的 ASP.NET web 應用程式,您可以在 Azure 入口網站的 [應用程式設定] 中選取 64 位平臺,以變更主機處理。For ASP.NET web applications deployed on Azure, you can change host processing by selecting the 64-bit platform in Application settings in the Azure portal.

注意

根據預設,新 Visual Studio 專案會設定為 [ 任何 CPU]。By default, new Visual Studio projects are set to Any CPU. 建議您將專案設定為 x64 ,使其不會切換至 x86We recommend that you set your project to x64 so it doesn't switch to x86. 如果加入僅限 x86 的相依性,則將專案設定為 任何 CPU 可以輕鬆地切換至 x86A project set to Any CPU can easily switch to x86 if an x86-only dependency is added.
ServiceInterop.dll 必須在執行 SDK DLL 的資料夾中。ServiceInterop.dll needs to be in the folder that the SDK DLL is being executed from. 只有當您手動複製 Dll 或擁有自訂群組建/部署系統時,才需要考慮這一點。This should be a concern only if you manually copy DLLs or have custom build/deployment systems.

開啟伺服器端垃圾收集 (GC)Turn on server-side garbage collection (GC)

在某些情況下,降低垃圾收集的頻率可能會有所説明。Reducing the frequency of garbage collection can help in some cases. 在 .NET 中,將 >gcserver> 設定為 trueIn .NET, set gcServer to true.

擴充您的用戶端工作負載Scale out your client workload

如果您是以高輸送量層級進行測試 (超過 50000 RU/秒) ,用戶端應用程式可能會因為電腦在 CPU 或網路使用量上的上限而變成瓶頸。If you're testing at high throughput levels (more than 50,000 RU/s), the client application could become the bottleneck due to the machine capping out on CPU or network utilization. 如果到了這一刻,您可以將用戶端應用程式向外延展至多部伺服器,以繼續將 Azure Cosmos DB 帳戶再往前推進一步。If you reach this point, you can continue to push the Azure Cosmos DB account further by scaling out your client applications across multiple servers.

注意

高 CPU 使用率可能會導致延遲增加和要求超時例外狀況。High CPU usage can cause increased latency and request timeout exceptions.

網路Networking

原則︰使用直接連接模式Connection policy: Use direct connection mode

.NET V2 SDK 預設連線模式是 gateway。.NET V2 SDK default connection mode is gateway. 您可以使用參數,在實例的結構期間設定連接模式 DocumentClient ConnectionPolicyYou configure the connection mode during the construction of the DocumentClient instance by using the ConnectionPolicy parameter. 如果您使用直接模式,您也必須 Protocol 使用參數來設定 ConnectionPolicyIf you use direct mode, you need to also set the Protocol by using the ConnectionPolicy parameter. 若要深入瞭解不同的連線選項,請參閱連線 模式 文章。To learn more about different connectivity options, see the connectivity modes article.

Uri serviceEndpoint = new Uri("https://contoso.documents.net");
string authKey = "your authKey from the Azure portal";
DocumentClient client = new DocumentClient(serviceEndpoint, authKey,
new ConnectionPolicy
{
   ConnectionMode = ConnectionMode.Direct, // ConnectionMode.Gateway is the default
   ConnectionProtocol = Protocol.Tcp
});

暫時連接埠耗盡Ephemeral port exhaustion

如果您在實例上看到的連接量或高埠使用量很高,請先確認您的用戶端實例已 singleton。If you see a high connection volume or high port usage on your instances, first verify that your client instances are singletons. 換句話說,用戶端實例在應用程式的存留期內應該是唯一的。In other words, the client instances should be unique for the lifetime of the application.

在 TCP 通訊協定上執行時,用戶端會使用長時間執行的連線(而不是 HTTPS 通訊協定)來優化延遲,這會在閒置2分鐘後終止連接。When running on the TCP protocol, the client optimizes for latency by using the long-lived connections as opposed to the HTTPS protocol, which terminates the connections after 2 minutes of inactivity.

在您有稀疏存取的情況下,如果您在與閘道模式存取相較之下發現連接計數較高,您可以:In scenarios where you have sparse access and if you notice a higher connection count when compared to the gateway mode access, you can:

  • ConnectionPolicy. PortReuseMode 屬性設定為 PrivatePortPool (有效的 framework 版本>= 4.6.1 和 .net core 版本 >= 2.0) :此屬性可讓 SDK 針對不同的 Azure Cosmos DB 目的地端點使用較小的暫時埠集區。Configure the ConnectionPolicy.PortReuseMode property to PrivatePortPool (effective with framework version>= 4.6.1 and .NET core version >= 2.0): This property allows the SDK to use a small pool of ephemeral ports for different Azure Cosmos DB destination endpoints.
  • 設定 ConnectionPolicy. IdleConnectionTimeout 屬性必須大於或等於10分鐘。Configure the ConnectionPolicy.IdleConnectionTimeout property must be greater than or equal to 10 minutes. 建議的值介於20分鐘到24小時之間。The recommended values are between 20 minutes and 24 hours.

呼叫 OpenAsync 以避免第一次要求的啟動延遲Call OpenAsync to avoid startup latency on first request

根據預設,第一個要求會有較高的延遲,因為它需要提取位址路由表。By default, the first request has higher latency because it needs to fetch the address routing table. 當您使用 SDK V2時,請在 OpenAsync() 初始化期間呼叫一次,以避免第一個要求的啟動延遲。When you use SDK V2, call OpenAsync() once during initialization to avoid this startup latency on the first request. 呼叫看起來像這樣: await client.OpenAsync();The call looks like: await client.OpenAsync();

注意

OpenAsync 將會產生要求,以取得帳戶中所有容器的位址路由表。OpenAsync will generate requests to obtain the address routing table for all the containers in the account. 對於具有許多容器的帳戶,但其應用程式會存取一部分的容器, OpenAsync 會產生不必要的流量量,這會導致初始化變慢。For accounts that have many containers but whose application accesses a subset of them, OpenAsync would generate an unnecessary amount of traffic, which would make the initialization slow. 因此, OpenAsync 在此案例中使用可能不會很有用,因為它會減緩應用程式啟動的速度。So using OpenAsync might not be useful in this scenario because it slows down application startup.

針對效能,請在相同的 Azure 區域中共置用戶端For performance, collocate clients in same Azure region

可能的話,請將呼叫 Azure Cosmos DB 的任何應用程式放在與 Azure Cosmos DB 資料庫相同的區域中。When possible, place any applications that call Azure Cosmos DB in the same region as the Azure Cosmos DB database. 以下是大約的比較:在相同區域內 Azure Cosmos DB 的呼叫會在1毫秒到2毫秒內完成,但是美國西部與東部海岸之間的延遲超過50毫秒。Here's an approximate comparison: calls to Azure Cosmos DB within the same region complete within 1 ms to 2 ms, but the latency between the West and East coast of the US is more than 50 ms. 這項延遲可能會因要求的要求而有所不同,這取決於要求從用戶端傳遞至 Azure 資料中心界限時所採取的路由。This latency can vary from request to request, depending on the route taken by the request as it passes from the client to the Azure datacenter boundary. 您可以確保呼叫的應用程式位於與布建的 Azure Cosmos DB 端點相同的 Azure 區域內,以取得可能的最低延遲。You can get the lowest possible latency by ensuring the calling application is located within the same Azure region as the provisioned Azure Cosmos DB endpoint. 如需可用區域的清單,請參閱 Azure 區域For a list of available regions, see Azure regions.

Azure Cosmos DB 連接原則

增加執行緒/工作數目 Increase the number of threads/tasks

由於呼叫 Azure Cosmos DB 是透過網路進行,因此您可能需要改變要求的平行處理原則程度,以便讓用戶端應用程式花費最短時間在要求之間等待。Because calls to Azure Cosmos DB are made over the network, you might need to vary the degree of parallelism of your requests so that the client application spends minimal time waiting between requests. 例如,如果您使用的是 .NET 工作 平行程式庫,請建立從 Azure Cosmos DB 讀取或寫入的數百個工作的順序。For example, if you're using the .NET Task Parallel Library, create on the order of hundreds of tasks that read from or write to Azure Cosmos DB.

啟用加速網路Enable accelerated networking

若要減少延遲和 CPU 抖動,建議您在用戶端虛擬機器上啟用加速網路。To reduce latency and CPU jitter, we recommend that you enable accelerated networking on client virtual machines. 請參閱使用 加速網路建立 Windows 虛擬機器 ,或 建立具有加速網路功能的 Linux 虛擬機。See Create a Windows virtual machine with accelerated networking or Create a Linux virtual machine with accelerated networking.

SDK 使用方式SDK usage

安裝最新的 SDKInstall the most recent SDK

Azure Cosmos DB SDK 會持續改善以提供最佳效能。The Azure Cosmos DB SDKs are constantly being improved to provide the best performance. 請參閱 Azure Cosmos DB SDK 頁面來判斷最新的 SDK 並檢閱改善項目。See the Azure Cosmos DB SDK pages to determine the most recent SDK and review improvements.

在應用程式存留期內使用單一 Azure Cosmos DB 用戶端Use a singleton Azure Cosmos DB client for the lifetime of your application

每個 DocumentClient 實例都是安全線程,並且在直接模式中運作時執行有效率的連接管理和位址快取。Each DocumentClient instance is thread-safe and performs efficient connection management and address caching when operating in direct mode. 若要允許有效率的連線管理和更好的 SDK 用戶端效能,建議您在 AppDomain 應用程式的存留期內使用單一實例。To allow efficient connection management and better SDK client performance, we recommend that you use a single instance per AppDomain for the lifetime of the application.

使用閘道模式時,每一主機增加 System.Net MaxConnectionsIncrease System.Net MaxConnections per host when using gateway mode

當您使用閘道模式時,會透過 HTTPS/REST 發出 Azure Cosmos DB 要求。Azure Cosmos DB requests are made over HTTPS/REST when you use gateway mode. 它們受限於每個主機名稱或 IP 位址的預設連線限制。They're subjected to the default connection limit per hostname or IP address. 您可能需要將設定 MaxConnections 為較高的值 (100 至 1000) 因此,用戶端程式庫可以使用多個同時連線來 Azure Cosmos DB。You might need to set MaxConnections to a higher value (100 to 1,000) so the client library can use multiple simultaneous connections to Azure Cosmos DB. 在 .NET SDK 1.8.0 和更新版本中, ServicePointManager >servicepointmanager.defaultconnectionlimit 的預設值是50。In .NET SDK 1.8.0 and later, the default value for ServicePointManager.DefaultConnectionLimit is 50. 若要變更此值,您可以將 ConnectionPolicy. MaxConnectionLimit 設定為較高的值。To change the value, you can set Documents.Client.ConnectionPolicy.MaxConnectionLimit to a higher value.

調整資料分割集合的平行查詢Tune parallel queries for partitioned collections

SQL .NET SDK 1.9.0 和更新版本支援平行查詢,可讓您以平行方式查詢分割的集合。SQL .NET SDK 1.9.0 and later support parallel queries, which enable you to query a partitioned collection in parallel. 如需詳細資訊,請參閱使用 SDK 的相關程式碼範例For more information, see code samples related to working with the SDKs. 平行查詢的設計目的是要提供比其序列對應更好的查詢延遲和輸送量。Parallel queries are designed to provide better query latency and throughput than their serial counterpart. 平行查詢提供兩個參數,可供您調整以符合您的需求:Parallel queries provide two parameters that you can tune to fit your requirements:

  • MaxDegreeOfParallelism 控制可以平行查詢的資料分割數目上限。MaxDegreeOfParallelism controls the maximum number of partitions that can be queried in parallel.
  • MaxBufferedItemCount 控制預先提取的結果數目。MaxBufferedItemCount controls the number of pre-fetched results.

調整平行處理原則的程度Tuning degree of parallelism

平行查詢的運作方式是以平行方式查詢多個資料分割。Parallel query works by querying multiple partitions in parallel. 但是個別分割區中的資料會根據查詢順序提取。But data from an individual partition is fetched serially with respect to the query. MaxDegreeOfParallelism若將SDK V2中的資料分割設定為數據分割數目,就有機會達到最高效能的查詢,但前提是其他所有系統條件維持不變。Setting MaxDegreeOfParallelism in SDK V2 to the number of partitions has the best chance of achieving the most performant query, provided all other system conditions remain the same. 如果您不知道資料分割數目,您可以將平行處理原則的程度設定為較高的數位。If you don't know the number of partitions, you can set the degree of parallelism to a high number. 系統會選擇最小 (的資料分割數目、使用者提供的輸入) 作為平行處理原則的程度。The system will choose the minimum (number of partitions, user provided input) as the degree of parallelism.

如果資料平均分佈在與查詢相關的所有資料分割中,平行查詢會產生最大效益。Parallel queries produce the most benefit if the data is evenly distributed across all partitions with respect to the query. 如果分割的集合已分割,以便查詢所傳回的所有或大部分資料都集中在少數幾個資料分割中 (一個資料分割是最糟的情況) ,則這些資料分割將會造成查詢的效能瓶頸。If the partitioned collection is partitioned so that all or most of the data returned by a query is concentrated in a few partitions (one partition is the worst case), those partitions will bottleneck the performance of the query.

微調 MaxBufferedItemCountTuning MaxBufferedItemCount

平行查詢的設計是可在用戶端處理目前的結果批次時,先預先擷取結果。Parallel query is designed to pre-fetch results while the current batch of results is being processed by the client. 這項預先提取有助於改善查詢的整體延遲。This pre-fetching helps improve the overall latency of a query. MaxBufferedItemCount參數會限制預先提取的結果數目。The MaxBufferedItemCount parameter limits the number of pre-fetched results. 設定 MaxBufferedItemCount 為預期傳回的結果數目 (或更高的數目) ,讓查詢能獲得預先提取的最大效益。Set MaxBufferedItemCount to the expected number of results returned (or a higher number) to allow the query to receive the maximum benefit from pre-fetching.

不論平行處理原則的程度為何,預先提取的運作方式都相同,而且所有分割區的資料都有一個緩衝區。Pre-fetching works the same way regardless of the degree of parallelism, and there's a single buffer for the data from all partitions.

在 RetryAfter 間隔實作降速Implement backoff at RetryAfter intervals

在效能測試期間,您應該增加負載,直到低比率的要求受到節流。During performance testing, you should increase load until a small rate of requests are throttled. 如果要求受到節流處理,用戶端應用程式應該會在伺服器指定的重試間隔中,針對伺服器指定的重試間隔關閉。If requests are throttled, the client application should back off on throttle for the server-specified retry interval. 遵循輪詢可確保您在重試之間花費最少的等候時間。Respecting the backoff ensures you spend a minimal amount of time waiting between retries.

這些 Sdk 包含重試原則支援:Retry policy support is included in these SDKs:

如需詳細資訊,請參閱 RetryAfterFor more information, see RetryAfter.

在 .NET SDK 1.19 版和更新版本中,有一種機制可記錄其他診斷資訊和針對延遲問題進行疑難排解,如下列範例所示。In version 1.19 and later of the .NET SDK, there's a mechanism for logging additional diagnostic information and troubleshooting latency issues, as shown in the following sample. 您可以針對具有較高讀取延遲的要求記錄診斷字串。You can log the diagnostic string for requests that have a higher read latency. 所捕獲的診斷字串將協助您瞭解在指定的要求中收到429錯誤的次數。The captured diagnostic string will help you understand how many times you received 429 errors for a given request.

ResourceResponse<Document> readDocument = await this.readClient.ReadDocumentAsync(oldDocuments[i].SelfLink);
readDocument.RequestDiagnosticsString 

快取較低讀取延遲的文件 URICache document URIs for lower read latency

盡可能快取文件 URI 以達到最佳讀取效能。Cache document URIs whenever possible for the best read performance. 當您建立資源時,您需要定義邏輯來快取資源識別碼。You need to define logic to cache the resource ID when you create a resource. 以資源識別碼為基礎的查閱速度比以名稱為基礎的查閱更快,因此快取這些值可改善效能。Lookups based on resource IDs are faster than name-based lookups, so caching these values improves performance.

調整查詢/讀取摘要的頁面大小以獲得更好的效能Tune the page size for queries/read feeds for better performance

當您使用讀取摘要功能來大量讀取檔時 (例如, ReadDocumentFeedAsync) 或當您發出 SQL 查詢時,如果結果集太大,則會以分段方式傳回結果。When you do a bulk read of documents by using read feed functionality (for example, ReadDocumentFeedAsync) or when you issue a SQL query, the results are returned in a segmented fashion if the result set is too large. 根據預設,會以 100 個項目或 1 MB 的區塊傳回結果 (以先達到的限制為準)。By default, results are returned in chunks of 100 items or 1 MB, whichever limit is hit first.

若要減少取出所有適用結果所需的網路來回行程次數,您可以使用 x-毫秒-最大專案計數 來要求最多1000的標頭,以增加頁面大小。To reduce the number of network round trips required to retrieve all applicable results, you can increase the page size by using x-ms-max-item-count to request as many as 1,000 headers. 當您只需要顯示幾個結果時(例如,如果您的使用者介面或應用程式 API 一次只傳回10個結果),您也可以將頁面大小縮小為10,以降低讀取和查詢所耗用的輸送量。When you need to display only a few results, for example, if your user interface or application API returns only 10 results at a time, you can also decrease the page size to 10 to reduce the throughput consumed for reads and queries.

注意

maxItemCount屬性不應只用于分頁。The maxItemCount property shouldn't be used just for pagination. 其主要用途是減少在單一頁面中傳回的最大專案數,藉以改善查詢的效能。Its main use is to improve the performance of queries by reducing the maximum number of items returned in a single page.

您也可以使用可用的 Azure Cosmos DB Sdk 來設定頁面大小。You can also set the page size by using the available Azure Cosmos DB SDKs. 中的 MaxItemCount 屬性可 FeedOptions 讓您設定列舉作業中要傳回的專案數目上限。The MaxItemCount property in FeedOptions allows you to set the maximum number of items to be returned in the enumeration operation. maxItemCount 設定為-1 時,SDK 會自動尋找最佳值,視檔案大小而定。When maxItemCount is set to -1, the SDK automatically finds the optimal value, depending on the document size. 例如:For example:

IQueryable<dynamic> authorResults = client.CreateDocumentQuery(documentCollection.SelfLink, "SELECT p.Author FROM Pages p WHERE p.Title = 'About Seattle'", new FeedOptions { MaxItemCount = 1000 });

執行查詢時,會在 TCP 封包內傳送產生的資料。When a query is executed, the resulting data is sent within a TCP packet. 如果您指定的值太低,則在 maxItemCount TCP 封包中傳送資料所需的行程次數很高,而這會影響效能。If you specify too low a value for maxItemCount, the number of trips required to send the data within the TCP packet is high, which affects performance. 因此,如果您不確定要為屬性設定的值 maxItemCount ,最好將它設定為-1,並讓 SDK 選擇預設值。So if you're not sure what value to set for the maxItemCount property, it's best to set it to -1 and let the SDK choose the default value.

增加執行緒/工作數目Increase the number of threads/tasks

請參閱本文的「網路功能」一節中的「 增加執行緒/工作數目 」。See Increase the number of threads/tasks in the networking section of this article.

編製索引原則Indexing policy

從索引編製中排除未使用的路徑以加快寫入速度Exclude unused paths from indexing for faster writes

Azure Cosmos DB 的編制索引原則也可讓您使用索引路徑 (IndexingPolicy IncludedPaths 和 IndexingPolicy. Indexingpolicy.excludedpaths) ,指定要包含在索引中或從中排除的檔路徑。The Azure Cosmos DB indexing policy also allows you to specify which document paths to include in or exclude from indexing by using indexing paths (IndexingPolicy.IncludedPaths and IndexingPolicy.ExcludedPaths). 在事先已知查詢模式的情況下,編制索引路徑可改善寫入效能並降低索引儲存體。Indexing paths can improve write performance and reduce index storage for scenarios in which the query patterns are known beforehand. 這是因為索引編制成本會直接與索引的唯一路徑數目產生關聯。This is because indexing costs correlate directly to the number of unique paths indexed. 例如,這段程式碼會示範如何使用 "*" 萬用字元,將檔的整個區段 (子樹) 從索引中排除:For example, this code shows how to exclude an entire section of the documents (a subtree) from indexing by using the "*" wildcard:

var collection = new DocumentCollection { Id = "excludedPathCollection" };
collection.IndexingPolicy.IncludedPaths.Add(new IncludedPath { Path = "/*" });
collection.IndexingPolicy.ExcludedPaths.Add(new ExcludedPath { Path = "/nonIndexedContent/*");
collection = await client.CreateDocumentCollectionAsync(UriFactory.CreateDatabaseUri("db"), collection);

如需詳細資訊,請參閱 Azure Cosmos DB 索引編製原則For more information, see Azure Cosmos DB indexing policies.

輸送量Throughput

測量和調整較低的要求單位/秒使用量Measure and tune for lower Request Units/second usage

Azure Cosmos DB 提供一組豐富的資料庫作業。Azure Cosmos DB offers a rich set of database operations. 這些作業包括使用 Udf、預存程式和觸發程式進行關聯式和階層式查詢,而這些查詢都是在資料庫集合內的檔上運作。These operations include relational and hierarchical queries with UDFs, stored procedures, and triggers, all operating on the documents within a database collection. 與每個作業相關聯的成本會根據完成作業所需的 CPU、IO 和記憶體而有所不同。The cost associated with each of these operations varies depending on the CPU, IO, and memory required to complete the operation. 與其考慮和管理硬體資源,您可以將要求單位 (RU) 作為執行各種資料庫作業和服務應用程式要求所需資源的單一量值。Instead of thinking about and managing hardware resources, you can think of a Request Unit (RU) as a single measure for the resources required to perform various database operations and service an application request.

輸送量是根據為每個容器設定的 要求單位 數目來布建。Throughput is provisioned based on the number of Request Units set for each container. 要求單位耗用量是以每秒的速率來評估。Request Unit consumption is evaluated as a rate per second. 超過布建之容器要求單位速率的應用程式會受到限制,直到該速率低於容器的布建層級。Applications that exceed the provisioned Request Unit rate for their container are limited until the rate drops below the provisioned level for the container. 如果您的應用程式需要較高層級的輸送量,您可以布建額外的要求單位來增加輸送量。If your application requires a higher level of throughput, you can increase your throughput by provisioning additional Request Units.

查詢的複雜性會影響針對作業所耗用的要求單位數目。The complexity of a query affects how many Request Units are consumed for an operation. 述詞數目、述詞性質、Udf 數目,以及源資料集的大小,全都會影響查詢作業的成本。The number of predicates, the nature of the predicates, the number of UDFs, and the size of the source dataset all influence the cost of query operations.

若要測量任何作業的額外負荷 (建立、更新或刪除) ,請檢查 x-ms-要求費用 標頭 (或 RequestCharge .net SDK) 中或中的對等屬性, ResourceResponse\<T> FeedResponse\<T> 以測量作業所耗用的要求單位數目:To measure the overhead of any operation (create, update, or delete), inspect the x-ms-request-charge header (or the equivalent RequestCharge property in ResourceResponse\<T> or FeedResponse\<T> in the .NET SDK) to measure the number of Request Units consumed by the operations:

// Measure the performance (Request Units) of writes
ResourceResponse<Document> response = await client.CreateDocumentAsync(collectionSelfLink, myDocument);
Console.WriteLine("Insert of document consumed {0} request units", response.RequestCharge);
// Measure the performance (Request Units) of queries
IDocumentQuery<dynamic> queryable = client.CreateDocumentQuery(collectionSelfLink, queryString).AsDocumentQuery();
while (queryable.HasMoreResults)
    {
        FeedResponse<dynamic> queryResponse = await queryable.ExecuteNextAsync<dynamic>();
        Console.WriteLine("Query batch consumed {0} request units", queryResponse.RequestCharge);
    }

此標頭中傳回的要求費用是布建輸送量的一部分, (也就是 2000 ru/秒) 。The request charge returned in this header is a fraction of your provisioned throughput (that is, 2,000 RUs / second). 例如,如果上述查詢傳回 1000 1 KB 檔,則作業的成本是1000。For example, if the preceding query returns 1,000 1-KB documents, the cost of the operation is 1,000. 因此,在一秒內,伺服器只接受兩個這類要求,再對稍後的要求進行速率限制。So, within one second, the server honors only two such requests before rate limiting later requests. 如需詳細資訊,請參閱 要求單位要求單位計算機For more information, see Request Units and the Request Unit calculator.

處理速率限制/要求速率太大Handle rate limiting/request rate too large

當用戶端嘗試超過帳戶的保留輸送量時,伺服器的效能不會降低,而且不會使用超過保留層級的輸送量容量。When a client attempts to exceed the reserved throughput for an account, there's no performance degradation at the server and no use of throughput capacity beyond the reserved level. 伺服器會事先使用 RequestRateTooLarge (HTTP 狀態碼 429) 來結束要求。The server will preemptively end the request with RequestRateTooLarge (HTTP status code 429). 它會傳回一次 x 毫秒- -毫秒的標頭,表示使用者必須等待的時間長度(以毫秒為單位),然後再重試要求。It will return an x-ms-retry-after-ms header that indicates the amount of time, in milliseconds, that the user must wait before attempting the request again.

HTTP Status 429,
Status Line: RequestRateTooLarge
x-ms-retry-after-ms :100

SDK 全都隱含地攔截這個回應,採用伺服器指定的 retry-after 標頭,並重試此要求。The SDKs all implicitly catch this response, respect the server-specified retry-after header, and retry the request. 除非有多個用戶端同時存取您的帳戶,否則下次重試將會成功。Unless your account is being accessed concurrently by multiple clients, the next retry will succeed.

如果您有多個用戶端的累積作業高於要求速率,則在用戶端內部設定的預設重試計數目前可能不會足夠。If you have more than one client cumulatively operating consistently above the request rate, the default retry count currently set to 9 internally by the client might not suffice. 在此情況下,用戶端會對應用程式擲回狀態碼為429的 Documentclientexception (。In this case, the client throws a DocumentClientException with status code 429 to the application.

您可以藉由在實例上設定,來變更預設的重試計數 RetryOptions ConnectionPolicyYou can change the default retry count by setting the RetryOptions on the ConnectionPolicy instance. 根據預設,如果要求繼續以高於要求速率的方式運作,則會在 30 秒的累計等候時間後傳回 DocumentClientException (狀態碼 429)。By default, the DocumentClientException with status code 429 is returned after a cumulative wait time of 30 seconds if the request continues to operate above the request rate. 這項錯誤會在目前的重試計數小於最大重試次數時傳回,無論目前的值是預設值9或使用者定義值。This error returns even when the current retry count is less than the maximum retry count, whether the current value is the default of 9 or a user-defined value.

自動重試行為可協助改善大部分應用程式的復原能力和可用性。The automated retry behavior helps improve resiliency and usability for most applications. 但是當您執行效能基準測試時,可能不是最佳的行為,尤其是在測量延遲的時候。But it might not be the best behavior when you're doing performance benchmarks, especially when you're measuring latency. 如果實驗達到伺服器節流並導致用戶端 SDK 以無訊息模式重試,則用戶端觀察到的延遲將會突然增加。The client-observed latency will spike if the experiment hits the server throttle and causes the client SDK to silently retry. 若要避免效能實驗期間的延遲尖峰,測量每個作業所傳回的費用,並確保要求是以低於保留要求速率的方式運作。To avoid latency spikes during performance experiments, measure the charge returned by each operation and ensure that requests are operating below the reserved request rate. 如需詳細資訊,請參閱 要求單位For more information, see Request Units.

針對較高的輸送量,請針對較小的檔進行設計For higher throughput, design for smaller documents

要求費用 (也就是指定作業的要求處理成本) 直接與檔案大小相互關聯。The request charge (that is, the request-processing cost) of a given operation correlates directly to the size of the document. 大型檔的作業成本高於小型檔上的作業。Operations on large documents cost more than operations on small documents.

下一步Next steps

如需在少數用戶端電腦上用來評估高效能案例 Azure Cosmos DB 的範例應用程式,請參閱 Azure Cosmos DB 的效能和規模測試For a sample application that's used to evaluate Azure Cosmos DB for high-performance scenarios on a few client machines, see Performance and scale testing with Azure Cosmos DB.

若要深入了解如何針對規模和高效能設計您的應用程式,請參閱 Azure Cosmos DB 的資料分割與調整規模To learn more about designing your application for scale and high performance, see Partitioning and scaling in Azure Cosmos DB.