ClickHouse DB::Exception: Empty query

The "DB::Exception: Empty query" error in ClickHouse is raised when the server receives a query string that is empty, contains only whitespace, or consists entirely of comments with no executable statement. The error code is EMPTY_QUERY.

Impact

The request fails immediately. No resources are consumed. While this error is harmless, frequent occurrences may indicate bugs in application code or client configuration issues that should be addressed.

Common Causes

1. Application bug sending empty strings -- a code path that constructs SQL dynamically produces an empty result.
2. Client configuration issue -- a database client or driver sending a keepalive or initialization query that is blank.
3. Comment-only queries -- submitting a SQL file that contains only comments and no actual statements.
4. Trailing semicolons parsed as separate queries -- some clients split on semicolons and send the empty string after the last one.
5. Conditional query building -- application logic that conditionally builds query parts but produces nothing under certain conditions.
6. Copy-paste errors -- accidentally executing an empty editor buffer or whitespace selection.

Troubleshooting and Resolution Steps

1. Check your application code. If the query is built dynamically, log the final SQL string before sending it:

   query = build_query(params)
   if not query.strip():
       raise ValueError("Generated query is empty")
   client.execute(query)
   

2. Handle trailing semicolons. If splitting SQL files by semicolons, filter out empty statements:

   statements = sql_text.split(';')
   statements = [s.strip() for s in statements if s.strip()]
   

3. Check client driver settings. Some drivers send initialization queries on connect. Verify these are not empty:

   # Example: check JDBC connection URL for init queries
   jdbc:clickhouse://host:8123/db?init_sql=SELECT 1
   

4. Verify SQL files are not comment-only:

   -- This file contains only comments
   -- No actual SQL statement follows
   -- This will produce an EMPTY_QUERY error
   

   Add at least one executable statement.

5. Add input validation. Before sending any query to ClickHouse, validate it is not empty:

   -- Simple validation: at minimum, a query should contain a keyword
   -- Implement this check in your application layer
   

Best Practices

• Always validate query strings in application code before sending them to ClickHouse.
• When splitting multi-statement SQL files, filter out empty strings and comment-only segments.
• Log the actual query text in your application for debugging -- empty query errors become trivial to diagnose when you can see what was sent.
• Configure database connection pools to use SELECT 1 as a health check query rather than an empty string.
• In CI/CD pipelines that run SQL files, add a pre-check that the file contains at least one valid statement.

Frequently Asked Questions

Q: Is an empty query harmful to ClickHouse?
A: No. It is rejected immediately with minimal overhead. However, frequent empty queries in logs may indicate application bugs that should be fixed.

Q: Does a query containing only comments trigger this error?
A: Yes. ClickHouse strips comments during parsing, and if nothing remains after comment removal, it raises EMPTY_QUERY.

Q: My application sends a semicolon by itself and gets this error. Why?
A: A bare semicolon ; is parsed as an empty statement. Some clients and drivers split multi-statement strings on semicolons and send each part individually. The trailing semicolon produces an empty final statement.

Q: How do I prevent this error in batch SQL execution?
A: Filter your statement list before execution. Remove entries that are empty or contain only whitespace and comments. Most ClickHouse client libraries do not do this automatically.