Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
10 changes: 5 additions & 5 deletions docs/admin-manual/cluster-management/time-zone.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@

The time zone affects the values returned by time functions such as `NOW()` and `CURTIME()`, as well as the time values shown in `SHOW LOAD` and `SHOW BACKENDS`.

However, it does **not** affect the `LESS THAN` values of time-typed partition columns in `CREATE TABLE`, and it does not affect the displayed values of data stored as `DATE` or `DATETIME` types.
However, it does **not** affect the `LESS THAN` values of time-typed partition columns in `CREATE TABLE`, and it does not affect the displayed values of data stored as `DATE`, `DATETIME`, or `TIMESTAMP_NS` types.

Functions affected by the time zone:

Expand All @@ -107,9 +107,9 @@

### Effect on Time Types

#### DATE / DATETIME Types
#### DATE / DATETIME / TIMESTAMP_NS Types

For the `DATE` and `DATETIME` types, time zone conversion is supported during data ingestion:
For the `DATE`, `DATETIME`, and `TIMESTAMP_NS` types, time zone conversion is supported during data ingestion. `TIMESTAMP_NS` follows the same time-zone-naive storage rule as `DATETIME`, while preserving nine fractional-second digits:

- **Data with time zone**: For example, given `2020-12-12 12:12:12+08:00` and a Stream Load header `timezone` of `+00:00`, the actual value stored in Doris is `2020-12-12 04:12:12`.
- **Data without time zone**: For example, `2020-12-12 12:12:12` is treated as an absolute time, and no conversion occurs.
Expand Down Expand Up @@ -164,7 +164,7 @@
2. **Ingestion time zone**: the header `timezone` specified during Stream Load, Broker Load, and similar ingestion methods.
3. **Data time zone**: the time-zone literal in the data (for example, the `+08:00` in `2023-12-12 08:00:00+08:00`).

Doris currently supports ingesting data from any time zone into Doris. Because Doris time types such as `DATETIME` do not carry time zone information internally and the stored data does not change with the time zone after ingestion, time data ingested into Doris falls into two categories:
Doris currently supports ingesting data from any time zone into Doris. Because time types such as `DATETIME` and `TIMESTAMP_NS` do not carry time zone information internally and the stored data does not change with the time zone after ingestion, time data ingested into Doris falls into two categories:

1. **Absolute time**

Expand Down Expand Up @@ -295,7 +295,7 @@

### Q: After changing `time_zone`, the query results for existing data change unexpectedly?

Types such as `DATETIME` do not carry time zone information internally, and changing the cluster time zone after ingestion does not change the stored values. Confirm the cluster time zone before use, set `time_zone`, and do not change it afterward.
Types such as `DATETIME` and `TIMESTAMP_NS` do not carry time zone information internally, and changing the cluster time zone after ingestion does not change the stored values. Confirm the cluster time zone before use, set `time_zone`, and do not change it afterward.

### Q: The time offset of Stream Load ingested data does not match expectations?

Expand All @@ -315,6 +315,6 @@

## Further Reading

