Implement native path translation for JsonNode navigation

[HappyEntity]

Description:

This PR closes the standing limitation #1 mentioned in the README: "No JSON path translation — entity.Payload["name"] in LINQ does not translate to ClickHouse's data.name SQL syntax.".

Now, the provider supports native ClickHouse navigation for System.Text.Json.Nodes.JsonNode using standard C# indexing and casting.

Key Features:

• Property Access: Data["key"] translates to data.key.
• Array Indexing: Data[0] translates to data[1] (handles ClickHouse 1-based indexing).
• Deep Nesting: Supports infinite nesting like Data["user"]["address"]["city"].
• Type Casting: Supports both .GetValue<T>() and explicit casting (T)Data["key"].
• Matrix Support: Handles multi-dimensional arrays (e.g., Data["matrix"][0][0]).

Technical Changes:

• Implemented ClickHouseJsonPathExpression and ClickHouseJsonArrayIndexExpression to represent JSON paths in the SQL tree.
• Added ClickHouseJsonNodeTranslator with strict MethodInfo mapping to handle indexing and value extraction.
• Updated ClickHouseQuerySqlGenerator with dedicated visitors for JSON paths and indices. Implemented custom VisitSqlUnary logic to handle explicit/implicit casting, ensuring clean CAST(... AS Type) output and avoiding ClickHouse "Illegal type JSON" errors.
• Updated ClickHouseSqlNullabilityProcessor to ensure correct null propagation for JSON paths.

Examples:

LINQ:

.Where(e => (int)e.Data["age"] > 25)
.Select(e => new {
    City = e.Data["address"]["city"].GetValue<string>(),
    FirstTag = e.Data["tags"][0].GetValue<string>()
})

Generated SQL:

SELECT CAST(j.data.address.city AS String), CAST(j.data.tags[1] AS String)
FROM json_table AS j
WHERE CAST(j.data.age AS Int32) > 25

Note

On Object Projections:

Due to ClickHouse's native JSON type implementation (which uses dynamic sub-columns and flattens nested objects), projecting an entire intermediate object like Data["address"] will return an empty result or a flattened map. This is consistent with native ClickHouse behavior: SELECT data.address returns an empty string/map because the engine only physically stores leaf nodes like data.address.city.

However, projecting array elements containing objects (e.g., Data["orders"][0]) works as expected because ClickHouse preserves the internal structure for array elements.

Recommendation: To ensure predictable results, always project to the leaf property (e.g., (T)Data["address"]["city"]) or use .GetValue<T>().

Testing:

Added comprehensive integration tests in JsonNodeTranslationTests.cs covering:

• Scalar types (string, int, long, double, bool, ulong).
• Missing keys (verified ClickHouse implicit defaults behavior).
• Deeply nested objects and matrix arrays.
• Full object/array projections.

[codecov]

Codecov Report

❌ Patch coverage is 77.89474% with 21 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ons/Internal/ClickHouseJsonArrayIndexExpression.cs	37.50%	9 Missing and 1 partial ⚠️
...pressions/Internal/ClickHouseJsonPathExpression.cs	40.00%	8 Missing and 1 partial ⚠️
...anslators/Internal/ClickHouseJsonNodeTranslator.cs	96.77%	0 Missing and 1 partial ⚠️
...ouse/Query/Internal/ClickHouseQuerySqlGenerator.cs	95.83%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[alex-clickhouse]

Looks good to me, please add a mention of the new features to CHANGELOG.md and RELEASENOTES.md and it's ready to go.

[HappyEntity]

I've pushed the requested changes:

• Updated CHANGELOG.md and RELEASENOTES.md under the new v0.3.0 section.

[alex-clickhouse]

Thank you for your contribution!