docs: json2 data type#2615
Conversation
|
@codex review |
There was a problem hiding this comment.
Pull request overview
This PR adds documentation for GreptimeDB’s JSON2 data type (nightly/current docs) and surfaces it in the Logs section of the docs sidebar, including a Chinese localized version.
Changes:
- Added a new JSON2 documentation page under
docs/user-guide/logs/. - Added the corresponding Chinese doc under
i18n/zh/.../current/. - Linked the new page into the Logs sidebar navigation.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| sidebars.ts | Adds the new user-guide/logs/json2 doc entry to the Logs sidebar. |
| docs/user-guide/logs/json2.md | Introduces the English JSON2 type guide with examples and limitations. |
| i18n/zh/docusaurus-plugin-content-docs/current/user-guide/logs/json2.md | Adds the Chinese version of the JSON2 type guide. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: eb656f1549
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| When creating a table, you can declare a JSON2 column with the `JSON2` type. | ||
| Currently, JSON2 can only be used in append-only tables, so you must set `'append_mode' = 'true'` when creating the table. | ||
|
|
||
| JSON2 supports type hints, which let you declare concrete data types for subpaths. Once declared, these subpaths are stored using the specified types, which provides query performance close to regular columns and enforces type validation during writes. In the following example, the `attrs` column defines type hints for common paths such as `http.status`, `latency_ms`, and `error`. |
There was a problem hiding this comment.
describe this is not required. My suggestion is to make quick start quick enough and cover type hint in later section.
just show how to create table without type hint, ingest json and query.
| - Support subscript access to elements inside JSON arrays. For now, you can query `attrs.items`, but not `attrs.items[0]` or `json_get(attrs, 'items[0]')`. | ||
| - Support functions such as `json_get_string`, `json_get_int`, `json_get_float`, and `json_get_bool` for JSON2. | ||
| - Extend supported type hint data types, such as time-related types like `TIMESTAMP`. | ||
| - Support index options such as `INVERTED INDEX` and `SKIPPING INDEX` for type hints. |
There was a problem hiding this comment.
how to use json2 with otlp and other ingestion path
|
|
||
| Type hints allow `NULL` by default. If you specify `NOT NULL`, that path must exist in the written JSON. | ||
|
|
||
| ### `json_get` |
There was a problem hiding this comment.
| ### `json_get` | |
| ### `json_get` UDF |
|
|
||
| ```sql | ||
| json_get(json_column, 'path.to.field')::TYPE | ||
| ``` |
There was a problem hiding this comment.
add a description for dot syntax
|
|
||
| ## Syntax | ||
|
|
||
| ### Type hints |
There was a problem hiding this comment.
| ### Type hints | |
| ### JSON Field Type hints |
There was a problem hiding this comment.
and explain why it's essential, but optional
| | path | status | latency_ms | error | | ||
| | --- | --- | --- | --- | | ||
| | /v1/orders | 200 | 386.4 | NULL | | ||
| | /v1/orders | 500 | 71.2 | 1 | |
There was a problem hiding this comment.
This is still the result of a ::BOOLEAN cast, so the value should render as true, not 1. The current JSON2 fixtures render Boolean fields as true, and this cast is planned as a Boolean-returning json_get. Please fix this table and the Chinese table at line 110; the earlier thread was resolved, but the value remains.
| Type hints allow `NULL` by default. If you specify `NOT NULL`, that path must | ||
| exist in the written JSON. | ||
|
|
||
| As shown in the quick start example above, type hints can be declared directly |
There was a problem hiding this comment.
The quick-start table now declares plain attrs JSON2 without type hints, so “As shown in the quick start example above” is no longer true. Please state explicitly that type hints are optional, then introduce this as a separate typed example; update the Chinese sentence too.
| subpaths such as `attrs.http.status` or `json_get(attrs, 'http.status')`. | ||
| - Support subscript access to elements inside JSON arrays. For now, you can | ||
| query `attrs.items`, but not `attrs.items[0]` or `json_get(attrs, 'items[0]')`. | ||
| - Support functions such as `json_get_string`, `json_get_int`, |
There was a problem hiding this comment.
These typed helpers already work with JSON2 on current GreptimeDB main: the shared implementation handles the StructArray representation used by JSON2, and its unit tests exercise typed reads from that representation. Keeping this in the Roadmap incorrectly documents an existing feature as unsupported. Please remove it here and in the Chinese page, or replace it with the actual remaining limitation.
|
|
||
| JSON2 is a JSON type in GreptimeDB designed for logs and semi-structured data. | ||
| It stores fields inside JSON in a structured, columnar form so that frequently | ||
| used fields can be read, filtered, and aggregated efficiently like regular |
There was a problem hiding this comment.
This line, together with lines 27 and 142, has trailing whitespace, so git diff --check origin/main...HEAD currently fails. Please remove those spaces.
What's Changed in this PR
This PR adds a guide to JSON2, including a quick start, syntax, and future roadmap.
Checklist
sidebars.tsmatches the current document structure when you changed the document structure.