Skip to content

Support Decimal256 #377

Open

Description

@thomasj02

Clickhouse supports Decimal256, with precision up to 76 (https://clickhouse.com/docs/en/sql-reference/data-types/decimal). However, clickhouse-cpp only supports up to Decimal128.

Abseil doesn't have an int256, but boost::multiprecision does (https://www.boost.org/doc/libs/1_85_0/libs/multiprecision/doc/html/boost_multiprecision/tut/ints/cpp_int.html). There are many other int256 implementations available online, and clang has support for _BitInt(256)

Activity

  1. monkeyboiii commented on Jun 11, 2025

    @monkeyboiii

    Second this

  2. polyglotAI-bot commented on Nov 18, 2026

    @polyglotAI-bot
    Collaborator

    Recommendation: Keep open — maintainer decision
    Decimal256 is not supported on master. A maintainer decides on the design: Decimal256 needs a 256-bit value type, and the library has none (Int256 and UInt256 are not supported either). Until then, the client should reject a precision over 38 with a clear error: today it misreads the data.

    • Category: Feature
    • Classification: impact: none · area: Data types & formats (Decimal256)
    • Status on master: Not supported on master — on a0ac408 (default 2.x build options) with ClickHouse 26.10.4.207, the client reads each 32-byte Decimal256 value as 16 bytes (run below).
    • Breaking change: No — can be done without a break: add a 256-bit value type and ColumnDecimal methods for it; columns with a precision up to 38 keep the current API.
    • Duplicates / related: Related: Unknown type names inside a container are misread instead of rejected #589 (unknown type names such as Int256 and UInt256 inside a container are misread instead of rejected; open PR Reject unknown type names inside containers #590 rejects them)

    Analysis: The type parser knows only Decimal, Decimal32, Decimal64, and Decimal128 (clickhouse/types/type_parser.cpp:72-75). The server sends a Decimal256 column as Decimal(76, S), and the parser accepts it as Decimal. ColumnDecimal stores every precision above 18 in a ColumnInt128 (clickhouse/columns/decimal.cpp:67-73), and the precision check is only a TODO (clickhouse/types/types.cpp:320). A Decimal(39..76, S) value has 32 bytes on the wire, so Select() reads half of each value: the callback gets wrong values, then Select() fails with an error that does not name the type (unimplemented 72, can't read packet type from input stream, unsupported column type: ); with one small positive value the result is correct by accident. Insert() into a Decimal256 column sends 16 bytes for each value, so the server waits until its receive timeout (300 s) and the insert fails. Until the type is supported, a caller can read the value as text with toString() (case toString(Decimal256) below).

    Reproduction: complete program and output
    #include <clickhouse/client.h>
    
    #include <cstdlib>
    #include <iostream>
    #include <string>
    
    using namespace clickhouse;
    
    static Client MakeClient() {
        const char* host = std::getenv("CLICKHOUSE_HOST");
        const char* port = std::getenv("CLICKHOUSE_PORT");
        return Client(ClientOptions()
                          .SetHost(host ? host : "localhost")
                          .SetPort(port ? std::stoi(port) : 9000));
    }
    
    // Print the type and the values of each column of each non-empty block, then the result.
    static void RunSelect(const std::string& label, const std::string& sql) {
        try {
            Client client = MakeClient();
            client.Select(sql, [&](const Block& block) {
                if (block.GetRowCount() == 0) return;
                for (size_t c = 0; c < block.GetColumnCount(); ++c) {
                    auto col = block[c];
                    std::cout << label << ": " << block.GetColumnName(c) << " " << col->Type()->GetName() << " =";
                    for (size_t r = 0; r < block.GetRowCount(); ++r) {
                        if (auto d = col->As<ColumnDecimal>()) std::cout << " " << d->At(r);  // the unscaled value
                        else if (auto u = col->As<ColumnUInt64>()) std::cout << " " << u->At(r);
                        else if (auto s = col->As<ColumnString>()) std::cout << " " << s->At(r);
                    }
                    std::cout << "\n";
                }
            });
            std::cout << label << ": no exception\n";
        } catch (const std::exception& e) {
            std::cout << label << ": exception: " << e.what() << "\n";
        }
    }
    
    int main() {
        // Control: Decimal128 is supported. Expected d = 100 200 300 (1.00, 2.00, 3.00).
        RunSelect("Decimal128(2), 3 rows", "SELECT toDecimal128(number + 1, 2) AS d, number AS n FROM numbers(3)");
        // Decimal256(2): the server sends the type name Decimal(76, 2), 32 bytes for each value.
        RunSelect("Decimal256(2), 1 row", "SELECT toDecimal256(1, 2) AS d");
        RunSelect("Decimal256(2), 2 rows", "SELECT toDecimal256(number + 1, 2) AS d FROM numbers(2)");
        RunSelect("Decimal256(2), -1.00", "SELECT toDecimal256(-1, 2) AS d");
        RunSelect("Decimal(40, 2) + UInt64", "SELECT CAST(number + 1 AS Decimal(40, 2)) AS d, number AS n FROM numbers(3)");
        // Workaround: let the server convert the value to a string.
        RunSelect("toString(Decimal256)", "SELECT toString(toDecimal256(number + 1, 2)) AS s FROM numbers(2)");
    
        // Insert into a Decimal256 column.
        try {
            Client client = MakeClient();
            client.Execute("DROP TABLE IF EXISTS issue377");
            client.Execute("CREATE TABLE issue377 (d Decimal256(2)) ENGINE = Memory");
            auto d = std::make_shared<ColumnDecimal>(76, 2);
            d->Append(std::string("1.50"));
            d->Append(std::string("2.25"));
            Block block;
            block.AppendColumn("d", d);
            client.Insert("issue377", block);
            std::cout << "insert Decimal256(2): no exception\n";
        } catch (const std::exception& e) {
            std::cout << "insert Decimal256(2): exception: " << e.what() << "\n";
        }
        RunSelect("rows after insert", "SELECT toString(count()) AS s FROM issue377");
        MakeClient().Execute("DROP TABLE IF EXISTS issue377");
        return 0;
    }

    Output on master (a0ac408), ClickHouse 26.10.4.207, default 2.x build options. d prints the unscaled value: 100 is 1.00. The program took 5 minutes, because the insert case waits for the server timeout:

    Decimal128(2), 3 rows: d Decimal(38,2) = 100 200 300
    Decimal128(2), 3 rows: n UInt64 = 0 1 2
    Decimal128(2), 3 rows: no exception
    Decimal256(2), 1 row: d Decimal(76,2) = 100
    Decimal256(2), 1 row: no exception
    Decimal256(2), 2 rows: d Decimal(76,2) = 100 0
    Decimal256(2), 2 rows: exception: unimplemented 72
    Decimal256(2), -1.00: d Decimal(76,2) = -100
    Decimal256(2), -1.00: exception: can't read packet type from input stream
    Decimal(40, 2) + UInt64: exception: unsupported column type: 
    toString(Decimal256): s String = 1 2
    toString(Decimal256): no exception
    insert Decimal256(2): exception: DB::NetException: Timeout exceeded while reading from socket (peer: …, local: …, 300000 ms)
    rows after insert: s String = 0
    rows after insert: no exception
    

    Automated triage by Polyglot AI. A maintainer makes the final decision.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions