From 2c8fda4d809f40108a9a82268fcbd313cdc01776 Mon Sep 17 00:00:00 2001 From: Danielle9897 Date: Sun, 14 Jun 2026 13:03:21 +0300 Subject: [PATCH 1/2] RDoc-3333 Document sharding query optimization --- .../content/_conventions-csharp.mdx | 39 ++++++++++ docs/sharding/configuration.mdx | 77 +++++++++++++++++++ docs/sharding/import-and-export.mdx | 23 ++---- docs/sharding/overview.mdx | 41 +++++----- 4 files changed, 146 insertions(+), 34 deletions(-) create mode 100644 docs/sharding/configuration.mdx diff --git a/docs/client-api/configuration/content/_conventions-csharp.mdx b/docs/client-api/configuration/content/_conventions-csharp.mdx index 12a5ec5325..f10c3fee19 100644 --- a/docs/client-api/configuration/content/_conventions-csharp.mdx +++ b/docs/client-api/configuration/content/_conventions-csharp.mdx @@ -31,6 +31,7 @@ import CodeBlock from '@theme/CodeBlock'; [FindPropertyNameForDynamicIndex](../../../client-api/configuration/conventions.mdx#findpropertynamefordynamicindex) [FindPropertyNameForIndex](../../../client-api/configuration/conventions.mdx#findpropertynameforindex) [FirstBroadcastAttemptTimeout](../../../client-api/configuration/conventions.mdx#firstbroadcastattempttimeout) + [GlobalHttpClientTimeout](../../../client-api/configuration/conventions.mdx#globalhttpclienttimeout) [HttpClientType](../../../client-api/configuration/conventions.mdx#httpclienttype) [HttpPooledConnectionIdleTimeout](../../../client-api/configuration/conventions.mdx#httppooledconnectionidletimeout) [HttpPooledConnectionLifetime](../../../client-api/configuration/conventions.mdx#httppooledconnectionlifetime) @@ -704,6 +705,44 @@ public TimeSpan FirstBroadcastAttemptTimeout \{ get; set; \} + + + +#### GlobalHttpClientTimeout + +* Use the `GlobalHttpClientTimeout` convention to set the maximum time the underlying `HttpClient` can spend on a single HTTP request. + If a request takes longer than this value, the request times out and the client reports an error. + This setting does not control how long an idle TCP connection remains open; it limits how long the client waits for an HTTP request to complete. + +* This value also serves as the maximum allowed timeout for request-executor timeouts, + such as [RequestTimeout](../../../client-api/configuration/conventions.mdx#requesttimeout), + [FirstBroadcastAttemptTimeout](../../../client-api/configuration/conventions.mdx#firstbroadcastattempttimeout), + [SecondBroadcastAttemptTimeout](../../../client-api/configuration/conventions.mdx#secondbroadcastattempttimeout), and per-request command timeouts. + Setting any of these to a value greater than `GlobalHttpClientTimeout` will throw an exception. + +* In client code, set `GlobalHttpClientTimeout` to be greater than or equal to the longest request timeout you plan to use. + For example, if you set `RequestTimeout` or a per-request timeout to 24 hours, `GlobalHttpClientTimeout` must also be at least 24 hours. + +* Set the value to `Timeout.InfiniteTimeSpan` to remove this upper-bound restriction. + +* DEFAULT: `12 hours` + + + +{`GlobalHttpClientTimeout = TimeSpan.FromHours(6) +`} + + + + +{`// Syntax: +public TimeSpan GlobalHttpClientTimeout \{ get; set; \} +`} + + + + + #### HttpClientType diff --git a/docs/sharding/configuration.mdx b/docs/sharding/configuration.mdx new file mode 100644 index 0000000000..a74065efc8 --- /dev/null +++ b/docs/sharding/configuration.mdx @@ -0,0 +1,77 @@ +--- +title: "Sharding: Configuration Options" +description: "Configure RavenDB sharding options for sharded import stream compression, orchestrator request timeouts, and shard executor HTTP compression." +sidebar_label: Configuration +sidebar_position: 13 +--- + +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; +import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; +import LanguageContent from "@site/src/components/LanguageContent"; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; + + + +* The following configuration options control sharded import stream compression and HTTP communication between the orchestrator and the shards. + + Learn how to apply configuration options in [Configuration Overview](../server/configuration/configuration-options.mdx). + +* In this article: + * [Sharding.Import.CompressionLevel](../sharding/configuration.mdx#shardingimportcompressionlevel) + * [Sharding.OrchestratorTimeoutInMin](../sharding/configuration.mdx#shardingorchestratortimeoutinmin) + * [Sharding.ShardExecutor.UseHttpCompression](../sharding/configuration.mdx#shardingshardexecutorusehttpcompression) + * [Sharding.ShardExecutor.UseHttpDecompression](../sharding/configuration.mdx#shardingshardexecutorusehttpdecompression) + + + + + +## Sharding.Import.CompressionLevel + +The compression level used when the orchestrator sends imported data to the shards during a smuggler import. + +- **Type**: `CompressionLevel` (`NoCompression`, `Optimal`, `Fastest`, `SmallestSize`) +- **Default**: `NoCompression` +- **Scope**: Server-wide or per database + + + + +## Sharding.OrchestratorTimeoutInMin + +* Sets the maximum timeout, in minutes, for HTTP requests that the orchestrator sends to shards. +* By default, this timeout is infinite, so no timeout is enforced by this setting. + +--- + +- **Type**: `int` (minutes) +- **Default**: `Infinite` (no timeout) +- **Scope**: Server-wide only + + + + +## Sharding.ShardExecutor.UseHttpCompression + +Compress HTTP request content sent by the orchestrator to the shards. + +- **Type**: `bool` +- **Default**: `false` +- **Scope**: Server-wide only + + + + +## Sharding.ShardExecutor.UseHttpDecompression + +Allow the orchestrator to accept and decompress compressed HTTP responses from the shards. + +- **Type**: `bool` +- **Default**: `false` +- **Scope**: Server-wide only + + diff --git a/docs/sharding/import-and-export.mdx b/docs/sharding/import-and-export.mdx index bdf3c9df16..49cd9d5fd0 100644 --- a/docs/sharding/import-and-export.mdx +++ b/docs/sharding/import-and-export.mdx @@ -12,7 +12,6 @@ import CodeBlock from '@theme/CodeBlock'; import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -# Sharding: Import and Export * Smuggler is a RavenDB interface with which data can be @@ -34,12 +33,13 @@ import LanguageContent from "@site/src/components/LanguageContent"; done with a non-sharded database. Behind the scenes, Studio uses Smuggler to perform these operations. -* In this page: +* In this article: * [Export](../sharding/import-and-export.mdx#export) * [Import](../sharding/import-and-export.mdx#import) * [Export and Import Options Summary](../sharding/import-and-export.mdx#export-and-import-options-summary) + ## Export When smuggler is called to @@ -63,18 +63,17 @@ in a `ShardedSmugglerResult` type. This type is specific to a sharded database, and casting it using a non-sharded type [will fail](../migration/client-api/previous-versions-client-breaking-changes.mdx#casting-smuggler-results). - - ## Import Smuggler can be used to [import](../client-api/smuggler/what-is-smuggler.mdx#import) data into a database from either a [.ravendbdump](../sharding/import-and-export.mdx#export) file or from backup files (full or incremental). -When data is imported into a sharded database one of the shard nodes -is appointed **orchestrator**; the orchestrator retrieves items from -the `.ravendbdump` or backup files, gathers the imported items into -batches, and distributes them among the shards. +When data is imported into a sharded database one of the shard nodes is appointed **orchestrator**; the orchestrator retrieves items from +the `.ravendbdump` or backup files, gathers the imported items into batches, and distributes them among the shards. + +The compression level applied to the import streams the orchestrator sends to the shards can be set with the +[Sharding.Import.CompressionLevel](../sharding/configuration.mdx#shardingimportcompressionlevel) configuration key. ## Importing data from a `.ravendbdump` file @@ -125,8 +124,6 @@ contain only the changes that have been made in the database since the last full Import the full backup first, and then the incremental backups that complement it. - - ## Export and Import Options Summary | Option | Available on a Sharded Database | Comment | @@ -139,8 +136,4 @@ Import the full backup first, and then the incremental backups that complement i | Import from a `.ravendbdump` file | **Yes** | An orchestrator is appointed to distribute the data among the shards. | | Import from **Backup files** | **Yes** | **Importing** data from a backup file does **not** create a new database like running the [restore process](../sharding/backup-and-restore/restore.mdx) over the backup file would, but **adds the data** to the existing database by distributing it among the shards. | | Import from **Full backup files** | **Yes** | | -| Import from **Incremental backup files** | **Yes** | | - - - - +| Import from **Incremental backup files** | **Yes** | | \ No newline at end of file diff --git a/docs/sharding/overview.mdx b/docs/sharding/overview.mdx index 14f5b204b8..a15860eab8 100644 --- a/docs/sharding/overview.mdx +++ b/docs/sharding/overview.mdx @@ -12,7 +12,6 @@ import CodeBlock from '@theme/CodeBlock'; import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; -# Sharding Overview * Sharding, supported by RavenDB from version 6.0 onward, is the distribution of a database's content among autonomous **Shards**, @@ -24,7 +23,7 @@ import LanguageContent from "@site/src/components/LanguageContent"; * In most cases, sharding allows the efficient usage and management of exceptionally large databases (e.g., a 10-terabyte DB). -* In this page: +* In this article: * [Sharding](../sharding/overview.mdx#sharding) * [Licensing](../sharding/overview.mdx#licensing) * [Client compatibility](../sharding/overview.mdx#client-compatibility) @@ -42,6 +41,7 @@ import LanguageContent from "@site/src/components/LanguageContent"; * [Creating a sharded database](../sharding/overview.mdx#creating-a-sharded-database) + ## Sharding As a database grows [very large](https://en.wikipedia.org/wiki/Very_large_database), storing and managing it may become too demanding for any single node. @@ -52,6 +52,7 @@ With sharding, as the volume of stored data grows, the database can be scaled ou This allows the database to be managed by multiple nodes and effectively removes most limits on its growth. In this manner, the size of the overall database, comprised of all shards, can reach dozens of terabytes and more, while keeping the resources of each shard in check and maintaining high performance and throughput. + #### Licensing @@ -61,6 +62,7 @@ Sharding is fully available with the **Enterprise** license. * On a **Developer** license, the replication factor is restricted to 1. * On **Community** and **Professional** licenses, all shards must be on the same node. * Learn more about licensing [here](../licensing/overview.mdx). + #### Client compatibility Sharding is managed by the RavenDB server; @@ -72,6 +74,7 @@ clients require no special adaptation when accessing a sharded database: Specific modifications to RavenDB features in a sharded environment are documented in detail in feature-specific articles. + #### Client-Server communication When a client connects to a sharded database, it is appointed a RavenDB server that functions as an **orchestrator**, @@ -79,7 +82,13 @@ mediating all the communication between the client and the database shards. The client remains unaware of this process and uses the same API used by non-sharded databases to load documents, query, and perform other operations. Note that this additional communication between the client and the orchestrator, as well as between the orchestrator and the shards, -introduces some overhead compared to using a non-sharded database. +introduces some overhead compared to using a non-sharded database. + +The HTTP traffic between the orchestrator and the shards can be compressed +(see [Sharding.ShardExecutor.UseHttpCompression](../sharding/configuration.mdx#shardingshardexecutorusehttpcompression) +and [Sharding.ShardExecutor.UseHttpDecompression](../sharding/configuration.mdx#shardingshardexecutorusehttpdecompression)), +and a timeout can be set on the orchestrator's requests to the shards (see [Sharding.OrchestratorTimeoutInMin](../sharding/configuration.mdx#shardingorchestratortimeoutinmin)). + #### When should sharding be used? While sharding solves many issues related to the storage and management of high-volume databases, @@ -103,13 +112,13 @@ is in the vicinity of 250 GB, so the transition is already well established when - ## Shards While each cluster node of a non-sharded database handles a full replica of the entire database, each **shard** is assigned a **subset** of the entire database content. + For example: Take a 3-shard database, in which shard **1** is populated with documents `Users/1`..`Users/2000`, @@ -119,6 +128,7 @@ A client that connects to this database to retrieve `Users/3000` and `Users/5000 automatically-appointed [orchestrator node](../sharding/overview.mdx#client-server-communication) that would seamlessly retrieve `Users/3000` from shard **2** and `Users/5000` from shard **3** and hand them to the client. + As far as clients are concerned, a sharded database is still a single entity: @@ -131,6 +141,7 @@ a client can, for example, track the shard where a document is stored and query Studio can be used to relocate ([reshard](../sharding/resharding.mdx)) documents from one shard to another. !["Studio Document View"](./assets/overview_document-view.png) + #### Shard replication Similar to non-sharded databases, shards can be **replicated** across cluster nodes to ensure the continuous availability @@ -145,13 +156,13 @@ The number of nodes a shard is replicated to is determined by the **Shard Replic * The Shard Replication Factor is set to 2, maintaining two replicas of each shard. - - ## How documents are distributed among shards #### Buckets + Documents in a sharded database are stored within virtual containers called **buckets**. -The number of documents and the amount of data stored in each bucket may vary. +The number of documents and the amount of data stored in each bucket may vary. + #### Buckets allocation Upon creating a sharded database, the cluster reserves **1,048,576** (1024 x 1024) buckets for the entire database. @@ -159,6 +170,7 @@ Each shard is assigned a range of buckets from this overall set, where documents (Note: This default reservation method differs when using prefixed sharding. Learn more in [Bucket management](../sharding/administration/sharding-by-prefix.mdx#bucket-management)). !["Buckets Allocation"](./assets/overview_buckets-allocation.png) + #### Buckets population The cluster automatically populates the buckets with documents in the following way: @@ -185,13 +197,12 @@ the bucket number assigned to a document also determines which shard the documen Learn more in [Sharding by prefix](../sharding/administration/sharding-by-prefix.mdx). + #### Document extensions storage Document extensions (i.e. Attachments, Time series, Counters, and Revisions) are stored in the same bucket as the document they belong to. To achieve this, the bucket number (hash code) for these extensions is calculated using the ID of the document that owns them. - - ## Resharding [Resharding](../sharding/resharding.mdx) is the relocation of data from one shard to another to maintain a balanced database, @@ -210,10 +221,9 @@ For example: * Move all the data that belongs to this bucket to shard **2**. * Associate bucket `100,000` with shard **2**. * From now on, any data added to this bucket will be stored in shard **2**. + - - ## Paging From the client's perspective, [paging](../indexes/querying/paging.mdx) is conducted similarly in both sharded and non-sharded databases, @@ -224,8 +234,6 @@ and sort the retrieved results before handing the selected page to the client. Read more about paging [here](../sharding/querying.mdx#paging). - - ## Using local IP addresses The local IP address of a cluster node can be exposed, allowing other cluster nodes to prioritize it over the public IP address when accessing the node. @@ -236,8 +244,6 @@ that may need to communicate with all other shards to process the request and it Use [this configuration option](../server/configuration/core-configuration.mdx#serverurlcluster) to expose a node's local IP address to other nodes. - - ## Creating a sharded database * When a database is created, the user can choose whether it will be sharded or not. @@ -245,7 +251,4 @@ Use [this configuration option](../server/configuration/core-configuration.mdx#s * A sharded database can be created via the [Studio](../sharding/administration/studio-admin.mdx#creating-a-sharded-database) or the [Client API](../sharding/administration/api-admin.mdx). -* A RavenDB cluster can run both sharded and non-sharded databases in parallel. - - - +* A RavenDB cluster can run both sharded and non-sharded databases in parallel. \ No newline at end of file From 6012f848b5c71b1eea155441daf4653db73d70ad Mon Sep 17 00:00:00 2001 From: Danielle9897 Date: Sun, 14 Jun 2026 13:31:32 +0300 Subject: [PATCH 2/2] RDoc-3333 Apply updates to v7.1, v7.0, & v6.2 --- .../content/_conventions-csharp.mdx | 37 +++++++++ .../version-6.2/sharding/configuration.mdx | 77 +++++++++++++++++++ .../sharding/import-and-export.mdx | 3 + .../version-6.2/sharding/overview.mdx | 6 ++ .../content/_conventions-csharp.mdx | 37 +++++++++ .../version-7.0/sharding/configuration.mdx | 77 +++++++++++++++++++ .../sharding/import-and-export.mdx | 3 + .../version-7.0/sharding/overview.mdx | 6 ++ .../content/_conventions-csharp.mdx | 37 +++++++++ .../version-7.1/sharding/configuration.mdx | 77 +++++++++++++++++++ .../sharding/import-and-export.mdx | 3 + .../version-7.1/sharding/overview.mdx | 6 ++ 12 files changed, 369 insertions(+) create mode 100644 versioned_docs/version-6.2/sharding/configuration.mdx create mode 100644 versioned_docs/version-7.0/sharding/configuration.mdx create mode 100644 versioned_docs/version-7.1/sharding/configuration.mdx diff --git a/versioned_docs/version-6.2/client-api/configuration/content/_conventions-csharp.mdx b/versioned_docs/version-6.2/client-api/configuration/content/_conventions-csharp.mdx index e894090c1b..40a8dab6fe 100644 --- a/versioned_docs/version-6.2/client-api/configuration/content/_conventions-csharp.mdx +++ b/versioned_docs/version-6.2/client-api/configuration/content/_conventions-csharp.mdx @@ -31,6 +31,7 @@ import CodeBlock from '@theme/CodeBlock'; [FindPropertyNameForDynamicIndex](../../../client-api/configuration/conventions.mdx#findpropertynamefordynamicindex) [FindPropertyNameForIndex](../../../client-api/configuration/conventions.mdx#findpropertynameforindex) [FirstBroadcastAttemptTimeout](../../../client-api/configuration/conventions.mdx#firstbroadcastattempttimeout) + [GlobalHttpClientTimeout](../../../client-api/configuration/conventions.mdx#globalhttpclienttimeout) [HttpClientType](../../../client-api/configuration/conventions.mdx#httpclienttype) [HttpPooledConnectionIdleTimeout](../../../client-api/configuration/conventions.mdx#httppooledconnectionidletimeout) [HttpPooledConnectionLifetime](../../../client-api/configuration/conventions.mdx#httppooledconnectionlifetime) @@ -704,6 +705,42 @@ public TimeSpan FirstBroadcastAttemptTimeout \{ get; set; \} +#### GlobalHttpClientTimeout + +* Use the `GlobalHttpClientTimeout` convention to set the maximum time the underlying `HttpClient` can spend on a single HTTP request. + If a request takes longer than this value, the request times out and the client reports an error. + This setting does not control how long an idle TCP connection remains open; it limits how long the client waits for an HTTP request to complete. + +* This value also serves as the maximum allowed timeout for request-executor timeouts, + such as [RequestTimeout](../../../client-api/configuration/conventions.mdx#requesttimeout), + [FirstBroadcastAttemptTimeout](../../../client-api/configuration/conventions.mdx#firstbroadcastattempttimeout), + [SecondBroadcastAttemptTimeout](../../../client-api/configuration/conventions.mdx#secondbroadcastattempttimeout), and per-request command timeouts. + Setting any of these to a value greater than `GlobalHttpClientTimeout` will throw an exception. + +* In client code, set `GlobalHttpClientTimeout` to be greater than or equal to the longest request timeout you plan to use. + For example, if you set `RequestTimeout` or a per-request timeout to 24 hours, `GlobalHttpClientTimeout` must also be at least 24 hours. + +* Set the value to `Timeout.InfiniteTimeSpan` to remove this upper-bound restriction. + +* DEFAULT: `12 hours` + + + +{`GlobalHttpClientTimeout = TimeSpan.FromHours(6) +`} + + + + +{`// Syntax: +public TimeSpan GlobalHttpClientTimeout \{ get; set; \} +`} + + + + + + #### HttpClientType * Use the `HttpClientType` convention to set the type of HTTP client you're using. diff --git a/versioned_docs/version-6.2/sharding/configuration.mdx b/versioned_docs/version-6.2/sharding/configuration.mdx new file mode 100644 index 0000000000..a74065efc8 --- /dev/null +++ b/versioned_docs/version-6.2/sharding/configuration.mdx @@ -0,0 +1,77 @@ +--- +title: "Sharding: Configuration Options" +description: "Configure RavenDB sharding options for sharded import stream compression, orchestrator request timeouts, and shard executor HTTP compression." +sidebar_label: Configuration +sidebar_position: 13 +--- + +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; +import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; +import LanguageContent from "@site/src/components/LanguageContent"; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; + + + +* The following configuration options control sharded import stream compression and HTTP communication between the orchestrator and the shards. + + Learn how to apply configuration options in [Configuration Overview](../server/configuration/configuration-options.mdx). + +* In this article: + * [Sharding.Import.CompressionLevel](../sharding/configuration.mdx#shardingimportcompressionlevel) + * [Sharding.OrchestratorTimeoutInMin](../sharding/configuration.mdx#shardingorchestratortimeoutinmin) + * [Sharding.ShardExecutor.UseHttpCompression](../sharding/configuration.mdx#shardingshardexecutorusehttpcompression) + * [Sharding.ShardExecutor.UseHttpDecompression](../sharding/configuration.mdx#shardingshardexecutorusehttpdecompression) + + + + + +## Sharding.Import.CompressionLevel + +The compression level used when the orchestrator sends imported data to the shards during a smuggler import. + +- **Type**: `CompressionLevel` (`NoCompression`, `Optimal`, `Fastest`, `SmallestSize`) +- **Default**: `NoCompression` +- **Scope**: Server-wide or per database + + + + +## Sharding.OrchestratorTimeoutInMin + +* Sets the maximum timeout, in minutes, for HTTP requests that the orchestrator sends to shards. +* By default, this timeout is infinite, so no timeout is enforced by this setting. + +--- + +- **Type**: `int` (minutes) +- **Default**: `Infinite` (no timeout) +- **Scope**: Server-wide only + + + + +## Sharding.ShardExecutor.UseHttpCompression + +Compress HTTP request content sent by the orchestrator to the shards. + +- **Type**: `bool` +- **Default**: `false` +- **Scope**: Server-wide only + + + + +## Sharding.ShardExecutor.UseHttpDecompression + +Allow the orchestrator to accept and decompress compressed HTTP responses from the shards. + +- **Type**: `bool` +- **Default**: `false` +- **Scope**: Server-wide only + + diff --git a/versioned_docs/version-6.2/sharding/import-and-export.mdx b/versioned_docs/version-6.2/sharding/import-and-export.mdx index 386dda8b75..07d9b1faa2 100644 --- a/versioned_docs/version-6.2/sharding/import-and-export.mdx +++ b/versioned_docs/version-6.2/sharding/import-and-export.mdx @@ -75,6 +75,9 @@ is appointed **orchestrator**; the orchestrator retrieves items from the `.ravendbdump` or backup files, gathers the imported items into batches, and distributes them among the shards. +The compression level applied to the import streams the orchestrator sends to the shards can be set with the +[Sharding.Import.CompressionLevel](../sharding/configuration.mdx#shardingimportcompressionlevel) configuration key. + ## Importing data from a `.ravendbdump` file There are no preliminary requirements regarding the structure diff --git a/versioned_docs/version-6.2/sharding/overview.mdx b/versioned_docs/version-6.2/sharding/overview.mdx index fda978484c..7b95f92ad2 100644 --- a/versioned_docs/version-6.2/sharding/overview.mdx +++ b/versioned_docs/version-6.2/sharding/overview.mdx @@ -79,6 +79,12 @@ The client remains unaware of this process and uses the same API used by non-sha Note that this additional communication between the client and the orchestrator, as well as between the orchestrator and the shards, introduces some overhead compared to using a non-sharded database. + +The HTTP traffic between the orchestrator and the shards can be compressed +(see [Sharding.ShardExecutor.UseHttpCompression](../sharding/configuration.mdx#shardingshardexecutorusehttpcompression) +and [Sharding.ShardExecutor.UseHttpDecompression](../sharding/configuration.mdx#shardingshardexecutorusehttpdecompression)), +and a timeout can be set on the orchestrator's requests to the shards (see [Sharding.OrchestratorTimeoutInMin](../sharding/configuration.mdx#shardingorchestratortimeoutinmin)). + #### When should sharding be used? While sharding solves many issues related to the storage and management of high-volume databases, diff --git a/versioned_docs/version-7.0/client-api/configuration/content/_conventions-csharp.mdx b/versioned_docs/version-7.0/client-api/configuration/content/_conventions-csharp.mdx index b089437962..7d71befeaf 100644 --- a/versioned_docs/version-7.0/client-api/configuration/content/_conventions-csharp.mdx +++ b/versioned_docs/version-7.0/client-api/configuration/content/_conventions-csharp.mdx @@ -31,6 +31,7 @@ import CodeBlock from '@theme/CodeBlock'; [FindPropertyNameForDynamicIndex](../../../client-api/configuration/conventions.mdx#findpropertynamefordynamicindex) [FindPropertyNameForIndex](../../../client-api/configuration/conventions.mdx#findpropertynameforindex) [FirstBroadcastAttemptTimeout](../../../client-api/configuration/conventions.mdx#firstbroadcastattempttimeout) + [GlobalHttpClientTimeout](../../../client-api/configuration/conventions.mdx#globalhttpclienttimeout) [HttpClientType](../../../client-api/configuration/conventions.mdx#httpclienttype) [HttpPooledConnectionIdleTimeout](../../../client-api/configuration/conventions.mdx#httppooledconnectionidletimeout) [HttpPooledConnectionLifetime](../../../client-api/configuration/conventions.mdx#httppooledconnectionlifetime) @@ -706,6 +707,42 @@ public TimeSpan FirstBroadcastAttemptTimeout \{ get; set; \} +#### GlobalHttpClientTimeout + +* Use the `GlobalHttpClientTimeout` convention to set the maximum time the underlying `HttpClient` can spend on a single HTTP request. + If a request takes longer than this value, the request times out and the client reports an error. + This setting does not control how long an idle TCP connection remains open; it limits how long the client waits for an HTTP request to complete. + +* This value also serves as the maximum allowed timeout for request-executor timeouts, + such as [RequestTimeout](../../../client-api/configuration/conventions.mdx#requesttimeout), + [FirstBroadcastAttemptTimeout](../../../client-api/configuration/conventions.mdx#firstbroadcastattempttimeout), + [SecondBroadcastAttemptTimeout](../../../client-api/configuration/conventions.mdx#secondbroadcastattempttimeout), and per-request command timeouts. + Setting any of these to a value greater than `GlobalHttpClientTimeout` will throw an exception. + +* In client code, set `GlobalHttpClientTimeout` to be greater than or equal to the longest request timeout you plan to use. + For example, if you set `RequestTimeout` or a per-request timeout to 24 hours, `GlobalHttpClientTimeout` must also be at least 24 hours. + +* Set the value to `Timeout.InfiniteTimeSpan` to remove this upper-bound restriction. + +* DEFAULT: `12 hours` + + + +{`GlobalHttpClientTimeout = TimeSpan.FromHours(6) +`} + + + + +{`// Syntax: +public TimeSpan GlobalHttpClientTimeout \{ get; set; \} +`} + + + + + + #### HttpClientType * Use the `HttpClientType` convention to set the type of HTTP client you're using. diff --git a/versioned_docs/version-7.0/sharding/configuration.mdx b/versioned_docs/version-7.0/sharding/configuration.mdx new file mode 100644 index 0000000000..a74065efc8 --- /dev/null +++ b/versioned_docs/version-7.0/sharding/configuration.mdx @@ -0,0 +1,77 @@ +--- +title: "Sharding: Configuration Options" +description: "Configure RavenDB sharding options for sharded import stream compression, orchestrator request timeouts, and shard executor HTTP compression." +sidebar_label: Configuration +sidebar_position: 13 +--- + +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; +import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; +import LanguageContent from "@site/src/components/LanguageContent"; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; + + + +* The following configuration options control sharded import stream compression and HTTP communication between the orchestrator and the shards. + + Learn how to apply configuration options in [Configuration Overview](../server/configuration/configuration-options.mdx). + +* In this article: + * [Sharding.Import.CompressionLevel](../sharding/configuration.mdx#shardingimportcompressionlevel) + * [Sharding.OrchestratorTimeoutInMin](../sharding/configuration.mdx#shardingorchestratortimeoutinmin) + * [Sharding.ShardExecutor.UseHttpCompression](../sharding/configuration.mdx#shardingshardexecutorusehttpcompression) + * [Sharding.ShardExecutor.UseHttpDecompression](../sharding/configuration.mdx#shardingshardexecutorusehttpdecompression) + + + + + +## Sharding.Import.CompressionLevel + +The compression level used when the orchestrator sends imported data to the shards during a smuggler import. + +- **Type**: `CompressionLevel` (`NoCompression`, `Optimal`, `Fastest`, `SmallestSize`) +- **Default**: `NoCompression` +- **Scope**: Server-wide or per database + + + + +## Sharding.OrchestratorTimeoutInMin + +* Sets the maximum timeout, in minutes, for HTTP requests that the orchestrator sends to shards. +* By default, this timeout is infinite, so no timeout is enforced by this setting. + +--- + +- **Type**: `int` (minutes) +- **Default**: `Infinite` (no timeout) +- **Scope**: Server-wide only + + + + +## Sharding.ShardExecutor.UseHttpCompression + +Compress HTTP request content sent by the orchestrator to the shards. + +- **Type**: `bool` +- **Default**: `false` +- **Scope**: Server-wide only + + + + +## Sharding.ShardExecutor.UseHttpDecompression + +Allow the orchestrator to accept and decompress compressed HTTP responses from the shards. + +- **Type**: `bool` +- **Default**: `false` +- **Scope**: Server-wide only + + diff --git a/versioned_docs/version-7.0/sharding/import-and-export.mdx b/versioned_docs/version-7.0/sharding/import-and-export.mdx index 386dda8b75..07d9b1faa2 100644 --- a/versioned_docs/version-7.0/sharding/import-and-export.mdx +++ b/versioned_docs/version-7.0/sharding/import-and-export.mdx @@ -75,6 +75,9 @@ is appointed **orchestrator**; the orchestrator retrieves items from the `.ravendbdump` or backup files, gathers the imported items into batches, and distributes them among the shards. +The compression level applied to the import streams the orchestrator sends to the shards can be set with the +[Sharding.Import.CompressionLevel](../sharding/configuration.mdx#shardingimportcompressionlevel) configuration key. + ## Importing data from a `.ravendbdump` file There are no preliminary requirements regarding the structure diff --git a/versioned_docs/version-7.0/sharding/overview.mdx b/versioned_docs/version-7.0/sharding/overview.mdx index fda978484c..7b95f92ad2 100644 --- a/versioned_docs/version-7.0/sharding/overview.mdx +++ b/versioned_docs/version-7.0/sharding/overview.mdx @@ -79,6 +79,12 @@ The client remains unaware of this process and uses the same API used by non-sha Note that this additional communication between the client and the orchestrator, as well as between the orchestrator and the shards, introduces some overhead compared to using a non-sharded database. + +The HTTP traffic between the orchestrator and the shards can be compressed +(see [Sharding.ShardExecutor.UseHttpCompression](../sharding/configuration.mdx#shardingshardexecutorusehttpcompression) +and [Sharding.ShardExecutor.UseHttpDecompression](../sharding/configuration.mdx#shardingshardexecutorusehttpdecompression)), +and a timeout can be set on the orchestrator's requests to the shards (see [Sharding.OrchestratorTimeoutInMin](../sharding/configuration.mdx#shardingorchestratortimeoutinmin)). + #### When should sharding be used? While sharding solves many issues related to the storage and management of high-volume databases, diff --git a/versioned_docs/version-7.1/client-api/configuration/content/_conventions-csharp.mdx b/versioned_docs/version-7.1/client-api/configuration/content/_conventions-csharp.mdx index b089437962..7d71befeaf 100644 --- a/versioned_docs/version-7.1/client-api/configuration/content/_conventions-csharp.mdx +++ b/versioned_docs/version-7.1/client-api/configuration/content/_conventions-csharp.mdx @@ -31,6 +31,7 @@ import CodeBlock from '@theme/CodeBlock'; [FindPropertyNameForDynamicIndex](../../../client-api/configuration/conventions.mdx#findpropertynamefordynamicindex) [FindPropertyNameForIndex](../../../client-api/configuration/conventions.mdx#findpropertynameforindex) [FirstBroadcastAttemptTimeout](../../../client-api/configuration/conventions.mdx#firstbroadcastattempttimeout) + [GlobalHttpClientTimeout](../../../client-api/configuration/conventions.mdx#globalhttpclienttimeout) [HttpClientType](../../../client-api/configuration/conventions.mdx#httpclienttype) [HttpPooledConnectionIdleTimeout](../../../client-api/configuration/conventions.mdx#httppooledconnectionidletimeout) [HttpPooledConnectionLifetime](../../../client-api/configuration/conventions.mdx#httppooledconnectionlifetime) @@ -706,6 +707,42 @@ public TimeSpan FirstBroadcastAttemptTimeout \{ get; set; \} +#### GlobalHttpClientTimeout + +* Use the `GlobalHttpClientTimeout` convention to set the maximum time the underlying `HttpClient` can spend on a single HTTP request. + If a request takes longer than this value, the request times out and the client reports an error. + This setting does not control how long an idle TCP connection remains open; it limits how long the client waits for an HTTP request to complete. + +* This value also serves as the maximum allowed timeout for request-executor timeouts, + such as [RequestTimeout](../../../client-api/configuration/conventions.mdx#requesttimeout), + [FirstBroadcastAttemptTimeout](../../../client-api/configuration/conventions.mdx#firstbroadcastattempttimeout), + [SecondBroadcastAttemptTimeout](../../../client-api/configuration/conventions.mdx#secondbroadcastattempttimeout), and per-request command timeouts. + Setting any of these to a value greater than `GlobalHttpClientTimeout` will throw an exception. + +* In client code, set `GlobalHttpClientTimeout` to be greater than or equal to the longest request timeout you plan to use. + For example, if you set `RequestTimeout` or a per-request timeout to 24 hours, `GlobalHttpClientTimeout` must also be at least 24 hours. + +* Set the value to `Timeout.InfiniteTimeSpan` to remove this upper-bound restriction. + +* DEFAULT: `12 hours` + + + +{`GlobalHttpClientTimeout = TimeSpan.FromHours(6) +`} + + + + +{`// Syntax: +public TimeSpan GlobalHttpClientTimeout \{ get; set; \} +`} + + + + + + #### HttpClientType * Use the `HttpClientType` convention to set the type of HTTP client you're using. diff --git a/versioned_docs/version-7.1/sharding/configuration.mdx b/versioned_docs/version-7.1/sharding/configuration.mdx new file mode 100644 index 0000000000..a74065efc8 --- /dev/null +++ b/versioned_docs/version-7.1/sharding/configuration.mdx @@ -0,0 +1,77 @@ +--- +title: "Sharding: Configuration Options" +description: "Configure RavenDB sharding options for sharded import stream compression, orchestrator request timeouts, and shard executor HTTP compression." +sidebar_label: Configuration +sidebar_position: 13 +--- + +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; +import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; +import LanguageContent from "@site/src/components/LanguageContent"; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; + + + +* The following configuration options control sharded import stream compression and HTTP communication between the orchestrator and the shards. + + Learn how to apply configuration options in [Configuration Overview](../server/configuration/configuration-options.mdx). + +* In this article: + * [Sharding.Import.CompressionLevel](../sharding/configuration.mdx#shardingimportcompressionlevel) + * [Sharding.OrchestratorTimeoutInMin](../sharding/configuration.mdx#shardingorchestratortimeoutinmin) + * [Sharding.ShardExecutor.UseHttpCompression](../sharding/configuration.mdx#shardingshardexecutorusehttpcompression) + * [Sharding.ShardExecutor.UseHttpDecompression](../sharding/configuration.mdx#shardingshardexecutorusehttpdecompression) + + + + + +## Sharding.Import.CompressionLevel + +The compression level used when the orchestrator sends imported data to the shards during a smuggler import. + +- **Type**: `CompressionLevel` (`NoCompression`, `Optimal`, `Fastest`, `SmallestSize`) +- **Default**: `NoCompression` +- **Scope**: Server-wide or per database + + + + +## Sharding.OrchestratorTimeoutInMin + +* Sets the maximum timeout, in minutes, for HTTP requests that the orchestrator sends to shards. +* By default, this timeout is infinite, so no timeout is enforced by this setting. + +--- + +- **Type**: `int` (minutes) +- **Default**: `Infinite` (no timeout) +- **Scope**: Server-wide only + + + + +## Sharding.ShardExecutor.UseHttpCompression + +Compress HTTP request content sent by the orchestrator to the shards. + +- **Type**: `bool` +- **Default**: `false` +- **Scope**: Server-wide only + + + + +## Sharding.ShardExecutor.UseHttpDecompression + +Allow the orchestrator to accept and decompress compressed HTTP responses from the shards. + +- **Type**: `bool` +- **Default**: `false` +- **Scope**: Server-wide only + + diff --git a/versioned_docs/version-7.1/sharding/import-and-export.mdx b/versioned_docs/version-7.1/sharding/import-and-export.mdx index 386dda8b75..07d9b1faa2 100644 --- a/versioned_docs/version-7.1/sharding/import-and-export.mdx +++ b/versioned_docs/version-7.1/sharding/import-and-export.mdx @@ -75,6 +75,9 @@ is appointed **orchestrator**; the orchestrator retrieves items from the `.ravendbdump` or backup files, gathers the imported items into batches, and distributes them among the shards. +The compression level applied to the import streams the orchestrator sends to the shards can be set with the +[Sharding.Import.CompressionLevel](../sharding/configuration.mdx#shardingimportcompressionlevel) configuration key. + ## Importing data from a `.ravendbdump` file There are no preliminary requirements regarding the structure diff --git a/versioned_docs/version-7.1/sharding/overview.mdx b/versioned_docs/version-7.1/sharding/overview.mdx index fda978484c..7b95f92ad2 100644 --- a/versioned_docs/version-7.1/sharding/overview.mdx +++ b/versioned_docs/version-7.1/sharding/overview.mdx @@ -79,6 +79,12 @@ The client remains unaware of this process and uses the same API used by non-sha Note that this additional communication between the client and the orchestrator, as well as between the orchestrator and the shards, introduces some overhead compared to using a non-sharded database. + +The HTTP traffic between the orchestrator and the shards can be compressed +(see [Sharding.ShardExecutor.UseHttpCompression](../sharding/configuration.mdx#shardingshardexecutorusehttpcompression) +and [Sharding.ShardExecutor.UseHttpDecompression](../sharding/configuration.mdx#shardingshardexecutorusehttpdecompression)), +and a timeout can be set on the orchestrator's requests to the shards (see [Sharding.OrchestratorTimeoutInMin](../sharding/configuration.mdx#shardingorchestratortimeoutinmin)). + #### When should sharding be used? While sharding solves many issues related to the storage and management of high-volume databases,