ClickHouse Performance: Application Domain Index for Nested Data Structures


Application Domain Indexes (ADIs) in ClickHouse provide a way to efficiently index and query nested data structures. ADIs allow for faster data retrieval and filtering when dealing with complex hierarchical or nested data. Let’s explore how ADIs are implemented in ClickHouse with a real-life data set example.

Example Scenario:

Suppose we have a dataset containing customer information for an e-commerce platform. Each customer record includes details such as customer IDnameemailphone number, and a nested field for order history. The order history contains sub-fields like order IDpurchase date, and product details. We want to implement an ADI on the order history to enable efficient querying of customer data based on order attributes.

Implementation Steps

Create the Table: We need to create a table in ClickHouse to store the customer data, including the nested order history field.

CREATE TABLE customers
customer_id UInt64,
name String,
email String,
phone_number String,
order_history Nested (
order_id UInt64,
purchase_date Date,
product_details Nested (
product_id UInt64,
product_name String,
price Float64
) ENGINE = MergeTree()
ORDER BY customer_id

In the above example, the table “customers” includes the customer ID, name, email, phone number, and the nested “order_history” field. The “order_history” field contains the nested “order_id,” “purchase_date,” and “product_details” fields.

Create the Application Domain Index

To implement an ADI, we define an index on the desired nested field using the “INDEX” keyword. In this case, we want to create an index on the “order_history” field.

CREATE INDEX idx_order_history ON customers (order_history) TYPE minmax GRANULARITY 100

In the above example, we create an index named “idx_order_history” on the “order_history” field of the “customers” table. We specify the index type as “minmax” and set the index granularity to 100. The index granularity determines the number of distinct index keys to store.

Querying Data using ADI:

Once the ADI is created, we can query the data using the nested field efficiently. ClickHouse automatically utilizes the ADI to optimize the query execution.

SELECT customer_id, name, email
FROM customers
WHERE order_history.order_id = 12345

In the above example, we retrieve the customer ID, name, and email of customers who have made an order with the ID 12345. ClickHouse leverages the ADI on the “order_history” field to efficiently filter and retrieve the relevant customer data.

Maintenance and Optimization:

ADIs in ClickHouse require periodic maintenance to ensure optimal performance. You can rebuild or optimize the ADI periodically to incorporate any changes or updates in the nested data. Additionally, you can adjust the index granularity based on the data distribution and query patterns to achieve optimal performance.


Application Domain Indexes (ADIs) in ClickHouse provide a powerful mechanism to index and query nested data structures efficiently. By implementing ADIs, you can improve query performance and enable faster retrieval of data from complex hierarchical or nested fields. ClickHouse’s support for ADIs makes it an ideal choice for handling and querying nested data in real-life scenarios, such as e-commerce platforms, IoT applications, and log analytics.

To know more about indexes in ClickHouse, do read the following articles:

ChistaDATA: Your Trusted ClickHouse Consultative Support and Managed Services Provider. Unlock the Power of Real-Time Analytics with ChistaDATA Cloud( – the World’s Most Advanced ClickHouse DBaaS Infrastructure. Contact us at or (844)395-5717 for tailored solutions and optimal performance.

About Shiv Iyer 222 Articles
Open Source Database Systems Engineer with a deep understanding of Optimizer Internals, Performance Engineering, Scalability and Data SRE. Shiv currently is the Founder, Investor, Board Member and CEO of multiple Database Systems Infrastructure Operations companies in the Transaction Processing Computing and ColumnStores ecosystem. He is also a frequent speaker in open source software conferences globally.