- Time zone format list: [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

Check notice on line 318 in docs/admin-manual/cluster-management/time-zone.md

View workflow job for this annotation

GitHub Actions / Build Check

link-external-report-only

External link is report-only and was not fetched%3A https%3A//en.wikipedia.org/wiki/List_of_tz_database_time_zones. Owner%3A @apache/doris-website-maintainers
- IANA Time Zone Database: [IANA Time Zone Database](https://www.iana.org/time-zones)

Check notice on line 319 in docs/admin-manual/cluster-management/time-zone.md

View workflow job for this annotation

GitHub Actions / Build Check

link-external-report-only

External link is report-only and was not fetched%3A https%3A//www.iana.org/time-zones. Owner%3A @apache/doris-website-maintainers
- ICANN Time Zone Database: [The tz-announce Archives](https://mm.icann.org/pipermail/tz-announce/)

Check notice on line 320 in docs/admin-manual/cluster-management/time-zone.md

View workflow job for this annotation

GitHub Actions / Build Check

link-external-report-only

External link is report-only and was not fetched%3A https%3A//mm.icann.org/pipermail/tz-announce/. Owner%3A @apache/doris-website-maintainers
2 changes: 1 addition & 1 deletion docs/data-operate/import/import-way/stream-load-manual.md
Original file line number Diff line number Diff line change
Expand Up @@ -511,7 +511,7 @@ curl --location-trusted -u <doris_user>:<doris_password> \

### Specify the import time zone

The `DATETIME`-related types represent only absolute points in time and do not contain time-zone information; they do not change with the Doris system time zone. Therefore, time-zone-aware data is handled in a unified way during import: it is converted to data in a specified target time zone. In the Doris system, the time zone is the one represented by the session variable `time_zone`.
Time-zone-naive types such as `DATETIME` and `TIMESTAMP_NS` do not contain time-zone information, and their stored values do not change with the Doris system time zone. Therefore, time-zone-aware input is converted to a specified target time zone during import and then stored without a time zone. In Doris, the target time zone is represented by the session variable `time_zone`.

In imports, the target time zone is specified by the `timezone` parameter. This variable replaces the session variable `time_zone` when time-zone conversions occur and when time-zone-sensitive functions are evaluated. Therefore, unless there are special circumstances, the `timezone` setting in the import transaction should match the current Doris cluster's `time_zone`. This means all time data with time zones is converted to that time zone.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ PROPERTIES (
);
```

> Supported types for Sequence columns: integer types, `DATE`, and `DATETIME`. **The type cannot be changed after the column is created.**
> Supported types for Sequence columns: integer types, `DATE`, `DATETIME`, and `TIMESTAMP_NS`. **The type cannot be changed after the column is created.**

After creation, the table schema is as follows:

Expand Down Expand Up @@ -304,7 +304,7 @@ When using Sequence Mapping, note the following constraints:
| Category | Constraint |
| --- | --- |
| **Table creation configuration** | `light_schema_change` must be enabled. If the `sequence_mapping` property is not declared at table creation, it cannot be enabled later. |
| **Column types** | Sequence columns only support integer types and time types (`DATE`, `DATETIME`), and the type cannot be changed after creation. |
| **Column types** | Sequence columns only support integer types and time types (`DATE`, `DATETIME`, `TIMESTAMP_NS`), and the type cannot be changed after creation. |
| **Column roles** | Neither Sequence columns nor mapped columns can be Key columns. All non-Key columns must be mapped to a Sequence column. |
| **Mapping relationships** | Mapped columns of different Sequence columns **cannot overlap** (for example, `d` cannot be mapped to both `s1` and `s2`). After a mapping is established, **it cannot be modified** (for example, a column already mapped to `s1` cannot be remapped to `s2`). |
| **DDL limitations** | Column renaming is not supported. Rollup creation is not supported. |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ The two properties differ as follows:
| `function_column.sequence_col` | Maps the Sequence column to an existing column in the table | Yes |
| `function_column.sequence_type` | Specifies only the type of the Sequence column, stored in a hidden column | No |

Supported column types: integer types, `DATE`, and `DATETIME`. **The column type cannot be changed once the table is created.**
Supported column types: integer types, `DATE`, `DATETIME`, and `TIMESTAMP_NS`. **The column type cannot be changed once the table is created.**

### Usage Example

Expand Down
2 changes: 1 addition & 1 deletion docs/key-features/inverted-index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -37,9 +37,9 @@

## What is the Apache Doris inverted index? {#what}

The Apache Doris inverted index is a column-level secondary index that maps each value, or each tokenized term for text columns, to the set of row IDs that contain it. It is built on top of [CLucene](https://github.com/apache/doris-thirdparty/tree/clucene), a C++ port of Lucene, and is fully integrated with Apache Doris columnar storage and vectorized execution.

Check notice on line 40 in docs/key-features/inverted-index.mdx

View workflow job for this annotation

GitHub Actions / Build Check

link-external-report-only

External link is report-only and was not fetched%3A https%3A//github.com/apache/doris-thirdparty/tree/clucene. Owner%3A @apache/doris-website-maintainers

An inverted index is declared in DDL with `INDEX <name>(<col>) USING INVERTED [PROPERTIES(...)]`. Supported column types include the integer family, `DECIMAL`, `DATE`, `DATETIME`, `IPV4`, `IPV6`, `CHAR`/`VARCHAR`/`STRING`, and `ARRAY<T>` of those. For text columns you can attach a `parser` to control tokenization.
An inverted index is declared in DDL with `INDEX <name>(<col>) USING INVERTED [PROPERTIES(...)]`. Supported column types include the integer family, `DECIMAL`, `DATE`, `DATETIME`, `TIMESTAMP_NS`, `IPV4`, `IPV6`, `CHAR`/`VARCHAR`/`STRING`, and `ARRAY<T>` of those. For text columns you can attach a `parser` to control tokenization.

**Key terms**

Expand All @@ -61,7 +61,7 @@
## Quick start {#quick-start}

```sql
CREATE TABLE access_log (

Check warning on line 64 in docs/key-features/inverted-index.mdx

View workflow job for this annotation

GitHub Actions / Build Check

markdown-code-fence-language

Code fence should declare a language. Owner%3A @apache/doris-website-maintainers
ts DATETIME NOT NULL,
user_id BIGINT NOT NULL,
status INT NOT NULL,
Expand Down Expand Up @@ -120,4 +120,4 @@
- [Full-text search](./full-text-search): tokenizers, phrase queries, and the `SEARCH()` DSL built on top of this index.
- [BM25 relevance scoring](./bm25): ranking matches with `score()`, available since 4.0.
- [Hybrid search](./hybrid-search): combining inverted index with the ANN vector index in a single SQL query.
- [How inverted index works in Apache Doris](https://www.velodb.io/blog/how-inverted-index-works-in-apache-doris): a deeper write-up on internals and benchmarks.

Check notice on line 123 in docs/key-features/inverted-index.mdx

View workflow job for this annotation

GitHub Actions / Build Check

link-external-report-only

External link is report-only and was not fetched%3A https%3A//www.velodb.io/blog/how-inverted-index-works-in-apache-doris. Owner%3A @apache/doris-website-maintainers
2 changes: 1 addition & 1 deletion docs/key-features/unique-key.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -66,11 +66,11 @@
1. **Buffer the batch.** BEs collect the incoming rows in a memtable and sort them by key.
2. **Look up each key.** For every key in the batch, the BE consults the per-segment primary-key index (one short read per key) to find any existing rowset and row ID. The index is a sorted, paginated structure built when each segment flushed, conceptually similar to a RocksDB partitioned index.
3. **Mark the old rows.** Each affected rowset gets the old row IDs flipped on in its delete bitmap. The bitmap is per `(rowset_id, segment_id, version)` and the old data stays on disk until compaction reclaims it.
4. **Resolve order with the sequence column.** If `function_column.sequence_col` is set, MoW compares the incoming row's sequence value against the current row's `__DORIS_SEQUENCE_COL__`. The larger value wins. Equal values fall back to load order. The sequence type must be an integer or `DATE`/`DATETIME`.
4. **Resolve order with the sequence column.** If `function_column.sequence_col` is set, MoW compares the incoming row's sequence value against the current row's `__DORIS_SEQUENCE_COL__`. The larger value wins. Equal values fall back to load order. The sequence type must be an integer or `DATE`/`DATETIME`/`TIMESTAMP_NS`.
5. **Publish the new rowset.** The transaction commits, the new version becomes visible, and queries from that point on filter through the merged delete bitmap. No version-merging step at read time.

`DELETE FROM ... WHERE` follows the same flow without the new rowset. Partial updates add one step: before writing, the BE reads the unmodified columns for each key so it can store a complete row.

Check warning on line 73 in docs/key-features/unique-key.mdx

View workflow job for this annotation

GitHub Actions / Build Check

markdown-code-fence-language

Code fence should declare a language. Owner%3A @apache/doris-website-maintainers
## Quick start {#quick-start}

```sql
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Doris collects statistics per column at the table level, including the following
| `max` | Maximum value |
| `null_count` | Number of null values |

**Supported column types**: BOOLEAN, TINYINT, SMALLINT, INT, BIGINT, LARGEINT, FLOAT, DOUBLE, DATE, DATETIME, STRING, VARCHAR, TEXT.
**Supported column types**: BOOLEAN, TINYINT, SMALLINT, INT, BIGINT, LARGEINT, FLOAT, DOUBLE, DATE, DATETIME, TIMESTAMP_NS, STRING, VARCHAR, TEXT.

**Not supported (automatically skipped)**: JSONB, VARIANT, MAP, STRUCT, ARRAY, HLL, BITMAP, TIME, TIMEV2, VARBINARY.

Expand Down
4 changes: 2 additions & 2 deletions docs/query-data/asof-join.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ Key points:
| --- | --- | --- |
| `left_table` | Yes | The left table (probe table). Every row in this table is evaluated. |
| `right_table` | Yes | The right table (build table). Used to look up the closest match. |
| `MATCH_CONDITION` | Yes | Defines the nearest-neighbor matching rule. Each side must reference a column from the corresponding table, and both columns must be of type `DATEV2`, `DATETIMEV2`, or `TIMESTAMPTZ`. Expressions are allowed. Supported operators: `>=`, `>`, `<=`, `<`. |
| `MATCH_CONDITION` | Yes | Defines the nearest-neighbor matching rule. Each side must reference a column from the corresponding table, and both columns must be of type `DATEV2`, `DATETIMEV2`, `TIMESTAMP_NS`, or `TIMESTAMPTZ`. Expressions are allowed. Supported operators: `>=`, `>`, `<=`, `<`. |
| `ON` / `USING` clause | Yes | Defines one or more equi-keys used as grouping keys. Matching is performed only within the same group. `ON` supports one or more equality (`=`) conditions and expressions (such as `SUBSTRING(l.code, 1, 3) = r.prefix`). `USING` supports one or more columns with the same name. |

## Matching Rules
Expand All @@ -82,7 +82,7 @@ The matching direction is determined by the comparison operator in `MATCH_CONDIT

Pay special attention to the following rules:

1. The columns in `MATCH_CONDITION` must be of type `DATEV2`, `DATETIMEV2`, or `TIMESTAMPTZ`.
1. The columns in `MATCH_CONDITION` must be of type `DATEV2`, `DATETIMEV2`, `TIMESTAMP_NS`, or `TIMESTAMPTZ`.
2. Expressions are allowed inside `MATCH_CONDITION`, for example `MATCH_CONDITION(l.ts >= r.ts + INTERVAL 1 HOUR)` or `MATCH_CONDITION(l.ts >= DATE_ADD(r.ts, INTERVAL 3 HOUR))`.
3. The equi-key clause can be written as `ON` or `USING`. When using `ON`, only equality (`=`) conditions joined by `AND` are allowed. Inequality conditions (such as `>`, `OR`) and literal comparisons (such as `l.grp = 1`) are not allowed in the `ON` clause.
4. NULL values in the matching column or in the equi-key columns do not produce a match. If a left-table row has NULL in the matching column, or if no qualifying right-table row exists in the same group, the right-side columns are filled with NULL (LEFT JOIN) or the row is discarded (INNER JOIN).
Expand Down
2 changes: 2 additions & 0 deletions docs/query-data/mysql-compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,8 @@
| Time | - Supported<br />- Time[(p)]<br />- Range: ['-838:59:59.000000', '838:59:59.000000']<br />- Format: hh:mm:ss[.fraction] | - Supported for computation, cannot be stored as a column in OLAP tables<br />- Time[(p)]<br />- Range: ['-838:59:59.999999', '838:59:59.999999']<br />- Format: hh:mm:ss[.fraction] |
| Year | - Supported<br />- Range: 1901 to 2155, or 0000<br />- Format: yyyy | Not supported |

`TIMESTAMP_NS` is a Doris extension rather than a MySQL `TIMESTAMP` equivalent. It is time-zone-naive, has fixed nanosecond precision, and supports the range `1677-09-21 00:12:43.145224192` through `2262-04-11 23:47:16.854775807`.

### String Types

| Type | MySQL | Doris |
Expand Down Expand Up @@ -98,7 +100,7 @@

The QUANTILE_STATE type cannot be used as a Key column. When used in an Aggregate model table, the matching aggregation type at table creation is QUANTILE_UNION. You do not need to specify length or default value; the length is controlled internally by the system based on the aggregation level of the data. QUANTILE_STATE columns can only be queried or used through the matching QUANTILE_PERCENT, QUANTILE_UNION, TO_QUANTILE_STATE, and other functions.

QUANTILE_STATE is a type for computing approximate quantiles. During import, it pre-aggregates different Values for the same Key: when the number of Values does not exceed 2048, all data is recorded in detail; when the number of Values exceeds 2048, the [TDigest](https://github.com/tdunning/t-digest/blob/main/docs/t-digest-paper/histo.pdf) algorithm is used to aggregate (cluster) the data and store the centroids of the clusters.

Check notice on line 103 in docs/query-data/mysql-compatibility.md

View workflow job for this annotation

GitHub Actions / Build Check

link-external-report-only

External link is report-only and was not fetched%3A https%3A//github.com/tdunning/t-digest/blob/main/docs/t-digest-paper/histo.pdf. Owner%3A @apache/doris-website-maintainers

- **Array\<T\>**

Expand Down
1 change: 1 addition & 0 deletions docs/query-data/udf/java-user-defined-function.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@
| Double | Double |
| Date | LocalDate |
| Datetime | LocalDateTime |
| TimestampNs | LocalDateTime |
| IPV4 / IPV6 | InetAddress |
| String | String |
| Decimal | BigDecimal |
Expand Down Expand Up @@ -90,7 +91,7 @@

## Quick Start

This section describes how to develop and register Java UDFs. Sample code is provided in the `samples/doris-demo/java-udf-demo/` directory for reference, and you can also view the [demo](https://github.com/apache/doris/tree/master/samples/doris-demo/java-udf-demo) on GitHub.

Check notice on line 94 in docs/query-data/udf/java-user-defined-function.md

View workflow job for this annotation

GitHub Actions / Build Check

link-external-report-only

External link is report-only and was not fetched%3A https%3A//github.com/apache/doris/tree/master/samples/doris-demo/java-udf-demo. Owner%3A @apache/doris-website-maintainers

UDFs are used in the same way as ordinary functions, with one difference:

Expand Down
8 changes: 4 additions & 4 deletions docs/sql-manual/basic-element/literal/date-literal.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,12 @@ TIMESTAMP '2008-08-08 20:08:08'
- Use a string separated by `-` in the format `'YYYY-MM-DD'` or `'YY-MM-DD'`. Doris also supports MySQL's non-standard separator formats, but their use is not recommended.
- As a string without separators, use the format `'YYYYMMDD'` or `'YYMMDD'` (provided the string is meaningful as a date).

### DATETIME and TIMESTAMPTZ Literal
### DATETIME, TIMESTAMP_NS, and TIMESTAMPTZ Literal

- Use a string separated by `-` in the format `'YYYY-MM-DD hh:mm:ss'` or `'YY-MM-DD hh:mm:ss'`. Doris also supports MySQL's non-standard separator formats, but their use is not recommended. The separator between date and time can be a space (` `) or `T`. **Unlike MySQL 8.4 and earlier versions, Doris does not support any other separators between time and date.**
- As a string without separators, use the format `'YYYYMMDDhhmmss'` or `'YYMMDDhhmmss'` (provided the string is meaningful as a date).

DATETIME literals can include a fractional second part with a precision up to microseconds (six digits). The fractional part should always be separated from the rest of the time with a dot (`.`); other fractional second separators are not recognized.
Date-time literals can include a fractional second part. `DATETIME` and `TIMESTAMPTZ` retain up to six digits (microseconds), while `TIMESTAMP_NS` retains nine digits (nanoseconds). Extra digits are rounded to the target type's precision. The fractional part must be separated from the rest of the time with a dot (`.`); other fractional-second separators are not recognized.

### Two-Digit Years

Expand All @@ -38,7 +38,7 @@ Dates containing two-digit year values are ambiguous because the century is unkn

### Time Zones

DATE, DATETIME and TIMESTAMPTZ literals can use time zone suffixes. When using time zones, the time zone must be immediately adjacent to the previous date or time part, with no spaces in between. For example:
DATE, DATETIME, TIMESTAMP_NS, and TIMESTAMPTZ literals can use time zone suffixes. When using time zones, the time zone must be immediately adjacent to the previous date or time part, with no spaces in between. For example:

```sql
TIMESTAMP '2008-08-08 20:08:08+08:00'
Expand All @@ -61,4 +61,4 @@ Will produce the following error:

```sql
date/datetime literal [071332] is invalid
```
```
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@

## Strict Mode

Before Doris 4.0, Doris's CAST behavior followed database systems like MySQL, trying to avoid CAST operations from raising errors. For example, in MySQL executing the following SQL:

Check warning on line 30 in docs/sql-manual/basic-element/sql-data-types/conversion/cast-expr.md

View workflow job for this annotation

GitHub Actions / Build Check

markdown-code-fence-language

Code fence should declare a language. Owner%3A @apache/doris-website-maintainers

```sql
select cast('abc' as signed);
Expand Down Expand Up @@ -98,10 +98,12 @@
- [Cast to DATE](./date-conversion.md)
- [Cast to TIME](./time-conversion.md)
- [Cast to DATETIME](./datetime-conversion.md)
- [Cast to TIMESTAMP_NS](./timestamp-ns-conversion.md)
- [Cast to TIMESTAMPTZ](./timestamptz-conversion.md)
- [Cast to integers (INT, etc.)](./int-conversion.md)
- [Cast to floating point (FLOAT/DOUBLE)](./float-double-conversion.md)
- [Cast to DECIMAL](./decimal-conversion.md)
- [Cast to CHAR/VARCHAR/STRING](./cast-to-string.md)
- [Cast to JSON / From JSON to other types](./json-conversion.md)
- [Cast to MAP](./map-conversion.md)
- [Cast to STRUCT](./struct-conversion.md)
Expand All @@ -123,4 +125,3 @@
```

You can see from the execution plan above that the system automatically performs a CAST conversion, converting the integer 123 to a string type. This is an example of implicit CAST.

Original file line number Diff line number Diff line change
Expand Up @@ -207,6 +207,24 @@ select cast(cast('20020304121212.123' as datetime(3)) as string);
+-----------------------------------------------------------+
```

## TIMESTAMP_NS

`TIMESTAMP_NS` is formatted as `yyyy-MM-dd HH:mm:ss.SSSSSSSSS`. The fractional-second part always contains exactly nine digits, including trailing zeros. The output does not contain a time zone.

The same representation is used when converting to `CHAR`, `VARCHAR`, or `STRING`. A `NULL` input returns `NULL`.

```sql
SELECT CAST(CAST('2024-02-29 12:34:56.123456' AS TIMESTAMP_NS) AS STRING) AS str_value;
```

```text
+-------------------------------+
| str_value |
+-------------------------------+
| 2024-02-29 12:34:56.123456000 |
+-------------------------------+
```

## Time

Time type is output in "hour:minute:second" format. The hour can be at most 3 digits, at least 2 digits, and can be negative; minutes and seconds are always 2 digits. If the type's `Scale` is not 0, then outputs the decimal point and `Scale` digits of fractional seconds.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@

* `ZULU`: +00:00

3. Long format timezone name: All valid timezone names contained in the IANA-managed [Timezone Database](https://www.iana.org/time-zones), such as `Europe/Paris`, `Etc/GMT+2`, etc., case insensitive.

Check notice on line 154 in docs/sql-manual/basic-element/sql-data-types/conversion/date-conversion.md

View workflow job for this annotation

GitHub Actions / Build Check

link-external-report-only

External link is report-only and was not fetched%3A https%3A//www.iana.org/time-zones. Owner%3A @apache/doris-website-maintainers

* For timezone name availability, see the [Timezone](../../../../admin-manual/cluster-management/time-zone) documentation.

Expand Down Expand Up @@ -333,7 +333,7 @@

* `ZULU`: +00:00

3. Long format timezone name: All valid timezone names contained in the IANA-managed [Timezone Database](https://www.iana.org/time-zones), such as `Europe/Paris`, `Etc/GMT+2`, etc., case insensitive.

Check notice on line 336 in docs/sql-manual/basic-element/sql-data-types/conversion/date-conversion.md

View workflow job for this annotation

GitHub Actions / Build Check

link-external-report-only

External link is report-only and was not fetched%3A https%3A//www.iana.org/time-zones. Owner%3A @apache/doris-website-maintainers

* For timezone name availability, see the [Timezone](../../../../admin-manual/cluster-management/time-zone) documentation.

Expand Down Expand Up @@ -490,3 +490,18 @@
| `500:00:00` | `2025-05-19` |
| `23:59:59` | `2025-04-29` |
| `-128:00:00` | `2025-04-23` |

### TIMESTAMP_NS

#### Rule Description

When converting from `TIMESTAMP_NS`, Doris returns the date part and discards the time and fractional-second parts without rounding. Every valid `TIMESTAMP_NS` value is within the `DATE` range, so the conversion always succeeds in both strict and non-strict modes. A `NULL` input returns `NULL`.

#### Examples

| Input TIMESTAMP_NS | Cast as DATE Result |
| --- | --- |
| `1677-09-21 00:12:43.145224192` | `1677-09-21` |
| `1969-12-31 23:59:59.999999999` | `1969-12-31` |
| `2024-02-29 12:34:56.123456789` | `2024-02-29` |
| `2262-04-11 23:47:16.854775807` | `2262-04-11` |
Original file line number Diff line number Diff line change
Expand Up @@ -157,7 +157,7 @@

* `ZULU`: +00:00

3. Long format timezone name: All valid timezone names contained in the IANA-managed [Timezone Database](https://www.iana.org/time-zones), such as `Europe/Paris`, `Etc/GMT+2`, etc., case insensitive.

Check notice on line 160 in docs/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion.md

View workflow job for this annotation

GitHub Actions / Build Check

link-external-report-only

External link is report-only and was not fetched%3A https%3A//www.iana.org/time-zones. Owner%3A @apache/doris-website-maintainers

* For timezone name availability, see the [Timezone](../../../../admin-manual/cluster-management/time-zone) documentation.

Expand Down Expand Up @@ -618,3 +618,16 @@
| `2020-12-12 00:00:00.123456+08:00` | Timestamptz(6) | Datetime(3) | `2020-12-12 00:00:00.123` | Decrease precision, no carr |
| `2020-12-12 00:00:00.99666+08:00` | Timestamptz(6) | Datetime(2) | `2020-12-12 00:00:01.00` | Decrease precision, carry to second |
| `9999-12-31 23:59:59.999999+08:00` | Timestamptz(6) | Datetime(5) | NULL | Carry overflow, produces an invalid date of year 10000 |

### TIMESTAMP_NS

`TIMESTAMP_NS` is time-zone-naive like `DATETIME`, so the conversion preserves the civil date and time without applying a time zone adjustment. Because `TIMESTAMP_NS` always has nine fractional digits and `DATETIME` supports at most six, the fractional part is rounded to the target `DATETIME` precision. A carry can propagate to the next second.

Every valid `TIMESTAMP_NS` value is within the `DATETIME` date range, so conversion always succeeds in both strict and non-strict modes. A `NULL` input returns `NULL`.

| Input TIMESTAMP_NS | Target Type | Result DATETIME | Comment |
| --- | --- | --- | --- |
| `2024-02-29 12:34:56.123456499` | Datetime(6) | `2024-02-29 12:34:56.123456` | Discarded digits round down |
| `2024-02-29 12:34:56.123456500` | Datetime(6) | `2024-02-29 12:34:56.123457` | Discarded digits round up |
| `1969-12-31 23:59:59.999999500` | Datetime(6) | `1970-01-01 00:00:00.000000` | Carry to the next second and date |
| `2024-02-29 12:34:56.123456789` | Datetime(3) | `2024-02-29 12:34:56.123` | Round to millisecond precision |
Original file line number Diff line number Diff line change
Expand Up @@ -266,6 +266,10 @@ Not supported.

Not supported.

## From TIMESTAMP_NS

Not supported.

## From time

Not supported.
Expand Down
Loading
Loading