bobhan1 commented on code in PR #1510: URL: https://github.com/apache/doris-website/pull/1510#discussion_r1895600336
########## docs/table-design/auto-increment.md: ########## @@ -24,30 +24,50 @@ specific language governing permissions and limitations under the License. --> +When importing data, **Doris** automatically assigns unique values to rows that do not have specified values in the **auto-increment column**. This feature simplifies data import workflows while maintaining flexibility. -When importing data, Doris assigns a table-unique value to rows that do not have specified values in the auto-increment column. +--- ## Functionality -For tables containing an auto-increment column, during data import: -- If the target columns don't include the auto-increment column, Doris will populate the auto-increment column with generated values. -- If the target columns include the auto-increment column, null values in the imported data for that column will be replaced by values generated by Doris, while non-null values will remain unchanged. Note that **non-null values can disrupt the uniqueness of the auto-increment column values**. +For tables with an auto-increment column, Doris processes data imports as follows: + +- **Auto-Population (Column Excluded)**: + If the imported data does not include the auto-increment column, Doris generates and populates unique values for this column. + +- **Partial Specification (Column Included)**: + - **Null Values**: Doris replaces null values in the imported data with system-generated unique values. + - **Non-Null Values**: User-provided values remain unchanged. + > **Important**: User-provided non-null values can disrupt the uniqueness of the auto-increment column. + +--- ### Uniqueness -Doris ensures that values generated on the auto-increment column have **table-wide uniqueness**. However, it's important to note that **the uniqueness of the auto-increment column only guarantees uniqueness for values automatically filled by Doris and does not consider values provided by users**. If a user explicitly inserts user-provided values for this table by specifying the auto-increment column, this uniqueness cannot be guaranteed. +Doris guarantees **table-wide uniqueness** for values it generates in the auto-increment column. However: + +- **Guaranteed Uniqueness**: This applies only to system-generated values. +- **User-Provided Values**: Doris does not validate or enforce uniqueness for values specified by users in the auto-increment column. This may result in duplicate entries. + +--- ### Density -Doris ensures that the values generated on the auto-increment column are dense, but it **cannot guarantee** that the values automatically generated in the auto-increment column during an import will be entirely contiguous. Thus, there might be some jumps in the values generated by the auto-increment column during an import. This is because, for performance consideration, each BE caches a portion of pre-allocated auto-increment column values, and these cached values do not intersect between different BEs. Additionally, due to this caching mechanism, Doris cannot guarantee that the values automatically generated on the auto-increment column in a later import on the physical timeline will be larger than those from the previous import. Therefore, the values allocated by the auto-increment column cannot be used to determine the chronological order of imports. +Auto-increment values generated by Doris are generally **dense** but with some considerations: + +- **Potential Gaps**: Gaps may appear due to performance optimizations. Each backend node (BE) pre-allocates a block of unique values for efficiency, and these blocks do not overlap between nodes. +- **Non-Chronological Values**: Doris does not guarantee that values generated in later imports are larger than those from earlier imports. + > **Note**: Auto-increment values cannot be used to infer the chronological order of imports. + +--- ## Syntax To use auto-increment columns, you need to add the `AUTO_INCREMENT` attribute to the corresponding column during table creation ([CREATE-TABLE](../sql-manual/sql-statements/Data-Definition-Statements/Create/CREATE-TABLE)). To manually specify the starting value for an auto-increment column, you can do so by using the `AUTO_INCREMENT(start_value)` statement when creating the table. If not specified, the default starting value is 1. ### Examples -1. Creating a Duplicate table with one key column as an auto-increment column: +1. Creating a duplicate table with an auto-increment column as one of the key columns. Review Comment: ```suggestion 1. Creating a duplicate table with an auto-increment column as the key column. ``` There is only one key column in this example -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: commits-unsubscr...@doris.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@doris.apache.org For additional commands, e-mail: commits-h...@doris.apache.org
