add information about column order in monolith (#6094)

sanderson · web-flow · commit dc533920f1b5 · 2025-05-27T15:15:54.000-05:00
diff --git a/content/influxdb3/core/write-data/best-practices/optimize-writes.md b/content/influxdb3/core/write-data/best-practices/optimize-writes.md
@@ -16,5 +16,6 @@ source: /shared/influxdb3-write-guides/best-practices/optimize-writes.md
 ---
 
 <!--
-The content for this page is at content/shared/influxdb3-write-guides/best-practices/optimize-writes.md
+The content for this page is at
+//SOURCE content/shared/influxdb3-write-guides/best-practices/optimize-writes.md
 -->
diff --git a/content/influxdb3/core/write-data/best-practices/schema-design.md b/content/influxdb3/core/write-data/best-practices/schema-design.md
@@ -16,5 +16,6 @@ source: /shared/influxdb3-write-guides/best-practices/schema-design.md
 ---
 
 <!--
-The content for this page is at content/shared/influxdb3-write-guides/best-practices/schema-design.md
+The content for this page is at
+//SOURCE content/shared/influxdb3-write-guides/best-practices/schema-design.md
 -->
diff --git a/content/influxdb3/enterprise/write-data/best-practices/optimize-writes.md b/content/influxdb3/enterprise/write-data/best-practices/optimize-writes.md
@@ -16,5 +16,6 @@ source: /shared/influxdb3-write-guides/best-practices/optimize-writes.md
 ---
 
 <!--
-The content for this page is at content/shared/influxdb3-write-guides/best-practices/optimize-writes.md
+The content for this page is at
+//SOURCE content/shared/influxdb3-write-guides/best-practices/optimize-writes.md
 -->
diff --git a/content/influxdb3/enterprise/write-data/best-practices/schema-design.md b/content/influxdb3/enterprise/write-data/best-practices/schema-design.md
@@ -16,5 +16,6 @@ source: /shared/influxdb3-write-guides/best-practices/schema-design.md
 ---
 
 <!--
-The content for this page is at content/shared/influxdb3-write-guides/best-practices/schema-design.md
+The content for this page is at
+//SOURCE content/shared/influxdb3-write-guides/best-practices/schema-design.md
 -->
diff --git a/content/shared/influxdb3-write-guides/best-practices/optimize-writes.md b/content/shared/influxdb3-write-guides/best-practices/optimize-writes.md
@@ -3,7 +3,8 @@ Use these tips to optimize performance and system overhead when writing data to
 {{< product-name >}}.
 
 - [Batch writes](#batch-writes)
-- [Sort tags by key](#sort-tags-by-key)
+{{% hide-in "enterprise,core" %}}- [Sort tags by key](#sort-tags-by-key){{% /hide-in %}}
+{{% show-in "enterprise,core" %}}- [On first write, sort tags by query priority](#on-first-write-sort-tags-by-query-priority){{% /show-in %}}
 - [Use the coarsest time precision possible](#use-the-coarsest-time-precision-possible)
 - [Use gzip compression](#use-gzip-compression)
   - [Enable gzip compression in Telegraf](#enable-gzip-compression-in-telegraf)
@@ -34,6 +35,8 @@ Write data in batches to minimize network overhead when writing data to InfluxDB
 > The optimal batch size is 10,000 lines of line protocol or 10 MBs, whichever
 > threshold is met first.
 
+{{% hide-in "enterprise,core" %}}
+
 ## Sort tags by key
 
 Before writing data points to InfluxDB, sort tags by key in lexicographic order.
@@ -49,6 +52,31 @@ measurement,tagC=therefore,tagE=am,tagA=i,tagD=i,tagB=think fieldKey=fieldValue
 measurement,tagA=i,tagB=think,tagC=therefore,tagD=i,tagE=am fieldKey=fieldValue 1562020262
 ```
 
+{{% /hide-in %}}
+
+{{% show-in "enterprise,core" %}}
+
+## On first write, sort tags by query priority
+
+The first write to a table in {{% product-name %}} determines the physical column
+order in storage, and that order has a direct impact on query performance.
+Columns that appear earlier are typically faster to filter and access during
+query execution.
+
+Sort your tags by query priority when performing the initial write to a table.
+Place the most commonly queried tags first—those you frequently use in `WHERE`
+clauses or joins—followed by less frequently queried ones. For example, if most
+of your queries filter by `region` and then by `host`, structure your first
+write so that `region` comes before `host`.
+
+> [!Important]
+> Column order is determined on the first write and cannot be changed afterward.
+> Tags added after the first write are added last in the column sort order.
+> Plan your schema with your query workload in mind to ensure the best long-term
+> performance.
+
+{{% /show-in %}}
+
 ## Use the coarsest time precision possible
 
 {{< product-name >}} supports up to nanosecond timestamp precision. However,
diff --git a/content/shared/influxdb3-write-guides/best-practices/schema-design.md b/content/shared/influxdb3-write-guides/best-practices/schema-design.md
@@ -9,6 +9,7 @@ for simpler and more performant queries.
   - [Do not use duplicate names for tags and fields](#do-not-use-duplicate-names-for-tags-and-fields)
   - [Maximum number of columns per table](#maximum-number-of-columns-per-table)
 - [Design for performance](#design-for-performance)
+  {{% show-in "enterprise,core" %}}- [Sort tags by query priority](#sort-tags-by-query-priority){{% /show-in %}}
   - [Avoid wide schemas](#avoid-wide-schemas)
   - [Avoid sparse schemas](#avoid-sparse-schemas)
   - [Table schemas should be homogenous](#table-schemas-should-be-homogenous)
@@ -135,11 +136,35 @@ the performance of queries against that table.
 
 The following guidelines help to optimize query performance:
 
+{{% show-in "enterprise,core" %}}- [Sort tags by query priority](#sort-tags-by-query-priority){{% /show-in %}}
 - [Avoid wide schemas](#avoid-wide-schemas)
 - [Avoid sparse schemas](#avoid-sparse-schemas)
 - [Table schemas should be homogenous](#table-schemas-should-be-homogenous)
 - [Use the best data type for your data](#use-the-best-data-type-for-your-data)
 
+{{% show-in "enterprise,core" %}}
+
+### Sort tags by query priority
+
+The first write to a table in {{% product-name %}} determines the physical column
+order in storage, and that order has a direct impact on query performance.
+Columns that appear earlier are typically faster to filter and access during
+query execution.
+
+Sort your tags by query priority when performing the initial write to a table.
+Place the most commonly queried tags first—those you frequently use in `WHERE`
+clauses or joins—followed by less frequently queried ones. For example, if most
+of your queries filter by `region` and then by `host`, structure your first
+write so that `region` comes before `host`.
+
+> [!Important]
+> Column order is determined on the first write and cannot be changed afterward.
+> Tags added after the first write are added last in the column sort order.
+> Plan your schema with your query workload in mind to ensure the best long-term
+> performance.
+
+{{% /show-in %}}
+
 ### Avoid wide schemas
 
 A wide schema refers to a schema with a large number of columns (tags and fields).
