Changelog category (leave one):

• Improvement

Changelog entry (a user-readable short description of the changes that goes into CHANGELOG.md):

Add support for Map and JSON/Object types as dictionary attributes. Now dictionaries can store and retrieve complex types including Map(String, String), Map(String, Array(String)), JSON, and Nullable(JSON) types in both FLAT and HASHED layouts.

Closes #86829

Detailed description

This PR adds support for complex types (Map and JSON/Object) as dictionary attributes, extending the existing dictionary functionality to handle nested and structured data types.

Supported dictionary layouts:

• FLAT
• HASHED
• HashedArray
• RangeHashed
• IPAddress
• Polygon
• Cache

Documentation entry for user-facing changes

• Documentation is written (mandatory for new features)

Documentation should include:

Motivation:
This PR addresses Issue #86829 which requested support for JSON type in dictionary attributes. Previously, attempting to create a dictionary with JSON attributes resulted in DB::Exception: Unknown type JSON for dictionary attribute. (UNKNOWN_TYPE).

Dictionaries are commonly used for lookups and data enrichment. Supporting Map and JSON types allows users to store and retrieve complex, nested data structures directly from dictionaries, enabling more flexible data modeling and reducing the need for multiple dictionary lookups or post-processing. This feature enables use cases such as:

• Storing unstructured or semi-structured data in dictionaries
• Accessing nested JSON fields directly via dictionary lookups (e.g., dictGet('dict', 'json_field', key).nested.field)
• Using Map types for key-value lookups within dictionary attributes

Parameters:

• Dictionary attribute types can now be declared as:
  • Map(KeyType, ValueType) where KeyType is typically String and ValueType can be String, Array, or numeric types
  • JSON or Nullable(JSON) for JSON/Object data
• All existing dictionary layouts (FLAT, HASHED, etc.) support these types
• Dictionary operations (dictGet, dictGetOrDefault, etc.) work seamlessly with Map and JSON types

Example use:

-- Step 1: Create source table with Map and JSON columns
CREATE TABLE users
(
    user_id UInt64,
    name String,
    metadata Map(String, String),
    profile JSON
)
ENGINE = Memory;

-- Step 2: Insert sample data
INSERT INTO users VALUES
(1, 'Alice', {'age': '30', 'city': 'New York'}, '{"age": 30, "city": "New York", "country": "USA", "address": {"street": "123 Main St", "zip": "10001"}}'),
(2, 'Bob', {'age': '25', 'city': 'London'}, '{"age": 25, "city": "London", "country": "UK", "address": {"street": "456 High St", "zip": "SW1A 1AA"}}');

-- Step 3: Create dictionary with Map and JSON attributes
CREATE DICTIONARY user_profiles
(
    user_id UInt64,
    name String,
    metadata Map(String, String),
    profile JSON
)
PRIMARY KEY user_id
SOURCE(CLICKHOUSE(HOST 'localhost' PORT tcpPort() DB 'default' TABLE 'users'))
LAYOUT(FLAT())
LIFETIME(MIN 0 MAX 0);

-- Step 4: Query Map values using dictionary
SELECT dictGet('user_profiles', 'metadata', 1)['city'] as city;
-- Result: New York

-- Step 5: Query JSON values using dictionary
SELECT dictGet('user_profiles', 'profile', 1).age as age;
-- Result: 30

SELECT dictGet('user_profiles', 'profile', 1).city as city;
-- Result: New York

-- Step 6: Access nested JSON fields
SELECT dictGet('user_profiles', 'profile', 1).country as country;
-- Result: USA

SELECT dictGet('user_profiles', 'profile', 1).address.city as address_city;
-- Result: New York

Backward compatibility:
This change is fully backward compatible. Existing dictionaries continue to work as before, and the new complex types are additive features.

Version info

• Merged into: 26.4.1.895