Correct insert placement documentation

Author: alex-clickhouse

ClickHouse.Driver/InsertOptions.cs

@@ -46,12 +46,12 @@ public sealed class InsertOptions : QueryOptions
     /// Gets or sets where the <c>INSERT INTO ... FORMAT ...</c> statement is sent. Defaults to
     /// <see cref="InsertQueryPlacement.Body"/>, which writes it ahead of the rows in the request body.
     /// Set <see cref="InsertQueryPlacement.Url"/> to send it as the <c>query</c> URL parameter instead,
-    /// so that proxies, gateways and access logs can read it — they cannot see into the body, which
-    /// <see cref="Compressor"/> compresses by default. The statement then counts towards the URL length,
-    /// whose effective limit is the lowest imposed by the .NET runtime, an intermediary, and the server.
+    /// so URL-only routing and logging can read it without decoding and inspecting the request body,
+    /// which <see cref="Compressor"/> compresses by default. The statement then counts towards the URL
+    /// length, whose effective limit is the lowest imposed by the .NET runtime, an intermediary, and the server.
     /// On .NET 6 through .NET 9, the complete encoded URI cannot exceed 65,519 characters; the driver
     /// reports an <see cref="System.InvalidOperationException"/> suggesting <see cref="InsertQueryPlacement.Body"/>
-    /// if that limit is exceeded. The server's <c>max_uri_size</c> is 1 MiB by default. This setting is
+    /// if that limit is exceeded. The server's <c>http_max_uri_size</c> is 1 MiB by default. This setting is
     /// independent of <see cref="Compressor"/>, which governs the body encoding only.
     /// </summary>
     public InsertQueryPlacement QueryPlacement { get; init; } = InsertQueryPlacement.Body;

ClickHouse.Driver/InsertQueryPlacement.cs

@@ -6,17 +6,17 @@ namespace ClickHouse.Driver;
 public enum InsertQueryPlacement
 {
     /// <summary>
-    /// The statement is written as the first line of the request body, ahead of the rows. The body
-    /// carries the whole request, so no part of it is subject to a URL length limit.
+    /// The statement is written as the first line of the request body, ahead of the rows. The statement
+    /// and rows are not subject to a URL length limit; other request options can still appear in the URL.
     /// </summary>
     Body = 0,
 
     /// <summary>
     /// The statement is sent as the <c>query</c> URL parameter and the body carries only rows. This
-    /// makes the statement readable by proxies, gateways and access logs, which cannot see into a
-    /// compressed body. The effective URL limit is the lowest imposed by the .NET runtime, an
-    /// intermediary, and the server. On .NET 6 through .NET 9, the complete encoded URI cannot exceed
-    /// 65,519 characters; the server's <c>max_uri_size</c> is 1 MiB by default.
+    /// makes the statement available to routing and logging that inspect only the URL, without decoding
+    /// and inspecting the request body. The effective URL limit is the lowest imposed by the .NET runtime,
+    /// an intermediary, and the server. On .NET 6 through .NET 9, the complete encoded URI cannot exceed
+    /// 65,519 characters; the server's <c>http_max_uri_size</c> is 1 MiB by default.
     /// </summary>
     Url = 1,
 }

docs/overview.mdx

@@ -511,14 +511,14 @@ POCO inserts work seamlessly when columns are added to the target table after th
 
 #### Insert query placement {#insert-query-placement}
 
-A binary insert writes its `INSERT INTO ... FORMAT ...` statement as the first line of the request body, ahead of the rows. The body is compressed by default, so an intermediary cannot read the statement there. Set `InsertOptions.QueryPlacement` to `InsertQueryPlacement.Url` to send the statement as the `query` URL parameter instead, leaving the body to the rows alone:
+A binary insert writes its `INSERT INTO ... FORMAT ...` statement as the first line of the request body, ahead of the rows. The body is compressed by default, so routing and logging that inspect only the URL do not see the statement. Set `InsertOptions.QueryPlacement` to `InsertQueryPlacement.Url` to send the statement as the `query` URL parameter instead, leaving the body to the rows alone:
 
 ```csharp
 var options = new InsertOptions { QueryPlacement = InsertQueryPlacement.Url };
 await client.InsertBinaryAsync("events", columns, rows, options);
 ```
 
-Use it when a proxy, load balancer or gateway routes or inspects on the `query` parameter, or when you want the statement in access logs and observability tooling. It is opt-in because the statement then counts towards the URL length. The effective limit is the lowest imposed by the .NET runtime, an intermediary and the server. On .NET 6 through .NET 9, `System.Uri` limits the complete encoded request URI to 65,519 characters; the driver throws an `InvalidOperationException` that directs you back to `InsertQueryPlacement.Body` when this limit is exceeded. ClickHouse's `max_uri_size` is 1 MiB by default, while an intermediary may impose a lower limit. The body has no such limit.
+Use it when a proxy, load balancer or gateway routes or inspects on the `query` parameter, or when you want the statement in access logs and observability tooling. It is opt-in because the statement then counts towards the URL length. The effective limit is the lowest imposed by the .NET runtime, an intermediary and the server. On .NET 6 through .NET 9, `System.Uri` limits the complete encoded request URI to 65,519 characters; the driver throws an `InvalidOperationException` that directs you back to `InsertQueryPlacement.Body` when this limit is exceeded. ClickHouse's `http_max_uri_size` is 1 MiB by default, while an intermediary may impose a lower limit. In body mode, the statement and rows have no such URL-length limit; other request options can still appear in the URL.
 
 The setting is independent of `Compressor`: the body is encoded the same way in both modes.