apache / apache/doris-website

DATE_TRUNC documentation is inconsistent with actual argument order behavior

Open Beginner friendly
#4,108 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
MDX
Stars
133
Forks
464
Avg merge
1d 1h
Merged PRs (30d)
50

Description

https://doris.apache.org/docs/3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/date-trunc

The `DATE_TRUNC` documentation states that both argument orders are supported:

```sql
DATE_TRUNC(, )
DATE_TRUNC(, )
```

However, in actual usage, only the following argument order appears to work:

```sql
DATE_TRUNC(, )
```

The reversed form:

```sql
DATE_TRUNC(, )
```

results in an error.

## Reproduction

### Case 1: Using a DATETIME column

The datetime-first form works as expected:

```sql
SELECT DATE_TRUNC(work_date, 'month');
```

However, reversing the arguments:

```sql
SELECT DATE_TRUNC('month', work_date);
```

returns:

```text
SQL Error [1105] [HY000]: errCode = 2, detailMessage =
the second parameter of date_trunc function must be a string constant:
date_trunc('month', work_date)
```

This suggests that the second argument is still interpreted as `time_unit`.

### Case 2: Using only string literals

The same behavior can be reproduced without using a column:

```sql
SELECT DATE_TRUNC('month', '2010-12-02 19:28:30');
```

which returns:

```text
SQL Error [1105] [HY000]: errCode = 2, detailMessage =
date_trunc function second param only support argument is
year|quarter|month|week|day|hour|minute|second
```

Again, this indicates that the second argument is interpreted as `time_unit`, rather than the first argument.

In contrast, the datetime-first form works:

```sql
SELECT DATE_TRUNC('2010-12-02 19:28:30', 'month');
```

## Expected behavior

According to the documentation, both forms should be accepted:

```sql
DATE_TRUNC(work_date, 'month')
DATE_TRUNC('month', work_date)
```

## Actual behavior

Only the datetime-first form appears to be supported:

```sql
DATE_TRUNC(, )
```

## Question

Could you please confirm whether:

1. `DATE_TRUNC(, )` is intended to be supported; or
2. the documentation should only list:

```sql
DATE_TRUNC(, )
```

If the reversed argument order is only supported in specific Doris versions, it would also be helpful to clarify the supported versions in the documentation.

## Environment

Apache Doris version: 3.0.4

Contributor guide

No contributing guide indexed for this repository

Research direction

Open the DATE_TRUNC documentation page linked in the issue and compare its two documented signatures with the reported Doris 3.0.4 queries. Verify whether the reversed argument order is supported and whether behavior differs by version; done means the page accurately lists supported syntax and clarifies any version-specific behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
sql
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
70/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.