ClickHouse DB::Exception: Not implemented

The "DB::Exception: Not implemented" error in ClickHouse indicates that you are trying to use a feature or operation that ClickHouse recognizes syntactically but has not yet implemented. Unlike an unknown function or syntax error, the server knows what you are asking for -- it just cannot do it yet. The error code is NOT_IMPLEMENTED.

Impact

The query or operation fails completely. Since the feature does not exist in the current build, no workaround exists within the same syntax. You will need to find an alternative approach or upgrade to a version where the feature has been implemented.

Common Causes

1. Using SQL features not yet supported -- ClickHouse is actively developed and some SQL standard features are planned but not yet available.
2. Type conversions not implemented -- certain type casts or conversions between specific types may not be supported.
3. Engine-specific limitations -- some operations work with certain table engines but not others (e.g., ALTER operations not supported on Log family engines).
4. Experimental features that are partially implemented -- features behind allow_experimental_* flags may have incomplete implementations.
5. Platform-specific limitations -- some functions may not be implemented on all architectures or operating systems.
6. Operations on specific data types -- certain combinations of operations and data types (e.g., JSON, Map, or Geo types) may have gaps.

Troubleshooting and Resolution Steps

1. Read the error message for specifics. It usually describes what exactly is not implemented:

   DB::Exception: Not implemented: ALTER UPDATE is not supported for Log engine
   

2. Check your ClickHouse version. The feature may have been implemented in a newer release:

   SELECT version();
   

3. Search the ClickHouse changelog and GitHub issues. The feature might be planned or in progress. Search at github.com/ClickHouse/ClickHouse/issues for the specific feature.

4. Find a workaround. Common alternatives:

   -- If ALTER UPDATE is not supported on your engine, recreate the table
   CREATE TABLE new_table AS old_table ENGINE = MergeTree() ORDER BY id;
   INSERT INTO new_table SELECT * FROM old_table WHERE ...;
   DROP TABLE old_table;
   RENAME TABLE new_table TO old_table;
   

5. Use a different table engine. Some operations are only available with MergeTree-family engines:

   -- Log engines don't support mutations; use MergeTree instead
   CREATE TABLE my_table (...)
   ENGINE = MergeTree()
   ORDER BY (key_column);
   

6. Try an alternative function or approach. If a specific type conversion is not implemented, use an intermediate type:

   -- If direct cast is not implemented, go through an intermediate type
   SELECT toInt64(toString(special_type_column)) FROM my_table;
   

Best Practices

• Check the ClickHouse documentation for your specific version before relying on advanced or niche features.
• Use MergeTree-family engines for production tables -- they have the most complete feature set.
• Follow the ClickHouse roadmap and release notes to know when planned features become available.
• When evaluating ClickHouse for a new use case, prototype with your actual query patterns to discover any NOT_IMPLEMENTED gaps early.
• Report missing features on GitHub if they are important for your use case -- the ClickHouse team prioritizes based on community demand.

Frequently Asked Questions

Q: Does NOT_IMPLEMENTED mean the feature will be added in the future?
A: Not necessarily. It means the codebase has a placeholder or recognition for the concept, but the implementation is missing. Some of these are actively planned; others may remain unimplemented indefinitely. Check the GitHub issues for the feature's status.

Q: Can I contribute the implementation myself?
A: Yes. ClickHouse is open source and accepts contributions. If a feature is important to you, consider opening an issue or submitting a pull request on GitHub.

Q: Is NOT_IMPLEMENTED specific to certain table engines?
A: Sometimes. Many operations (like mutations, TTL, and projections) are only implemented for MergeTree-family engines. The same operation on a Memory, Log, or external engine may trigger NOT_IMPLEMENTED.

Q: I upgraded ClickHouse and now I get NOT_IMPLEMENTED on something that used to work. Is that possible?
A: It is rare but can happen if an experimental feature was restructured or if a deprecated code path was removed. Check the upgrade notes for breaking changes.