Implementation:ClickHouse ClickHouse Clickhouse Local Query

Knowledge Sources	ClickHouse
Domains	Build_System, Testing, C++
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for verifying a successful ClickHouse build by executing a minimal query through the compiled binary's local mode, confirming correct linking and basic functionality.

Description

The clickhouse local command provides an embedded, serverless SQL execution mode. When invoked with -q "SELECT 1", it performs a full end-to-end query execution without requiring any external services, configuration files, or data directories.

The execution begins in programs/main.cpp at the main function (line 330). After static initialization (PHDR cache update, environment variable checks, new handler reset), the dispatch table at line 157-206 is traversed. The entry {"local", mainEntryClickHouseLocal} at line 159 is the first entry in the table, giving it highest priority in dispatch resolution.

The dispatch logic in isClickhouseApp (line 227) checks three conditions:

1. Whether the binary was invoked via a symlink (e.g., clickhouse-local).
2. Whether the first argument matches the mode name (e.g., clickhouse local ... or clickhouse --local ...).
3. Whether a short alias was used (e.g., chl for local, as defined in the clickhouse_short_names table at line 216).

Additionally, the main function contains special fallback logic (lines 394-401): if no mode is matched and the binary is invoked with no arguments, with flags starting with -, with a string containing spaces, or with a path to an existing regular file, it defaults to local mode. This makes clickhouse -q "SELECT 1" and even bare clickhouse invocations work as the local tool.

The main.cpp file also disables dlopen by providing stub implementations (lines 259-281), preventing any dynamic library loading. This is a security hardening measure.

Usage

Use this verification after every build to confirm the binary is functional. It is the fastest possible end-to-end check, typically completing in under a second.

Code Reference

Source Location

• Repository: ClickHouse
• File: programs/main.cpp
• Lines: 330-410 (main function), 157-206 (dispatch table), 216-223 (short aliases)

Signature

./build/programs/clickhouse local -q "SELECT 1"

Import

# Direct invocation (most common for build verification):
./build/programs/clickhouse local -q "SELECT 1"

# Via symlink:
./build/programs/clickhouse-local -q "SELECT 1"

# Via short alias:
./build/programs/chl -q "SELECT 1"

# Implicit local mode (bare clickhouse with -q flag):
./build/programs/clickhouse -q "SELECT 1"

I/O Contract

Inputs

Name	Type	Required	Description
Compiled binary	Executable file	Yes	The clickhouse binary produced by ninja -C build clickhouse
-q / --query	String	Yes (for single-query mode)	SQL query to execute. For build verification, "SELECT 1" is the canonical minimal query.
local	Subcommand	No (implicit if -q is passed)	Selects the local (embedded, serverless) execution mode

Outputs

Name	Type	Description
stdout	Text	Query result: 1 (a single line containing the integer result of SELECT 1)
Exit code	Integer	0 on success, non-zero on failure (unresolved symbols, initialization crash, query error)

Usage Examples

Basic Build Verification

# Build and verify in one step:
ninja -C build clickhouse && ./build/programs/clickhouse local -q "SELECT 1"
# Expected output: 1

Verify Version Information

# Check that version is correctly embedded:
./build/programs/clickhouse local -q "SELECT version()"
# Expected output: 26.2.1.1

Verify Multiple Execution Modes

# Verify the dispatch table works for different modes:
./build/programs/clickhouse local -q "SELECT 1"
./build/programs/clickhouse client --help 2>&1 | head -1
./build/programs/clickhouse server --help 2>&1 | head -1

CI Build Verification Script

#!/bin/bash
set -e
BINARY="./build/programs/clickhouse"

# Verify binary exists and is executable
test -x "$BINARY"

# Verify basic query execution
RESULT=$("$BINARY" local -q "SELECT 1")
if [ "$RESULT" != "1" ]; then
    echo "Build verification failed: expected '1', got '$RESULT'"
    exit 1
fi

echo "Build verification passed"

Verify With Short Aliases

# These should all produce the same result:
./build/programs/clickhouse local -q "SELECT 1"  # explicit mode
./build/programs/clickhouse -q "SELECT 1"         # implicit local mode
./build/programs/chl -q "SELECT 1"                # short alias
./build/programs/ch -q "SELECT 1"                 # shortest alias

Related Pages

Implements Principle

• Principle:ClickHouse_ClickHouse_Build_Verification

Requires Environment

• Environment:ClickHouse_ClickHouse_Linux_Build_Environment