ClickHouse DB::Exception: Deprecated function

The "DB::Exception: Deprecated function" error in ClickHouse means you are calling a function that has been marked as deprecated and removed from the current version. ClickHouse occasionally deprecates functions in favor of better alternatives, and after a transition period, the old function stops working. The error code is DEPRECATED_FUNCTION.

Impact

Queries using the deprecated function fail immediately. This typically surfaces after a ClickHouse version upgrade when previously working queries suddenly stop executing. The impact can be widespread if the function is used in materialized views, application queries, or scheduled jobs.

Common Causes

1. ClickHouse version upgrade -- the most common trigger. A function that worked in the old version has been removed in the new one.
2. Using legacy query examples -- following outdated tutorials or documentation that reference functions no longer available.
3. Materialized views with deprecated functions -- MVs created with older functions break after an upgrade.
4. Third-party tools generating deprecated syntax -- BI tools or query builders that have not been updated to use current function names.

Troubleshooting and Resolution Steps

1. Read the error message for the replacement function. ClickHouse usually suggests the modern alternative:

   DB::Exception: Function 'globalIn' is deprecated, use 'in' instead
   

2. Check the ClickHouse changelog. Look up when the function was deprecated and what replaced it. The release notes document these changes explicitly.

3. Replace the deprecated function in your queries. Common deprecation replacements include:

   -- Example: some older functions have been unified or renamed
   -- Check docs for the specific function mentioned in your error
   

4. Update materialized views. If a MV uses a deprecated function, recreate it:

   -- Save the MV data if needed
   -- Drop and recreate with updated function
   DROP TABLE IF EXISTS mv_name;
   CREATE MATERIALIZED VIEW mv_name ...
   AS SELECT ... -- use the replacement function
   FROM source_table;
   

5. Search your codebase for all uses of the deprecated function. Do not just fix the one query that errored -- find all references:

   grep -r "deprecated_function_name" /path/to/your/sql/
   

6. Check if the function can be re-enabled temporarily. Some deprecated functions have a setting to re-enable them during a transition period:

   -- Check for allow_deprecated_* settings
   SELECT name, value, description FROM system.settings
   WHERE name LIKE '%deprecated%';
   

Best Practices

• Read the ClickHouse changelog before every version upgrade and search for deprecation notices.
• Test upgrades in a staging environment first, running your full query suite to catch deprecation errors before they hit production.
• Maintain a list of functions used across your application and check them against deprecation notices when planning upgrades.
• Avoid using experimental or functions marked as "may be removed" in production workloads.
• Set up automated testing that validates all materialized view definitions after upgrades.

Frequently Asked Questions

Q: Can I re-enable a deprecated function to avoid rewriting queries immediately?
A: Some deprecated functions have an allow_deprecated_* setting that re-enables them temporarily. Check system.settings for such options. However, this is a temporary workaround -- the function will eventually be removed entirely.

Q: How do I find out what function replaces a deprecated one?
A: The error message itself often names the replacement. The ClickHouse changelog and documentation also document replacements. If neither helps, search the ClickHouse GitHub issues or community forums.

Q: Will my data be lost if a materialized view uses a deprecated function?
A: Existing data in the MV's target table is not lost. However, new INSERTs into the source table will fail because the MV's SELECT cannot execute. You need to recreate the MV with updated functions to resume ingestion.

Q: How far in advance does ClickHouse announce deprecations?
A: It varies. Some functions are deprecated with warnings in one major release and removed in the next. Others may have a longer transition period. Regularly reviewing release notes is the best way to stay informed.