apache / apache/doris-website

[doc] STRUCT_ELEMENT example in 3.x/2.1: undefined table + outdated struct display format

Open
#3,894 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
MDX
Stars
133
Forks
464
Avg merge
1d 1h
Merged PRs (30d)
50

Description

### Page

`STRUCT_ELEMENT` function reference — `version-3.x` and `version-2.1`, EN + ZH:
- `versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/struct-functions/struct-element.md`
- `versioned_docs/version-2.1/.../struct-element.md` (+ the two `i18n/zh-CN` copies)

### Two problems with the second example

```sql
select struct_col, struct_element(struct_col, 'f1') from test_struct;
```

**1. `test_struct` is never created.** The page has no `CREATE TABLE`/`INSERT` for `test_struct`, so copy-pasting the example fails with `table does not exist`.

**2. The printed output uses an outdated STRUCT display format.** The doc shows structs rendered positionally:

```
| struct_col | ... |
| {1, 2, 3, 4, 5} | 1 |
| NULL | NULL|
| {1, NULL, 3, NULL, 5} | 1 |
```

But current Doris (verified on **3.1.4** and **2.1.11**) renders STRUCT columns as JSON with field names:

```
| {"f1":1, "f2":2, "f3":3, "f4":4, "f5":5} | 1 |
| {"f1":1, "f2":null, "f3":3, "f4":null, "f5":5} | 1 |
```

So even after defining `test_struct`, the `struct_col` column in the documented output is unreproducible as written — the example is stale relative to the actual struct rendering on these release lines.

### Suggested fix

Add a `CREATE TABLE test_struct (...) / INSERT` setup block **and** update the example's expected output to the current JSON struct rendering (`{"f1":1, ...}`, nested `null` lowercase). I verified that a 5-row `struct` table reproducing the row values (`{1,2,3,4,5}`, `{1,1000,10000000,100000000000,100000000000}`, `{5,4,3,2,1}`, a `NULL` row, and `{1,null,3,null,5}`) yields `struct_element(struct_col,'f1')` = 1, 1, 5, NULL, 1 exactly — only the raw `struct_col` rendering needs the format update.

I'm intentionally leaving this out of the phantom-table-setup PR series because it's more than a missing-table fix — it requires changing the documented output to match current struct rendering, which is an editorial call on these older release lines.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.