Quantrail Data

In Parts 1 and 2, we looked at how JSON typically enters ClickHouse® and how it has traditionally been handled using String, Map, Tuple, and Object('json'). If you missed the part1 and part2, you can read it below.

A Beginner’s Guide to JSON in ClickHouse®

Traditional JSON handling in ClickHouse®

All of these approaches forced an early decision:

• either keep full flexibility and pay the cost at query time,
• or enforce structure upfront and lose flexibility.

The native JSON data type was introduced to rebalance this trade-off.

This part focuses on what the native JSON type actually is, how it works internally, and what changes – and just as importantly, what does not.

Why ClickHouse® Introduced a Native JSON Type

Traditional JSON handling in ClickHouse® exposed a fundamental tension:

• JSON data evolves naturally
• Analytical queries demand structure
• Performance matters at scale

Storing JSON as raw text delayed structure discovery until query time.
Modeling JSON into columns or tuples required early, often premature decisions.

The native JSON data type exists to address this tension – not by eliminating trade-offs, but by shifting where they apply.

We can take the below JSON Data as our example in this Blog.

{
  "event_type": "page_view",
  "user_id": 12345,
  "page": "/pricing",
  "device": {
    "os": "linux",
    "browser": "firefox"
  },
  "timestamp": "2026-01-01T10:00:00Z"
}

What the JSON Data Type Is (and Is Not)

At a high level, a column defined as JSON looks simple:

CREATE TABLE events
(
    event_time DateTime,
    data JSON
)
ENGINE = MergeTree
ORDER BY event_time;

But internally, this is very different from storing JSON as a String.

What it is

• A binary representation of JSON
• Structurally aware of keys, nesting, and types
• Designed for selective access

What it is not

• Not a wrapper around String
• Not an evolution of Object('json')
• Not a replacement for schema design

The key difference lies in how and when parsing happens.

Binary Storage and Structural Awareness

When JSON is stored as String, ClickHouse® has no memory of structure.
Every query starts from raw text.

With the native JSON type:

• JSON is converted into a binary form at insertion
• Structural metadata is preserved
• Keys, paths, and nesting are understood internally

This allows ClickHouse® to reason about JSON without re-reading raw text on every query.

However, this does not mean all fields are eagerly parsed.

Lazy Parsing: The Core Idea

Lazy parsing is the defining characteristic of the native JSON type.

Instead of fully parsing the entire JSON object at insert time or query time:

ClickHouse® parses only the parts of the JSON that a query actually touches.

If a query accesses one field:

• Only that field is parsed
• Unused fields incur no parsing cost

This changes the cost model significantly for wide or sparse JSON objects.

What lazy parsing does not mean

• It does not make parsing free
• It does not cache parsed results across queries
• It does not eliminate CPU cost

It simply makes the cost proportional to usage, not data size.

Querying Native JSON Columns

Querying a JSON column looks familiar, but the execution model is different.
Example:

SELECT
    data.event_type AS event_type,
    data.user_id AS user_id
FROM events;

What happens internally:

• ClickHouse® navigates the binary JSON structure
• Only event_type and user_id are parsed
• Other fields are skipped entirely

Nested access works the same way:

SELECT
    data.device.os AS os
FROM events;

Again, only the accessed path is parsed.

This is fundamentally different from JSONExtract, which reparses the entire JSON string every time.

Type Handling and Extraction

The native JSON type retains type information internally, but it does not enforce schema.

That means:

• Fields may appear or disappear
• Types may vary across rows
• Queries must still handle type uncertainty

Explicit extraction is often required:

SELECT
    toUInt64(data.user_id) AS user_id
FROM events;

Native JSON reduces parsing work – it does not guarantee type safety.

What the Native JSON Type Does Not Solve

This is where expectations must be managed carefully.

The native JSON type does not make all JSON queries fast.

In particular:

• Filtering on JSON fields still requires parsing
• Grouping by JSON fields is still expensive
• Joining on JSON fields is still costly

A critical rule still applies:

If a JSON field is frequently used in WHERE, GROUP BY, or joins, it should probably be a real column.

The native JSON type improves flexibility and reduces unnecessary parsing – it does not replace columnar modeling.

Where the Native JSON Type Works Best

The native JSON type shines in scenarios like:

• Rapidly evolving event schemas
• Sparse or optional attributes
• Long-tail metadata
• Early-stage ingestion pipelines

It allows teams to:

• Delay schema decisions
• Avoid repeated full JSON parsing
• Gradually promote hot fields into real columns

This makes it a powerful transitional and complementary tool, not a universal solution.

How Native JSON Fits into the Bigger Picture

At this point in the series, we’ve seen three distinct models:

• Raw JSON text (String)
• Structured representations (Map, Tuple)
• Structurally aware, lazily parsed JSON (JSON)

Each one optimizes for a different phase of system maturity.

The native JSON type exists because real systems change over time.

Conclusion

The native JSON data type does not eliminate trade-offs – it reshapes them.

It reduces unnecessary parsing, improves flexibility, and makes semi-structured data more manageable.
But it does not remove the need for schema design, nor does it replace well-modeled columns.

Understanding this distinction is essential to using native JSON correctly.

In Part 4, we’ll bring everything together:

• Compare all JSON approaches side by side.
• Walk through concrete examples.
• Limitations of native Json.
• And answer the practical question:

When should you use which JSON approach in ClickHouse®?

References

Native Json Type in ClickHouse®

https://clickhouse.com/docs/sql-reference/data-types/newjson