Introduction

In ClickHouse, a "flag" is usually a runtime setting such as memory limits, thread usage, or read-only behavior. Getting the current value is straightforward, but it is important to know whether you are reading session-level or server-level configuration. This guide shows reliable queries and explains how settings change across scopes.

Query Settings from system.settings

The primary way to inspect flags is the system.settings table. It includes the current value for the active session and whether it differs from default.

1SELECT
2    name,
3    value,
4    default,
5    changed,
6    description
7FROM system.settings
8WHERE name = 'max_memory_usage';

Important columns:

• value is the current effective value for your session
• default is the built-in default value
• changed indicates whether session value differs from default

This is the best first query when troubleshooting unexpected query behavior.

Read Multiple Related Flags at Once

Performance or safety issues usually involve multiple settings, not one flag. Query several relevant settings together.

1SELECT name, value
2FROM system.settings
3WHERE name IN (
4    'max_memory_usage',
5    'max_threads',
6    'readonly',
7    'allow_ddl'
8)
9ORDER BY name;

This avoids piecemeal debugging and gives a consistent snapshot of your current session state.

Get Value in Expressions with getSetting

When writing diagnostic queries, getSetting is useful because it returns setting values directly in expressions.

SELECT
    getSetting('max_threads') AS threads,
    getSetting('max_memory_usage') AS mem_limit;

You can combine settings with computed metadata for quick audits.

1SELECT
2    currentUser() AS user,
3    currentDatabase() AS db,
4    getSetting('readonly') AS is_readonly;

Understand Session vs Server Configuration

A frequent confusion is reading a setting after SET and assuming it changed globally. In most cases, SET updates only current session.

SET max_threads = 2;
SELECT getSetting('max_threads') AS now_threads;

Open a new session and you may see a different value. Global defaults usually come from server config files or user profiles.

Inspect User and Profile-Level Constraints

ClickHouse can override settings by user profile, quotas, or roles. If a flag appears fixed, the profile may enforce constraints.

SELECT *
FROM system.users
WHERE name = currentUser();

Also inspect profile metadata on your deployment if available in system tables. Managed environments may restrict direct config access, so check admin documentation for profile mapping.

Boolean and Enum-Like Flags

Some settings behave like booleans represented as numeric values. For example, readonly often uses integer values.

SELECT
    getSetting('readonly') AS readonly_value,
    if(getSetting('readonly') = 0, 'write allowed', 'read only mode') AS mode;

Always confirm expected value semantics in your ClickHouse version, because meanings can vary for specific flags.

Practical Troubleshooting Workflow

When queries behave unexpectedly:

• capture relevant settings from system.settings
• compare across working and failing sessions
• check user profile or role differences
• test controlled overrides with SET in one session

This workflow isolates whether issue is SQL logic, configuration, or permission policy.

Persisting and Auditing Setting Changes

If a setting must remain stable across sessions, persist it through user profile or server configuration rather than repeated SET in client code. Keep a small audit query that records effective values at job startup to simplify incident analysis when behavior changes after deployment.

Common Pitfalls

• Assuming SET modifies server-wide behavior for all users.
• Inspecting one setting while related limits remain unchanged.
• Ignoring user profile restrictions that override session intent.
• Treating all numeric settings as simple booleans without verifying semantics.
• Comparing behavior across sessions without capturing setting snapshots.

Summary

• Use system.settings to read active flag values and defaults.
• Use getSetting for inline diagnostics in SQL queries.
• Distinguish session-level changes from server or profile defaults.
• Check user/profile constraints when settings appear immutable.
• Capture grouped setting snapshots for faster troubleshooting and reproducibility.