ClickHouse Go

その後のすべての例では、明示的に示されない限り、ClickHouse conn 変数が作成されて利用可能であると仮定します。

接続設定

接続を開くとき、Options構造体を使用してクライアントの動作を制御できます。以下の設定が利用可能です：

Protocol - ネイティブまたはHTTP。HTTPは現在、database/sql APIのみでサポートされています。
TLS - TLSオプション。非nil値はTLSを有効にします。TLSの使用を参照してください。
Addr - ポートを含むアドレスのスライス。
Auth - 認証の詳細。認証を参照してください。
DialContext - 接続を確立する方法を決定するカスタムダイヤル関数。
Debug - デバッグを有効にするためのtrue/false。
Debugf - デバッグ出力を消費する関数を提供します。debugをtrueに設定する必要があります。
Settings - ClickHouse設定のマップ。これらはすべてのClickHouseクエリに適用されます。コンテキストの使用を使用すると、クエリごとに設定を設定できます。
Compression - ブロックの圧縮を有効にします。圧縮を参照してください。
DialTimeout - 接続を確立する最大時間。デフォルトは 1s です。
MaxOpenConns - 同時に使用する最大接続数。アイドルプールにはより多くまたは少ない接続がある可能性がありますが、この数の接続のみを使用できます。デフォルトは MaxIdleConns+5 です。
MaxIdleConns - プール内で維持する接続の数。可能な場合は接続が再利用されます。デフォルトは 5 です。
ConnMaxLifetime - 接続を利用可能にする最大ライフタイム。デフォルトは1時間です。この時間の後、接続は破棄され、新しい接続がプールに追加されます。
ConnOpenStrategy - ノードアドレスのリストをどのように消費して接続を開くかを決定します。複数ノードへの接続を参照してください。
BlockBufferSize - 一度にバッファにデコードする最大ブロック数。大きな値はメモリの代償に並列性を増やします。ブロックサイズはクエリに依存するため、接続でこれを設定できますが、返すデータに基づいてクエリごとに上書きすることをお勧めします。デフォルトは 2 です。

接続プール

クライアントは接続プールを維持し、必要に応じてこれらをクエリを跨いで再利用します。最も多く MaxOpenConns は同時に使用され、プールの最大サイズは MaxIdleConns によって制御されます。クライアントは各クエリ実行のためにプールから接続を取得し、再利用のためにプールに戻します。接続はバッチの生涯の間使用され、 Send() で解放されます。

ユーザーが MaxOpenConns=1 を設定しない限り、プール内の同じ接続が後続のクエリに使用される保証はありません。これはあまり必要ありませんが、ユーザーが一時テーブルを使用している場合には必要です。

また、デフォルトで ConnMaxLifetime は1時間です。これは、ノードがクラスタから離れた場合にClickHouseへの負荷が不均一になるケースを引き起こす可能性があります。ノードが利用できなくなると接続は他のノードに均等に振り分けられます。これらの接続は保持され、デフォルトで1時間の間はリフレッシュされません。問題のあるノードがクラスタに戻っても同様です。負荷の高いワークロードの場合はこの値を下げることを検討してください。

TLSの使用

低レベルでは、すべてのクライアント接続メソッド（DSN/OpenDB/Open）は、Goのtlsパッケージを使用して安全な接続を確立します。Options構造体が非nilの tls.Config ポインタを含む場合、クライアントはTLSを使用することを認識します。

この最小限の TLS.Config は通常、ClickHouseサーバーのセキュアなネイティブポート（通常9440）に接続するのに十分です。ClickHouseサーバーに有効な証明書（期限切れ、誤ったホスト名、一般的に認識されたルート認証機関によって署名されていない）がない場合、 InsecureSkipVerify をtrueに設定することができますが、これは強く推奨されません。

追加のTLSパラメータが必要な場合、アプリケーションコードは tls.Config 構造体の必要なフィールドを設定するべきです。これには、特定の暗号スイートの強制、特定のTLSバージョンの強制（1.2または1.3など）、内部CA証明書チェーンの追加、ClickHouseサーバーによって要求された場合のクライアント証明書（および秘密鍵）の追加、そしてより専門的なセキュリティセットアップに付随するその他のオプションが含まれます。

認証

接続情報にAuth構造体を指定してユーザー名とパスワードを指定します。

複数ノードへの接続

複数のアドレスを Addr 構造体を通じて指定できます。

2つの接続戦略が利用可能です：

ConnOpenInOrder （デフォルト） - アドレスは順番に消費されます。後のアドレスは、リストに含まれる早いアドレスへの接続に失敗した場合にのみ使用されます。これは実質的にフェイルオーバー戦略です。
ConnOpenRoundRobin - ラウンドロビン戦略を使用してアドレス間の負荷をバランスさせます。

これはオプション ConnOpenStrategy を通じて制御できます。

実行

任意のステートメントを Exec メソッドを通じて実行できます。これはDDLおよび簡単なステートメントに有用です。大きな挿入やクエリ反復には使用しないでください。

クエリにContextを渡す能力に注意してください。これは特定のクエリレベルの設定を渡すのに使用できます - コンテキストの使用を参照してください。

バッチ挿入

大量の行を挿入するには、クライアントはバッチセマンティクスを提供しています。これは、行を追加できるバッチの準備が必要です。これは最終的に Send() メソッドを通じて送信されます。バッチはSendが実行されるまでメモリに保持されます。

ClickHouseに対する推奨事項はここにも適用されます。バッチはゴルーチン間で共有しないでください - 各Routineごとに別々のバッチを構築してください。

上記の例から、行を追加する際には変数の型がカラムの型と一致する必要があることに注意してください。マッピングは通常明白ですが、このインターフェースは柔軟性を提供し、精度の損失がない限り型は変換されます。たとえば、次のことが示されています。

各カラム型に対するサポートされたgo型の完全な要約については、型変換を参照してください。

行のクエリ

ユーザーは QueryRow メソッドを使用して単一の行をクエリするか、 Query を介して結果セットを反復するためのカーソルを取得できます。前者はデータがシリアライズされる先を受け入れますが、後者は各行で Scan を呼び出す必要があります。

どちらの場合でも、シリアライズしたい各カラムの値を格納する変数のポインタを渡す必要があることに注意してください。これらは、デフォルトで、 SELECT ステートメントで指定された順序で渡す必要があります - デフォルトでは、 SELECT * の場合、カラム宣言の順序が使用されます。

挿入と同様に、Scanメソッドはターゲット変数が適切な型である必要があります。これは再度柔軟であることを目指しており、精度の損失が可能であれば型が変換されます。たとえば、上記の例ではUUIDカラムが文字列変数に読み取られています。各カラム型に対するサポートされたgo型の完全なリストについては、型変換を参照してください。

最後に、 Query および QueryRow メソッドに Context を渡す能力に注意してください。これはクエリレベルの設定に使用できます - 詳細はコンテキストの使用を参照してください。

非同期挿入

非同期挿入はAsyncメソッドを介してサポートされています。これにより、クライアントがサーバーに挿入を完了するまで待機するか、データを受信した時点で応答するかを指定できます。これは実質的にパラメータ wait_for_async_insert を制御します。

列指向挿入

挿入は列形式で行うことができます。これは、データがすでにこの構造である場合、行にピボットする必要を回避することにより、パフォーマンスの利点を提供します。

構造体を使用する

ユーザーにとって、Golangの構造体はClickHouseにおけるデータ行の論理的な表現を提供します。これをサポートするために、ネイティブインターフェースはさまざまな便利な関数を提供します。

シリアライズでの選択

Selectメソッドは、一度の呼び出しでレスポンス行のセットを構造体のスライスにマールシャルすることを可能にします。

Append Struct

AppendStruct は、構造体を既存の batch に追加し、完全な行として解釈することを可能にします。これには、構造体のカラムがテーブルのカラムと名前と型が一致する必要があります。すべてのカラムには対応する構造体フィールドが必要ですが、いくつかの構造体フィールドには対応するカラム表現がない場合があります。これらは単に無視されます。

型変換

クライアントは、挿入と応答のマーシャリングの両方に対して、変数型を受け入れる柔軟性を可能な限り高めることを目指しています。ほとんどの場合、ClickHouseのカラム型に対して等価なGolang型が存在します。例えば、UInt64 は uint64 にマッピングされます。これらの論理的なマッピングは常にサポートされるべきです。ユーザーは、カラムに挿入するために使用したり、応答を受け取るために使用したりできる変数型を利用したいと考えるかもしれません。変数または受信データのいずれかの変換が最初に行われる場合があります。クライアントは、これらの変換を透過的にサポートすることを目指しているため、ユーザーは挿入前にデータを正確に揃えるために変換する必要がなく、クエリ時に柔軟なマーシャリングを提供します。この透過的な変換では精度の喪失は許可されません。例えば、uint32はUInt64列からのデータを受け取るために使用することはできません。逆に、文字列はフォーマット要件を満たす限り、datetime64フィールドに挿入できます。

現在サポートされているプリミティブ型の型変換はこちらに記載されています。

この努力は継続中であり、挿入（Append/AppendRow）と読み取り時（Scanを通じて）に分けることができます。特定の変換に対するサポートが必要な場合は、問題を提起してください。

複雑な型

日付/日時型

ClickHouseのGoクライアントは、Date、Date32、DateTime、および DateTime64の日付/日時型をサポートしています。日付は、2006-01-02形式の文字列として挿入できます。またはGoのtime.Time{}やsql.NullTimeを使用します。DateTimeもこれらの型をサポートしていますが、文字列は2006-01-02 15:04:05形式で渡す必要があり、オプションのタイムゾーンオフセット（例：2006-01-02 15:04:05 +08:00）が必要です。time.Time{}およびsql.NullTimeは、読み取り時にもサポートされており、sql.Scannerインターフェイスの任意の実装も利用できます。

タイムゾーン情報の扱いは、ClickHouseの型や、値の挿入または読み取りに依存します：

DateTime/DateTime64
- 挿入時に値はUNIXタイムスタンプ形式でClickHouseに送信されます。タイムゾーンが提供されていない場合、クライアントはクライアントのローカルタイムゾーンを想定します。time.Time{}またはsql.NullTimeは、その結果としてエポックに変換されます。
- 選択時に、カラムに設定されたタイムゾーンが、time.Time値を返す際に使用されます。設定されていない場合、サーバーのタイムゾーンが使用されます。
Date/Date32
- 挿入時には、日付をUNIXタイムスタンプに変換する際に日付のタイムゾーンが考慮されます。すなわち、日付としてのストレージの前にタイムゾーンによってオフセットされます。ClickHouseのDate型にはロケールがないため、これは文字列値で指定されない限りローカルタイムゾーンが使用されます。
- 選択時には、日付がtime.Time{}またはsql.NullTime{}のインスタンスにスキャンされ、タイムゾーン情報なしで返されます。

配列

配列はスライスとして挿入される必要があります。要素の型ルールは、プリミティブ型に対するものと一致します。すなわち、可能な範囲で要素が変換されます。

スキャン時にはスライスへのポインタを提供する必要があります。

マップ

マップは、前述の型ルールに準拠するキーと値を持つGolangマップとして挿入される必要があります。

タプル

タプルは、任意の長さのカラムのグループを表します。カラムは明示的に名前を付けることも、型のみを指定することもできます（例：

これらのアプローチのうち、名前付きタプルはより柔軟性があります。無名のタプルはスライスを使用して挿入および読み取りする必要がありますが、名前付きタプルはマップとも互換性があります。

完全な例 - flatten_tested=0

注：型付きスライスとマップがサポートされているため、すべての名前付きタプルのサブカラムが同じ型である必要があります。

ネスト

ネストフィールドは、名前付きタプルの配列に相当します。ユーザーがflatten_nestedを1または0に設定したかどうかによって使用法が変わります。

flatten_nestedを0に設定すると、ネストしたカラムは単一のタプルの配列として保持されます。これにより、ユーザーは挿入や取得のためにマップのスライスを使用し、任意のレベルのネストを行うことができます。マップのキーはカラムの名前と等しくなければならず、以下の例のように示されます。

注：マップはタプルを表すため、map[string]interface{}型である必要があります。値は現在、強く型付けされていません。

デフォルト値の1がflatten_nestedに使用される場合、ネストされたカラムは別々の配列にフラット化されます。これにより、挿入および取得のためにネストされたスライスを使用する必要があります。任意のレベルのネストが機能する可能性がありますが、これは正式にはサポートされていません。

完全な例 - flatten_nested=1

注：ネストされたカラムは同じ次元でなければなりません。例えば、上述の例では、Col_2_2とCol_2_1は同じ数の要素を持っている必要があります。

より簡潔なインターフェースとネスティングの公式サポートを考慮すると、flatten_nested=0を推奨します。

ジオタイプ

クライアントは、Point、Ring、Polygon、および Multi Polygon のジオタイプをサポートしています。これらのフィールドは、github.com/paulmach/orbパッケージを使用してGolangで使用されます。

UUID

UUID型は、github.com/google/uuidパッケージによってサポートされています。ユーザーは、UUIDを文字列として送信したり、sql.ScannerまたはStringifyを実装した任意の型としてマーシャリングしたりすることもできます。

Decimal

Decimal型は、github.com/shopspring/decimalパッケージによってサポートされています。

Nullable

GoのNil値は、ClickHouseのNULLを表します。これは、フィールドがNullableとして宣言されている場合に使用できます。挿入時には、通常のカラムとNullableバージョンの両方にNilを渡すことができます。前者の場合、型のデフォルト値が保存されます。例えば、文字列の場合は空の文字列です。Nullableバージョンの場合、NULL値がClickHouseに保存されます。

スキャン時に、ユーザーは nil 値をNullableフィールドのために表すために、*string のような nil をサポートする型へのポインタを渡す必要があります。以下の例では、Nullable(String)のcol1は、したがって**stringを受け取ります。これによりnilが表現できるようになります。

クライアントは追加で、sql.Null*型（例：sql.NullInt64）をサポートします。これらは、それぞれのClickHouse型と互換性があります。

大きな整数 - Int128, Int256, UInt128, UInt256

64ビットを超える数値型は、ネイティブなGo bigパッケージを使用して表されます。

圧縮

圧縮方法のサポートは、使用しているプロトコルに依存します。ネイティブプロトコルの場合、クライアントはLZ4とZSTD圧縮をサポートしています。これは、ブロックレベルでのみ実行されます。圧縮は、接続の設定にCompression設定を含めることによって有効にできます。

HTTP経由の標準インターフェースを使用している場合、追加の圧縮手法が利用可能です。詳細については、database/sql API - 圧縮を参照してください。

パラメータバインディング

クライアントは、Exec、Query、およびQueryRowメソッドのためのパラメータバインディングをサポートしています。以下の例に示すように、これは名前付き、番号付き、位置指定のパラメータを使用してサポートされています。これについての例を以下に示します。

特殊ケース

デフォルトでは、スライスはクエリにパラメータとして渡された場合、値のカンマ区切りリストに展開されます。ユーザーが値のセットを [] でラップして挿入する必要がある場合は、ArraySetを使用する必要があります。

グループ/タプルが必要な場合は、( ) でラップされ、IN演算子と共に使用するために、GroupSetを使用できます。これは、以下の例に示すように、複数のグループが必要なケースに特に便利です。

最後に、DateTime64フィールドはパラメータが適切に表示されるように精度が必要です。フィールドの精度レベルはクライアントには不明ですが、ユーザーはそれを提供しなければなりません。これを簡素化するために、DateNamedパラメータを提供します。

コンテキストの使用

Goのコンテキストは、締切、キャンセレーション信号、および他のリクエストスコープの値をAPIの境界を越えて渡す手段を提供します。接続上のすべてのメソッドは、最初の変数としてコンテキストを受け入れます。前の例ではcontext.Background()が使用されていましたが、ユーザーはこの機能を利用して設定や締切を渡し、クエリをキャンセルすることができます。

withDeadlineで作成されたコンテキストを渡すことで、クエリには実行時間の制限を設けることができます。これは絶対的な時間であり、有効期限が切れると接続が解放され、ClickHouseにキャンセル信号が送信されます。WithCancelを代わりに使用して、クエリを明示的にキャンセルすることもできます。

ヘルパーの clickhouse.WithQueryID と clickhouse.WithQuotaKey を使用すると、クエリIDとクオータキーを指定することができます。クエリIDは、ログ内でのクエリ追跡やキャンセル目的に役立ちます。クオータキーは、ユニークなキー値に基づいてClickHouseの使用制限を設けるために使用されます - 詳細についてはクオータ管理を参照してください。

ユーザーはまた、コンテキストを使用して特定のクエリに対してのみ設定を適用することができます - 接続全体ではなく、接続設定に示されています。

最後に、clickhouse.WithBlockSizeを介してブロックバッファのサイズを制御できます。これは接続レベルの設定BlockBufferSizeを上書きし、メモリ内でデコードされて保持されるブロックの最大数を制御します。大きな値は、メモリの代償としてより多くの並列化を意味する可能性があります。

以下に上記の例を示します。

進捗/プロファイル/ログ情報

クエリに関して進捗、プロファイル、およびログ情報を要求することができます。進捗情報は、ClickHouseで読み取りおよび処理された行数およびバイト数の統計を報告します。対照的に、プロファイル情報はクライアントに返されるデータの要約を提供し、バイト（非圧縮）、行、およびブロックの合計を含みます。最後に、ログ情報はスレッドに関する統計を提供し、メモリ使用量やデータ速度を含みます。

この情報を得るには、ユーザーはコンテキストを使用する必要があり、コールバック関数を渡すことができます。

動的スキャン

ユーザーは、スキーマやフィールドの型がわからないテーブルを読み取る必要がある場合があります。これは、アドホックデータ分析が行われる場合や、汎用ツールが書かれる場合に一般的です。これを達成するために、クエリ応答ではカラムタイプ情報が利用可能です。これは、Goのリフレクションを使って、スキャンに渡すことができる正しい型の変数のインスタンスを作成するために使用できます。

外部テーブル

外部テーブルは、クライアントがSELECTクエリを介してデータをClickHouseに送信できるようにします。このデータは一時テーブルに配置され、評価のためにクエリ自体で使用できます。

外部データをクエリでクライアントに送信するには、ユーザーはコンテキストを介してこれを渡す前に ext.NewTable を使用して外部テーブルを構築する必要があります。

Open Telemetry

ClickHouseは、ネイティブプロトコルの一部としてトレースコンテキストを渡すことを可能にします。クライアントは、clickhouse.withSpan関数を介してスパンを作成し、これをコンテキストを介して渡すことができます。

トレースの活用に関する詳細は、OpenTelemetryサポートの下を参照してください。

データベース/SQL API

database/sqlまたは「標準」APIは、アプリケーションコードが基盤となるデータベースに無関心であるべきシナリオでクライアントを使用できるようにします。これはある種のコストがかかります - 追加の抽象化レイヤーと間接化、およびClickHouseと必ずしも一致しないプリミティブです。しかし、これらのコストは通常、ツールが複数のデータベースに接続する必要があるシナリオでは受け入れられます。

さらに、このクライアントはHTTPをトランスポートレイヤーとして使用することをサポートしており、データは最適なパフォーマンスのためにネイティブ形式でエンコードされます。

以下は、ClickHouse APIのドキュメント構造に合わせることを目指しています。

標準APIのフルコード例はこちらで見つけることができます。

接続

接続は、clickhouse://<host>:<port>?<query_option>=<value>という形式のDSN文字列とOpenメソッド、またはclickhouse.OpenDBメソッドを介して達成できます。後者はdatabase/sql仕様の一部ではありませんが、sql.DBインスタンスを返します。このメソッドは、database/sql仕様を通じて明示的に公開する明確な手段がないプロファイリングなどの機能を提供します。

以降のすべての例では、明示的に示されない限り、ClickHouseの conn 変数が作成され、利用可能であると仮定します。

接続設定

以下のパラメータをDSN文字列に渡すことができます：

hosts - ロードバランシングおよびフェイルオーバーのための単一アドレスホストのカンマ区切りリスト - 複数ノードへの接続を参照してください。
username/password - 認証資格情報 - 認証を参照してください。
database - 現在のデフォルトデータベースを選択する
dial_timeout - 期間文字列は、符号付きの可能性がある小数のシーケンスであり、各小数にはオプションの分数と300ms、1sのような単位の接尾辞があります。有効な時間単位はms、s、mです。
connection_open_strategy - random/in_order（デフォルトはrandom） - 複数ノードに接続するを参照してください。
- round_robin - セットからラウンドロビンサーバーを選択します
- in_order - 指定された順序で最初のライブサーバーが選択されます
debug - デバッグ出力を有効にする（ブール値）
compress - 圧縮アルゴリズムを指定する - none（デフォルト）、zstd、lz4、gzip、deflate、br。trueに設定すると、lz4が使用されます。ネイティブ通信については、lz4とzstdのみがサポートされます。
compress_level - 圧縮レベル（デフォルトは0）。詳しくは圧縮を参照してください。これはアルゴリズム特有です：
- gzip - -2（最高のスピード）から9（最高の圧縮）
- deflate - -2（最高のスピード）から9（最高の圧縮）
- br - 0（最高のスピード）から11（最高の圧縮）
- zstd、lz4 - 無視される
secure - セキュアなSSL接続を確立します（デフォルトはfalse）
skip_verify - 証明書の検証をスキップします（デフォルトはfalse）
block_buffer_size - ユーザーがブロックバッファのサイズを制御できるようにします。BlockBufferSizeを参照してください（デフォルトは2）。

接続プーリング

ユーザーは、複数ノードへの接続で説明されているように、提供されたノードアドレスのリストの使用を影響を与えることができます。ただし、接続管理とプーリングは意図的にsql.DBに委任されています。

HTTP経由での接続

デフォルトでは、接続はネイティブプロトコルを介して確立されます。HTTPが必要なユーザーは、DSNを修正してHTTPプロトコルを含めるか、接続オプションにプロトコルを指定することでこれを有効にできます。

複数ノードへの接続

OpenDBを使用する場合は、ClickHouse APIで使用されているのと同じオプションアプローチを使用して複数のホストに接続します。 ConnOpenStrategyをオプションとして指定できます。

DSNベースの接続の場合、文字列は複数のホストとconnection_open_strategyパラメーターを受け入れ、その値をround_robinまたはin_orderに設定できます。

TLSの使用

DSN接続文字列を使用する場合、SSLは「secure=true」パラメータを介して有効にできます。OpenDBメソッドは、ネイティブAPIのTLSと同じアプローチを採用しており、非nil TLS構造体の指定に依存しています。DSN接続文字列は、SSL検証をスキップするためにskip_verifyパラメーターをサポートしますが、OpenDBメソッドは、構成を渡すことを許可するため、より高度なTLS構成に必要です。

認証

OpenDBを使用する場合、認証情報は通常のオプションを介して渡すことができます。DSNベースの接続の場合、接続文字列にユーザー名とパスワードをパラメータとして渡すか、アドレスにエンコードされた資格情報として渡すことができます。

実行

接続が取得されると、ユーザーはExecメソッドを介してsql文を実行することができます。

このメソッドは、コンテキストを受け取ることはサポートしていません - デフォルトでは、バックグラウンドコンテキストで実行されます。ユーザーは必要に応じてExecContextを使用できます - コンテキストの使用を参照してください。

バッチ挿入

バッチセマンティクスは、Beingメソッドを介してsql.Txを作成することによって達成できます。これにより、INSERT文を使用してPrepareメソッドを取得できます。これにより、行をExecメソッドを使用して追加できるsql.Stmtが返されます。バッチは、最初のsql.TxでCommitが実行されるまでメモリに蓄積されます。

行のクエリ

単一の行のクエリは、QueryRowメソッドを使用して実行できます。これにより、スキャンを行うために変数へのポインタを伴う*sql.Rowが返されます。QueryRowContextのバリアントにより、バックグラウンド以外のコンテキストを渡すことができます - コンテキストの使用を参照してください。

複数行を繰り返すには、Queryメソッドを使用します。これにより、行を反復処理するためにNextを呼び出すことができる*sql.Rows構造体が返されます。QueryContextの同等のものはコンテキストの渡しを可能にします。

非同期挿入

非同期挿入は、ExecContextメソッドを介して挿入を実行することで達成できます。これは、非同期モードが有効になったコンテキストを渡す必要があります。これにより、クライアントがサーバーが挿入を完了するまで待つか、データが受信された時点で応答するかを指定できます。これは、wait_for_async_insertパラメータを制御します。

列指向の挿入

標準インターフェースではサポートされていません。

構造体の使用

標準インターフェースではサポートされていません。

型変換

標準のdatabase/sqlインターフェースは、ClickHouse APIと同じ型をサポートする必要があります。いくつかの例外があり、主に複雑な型については、以下にドキュメントされています。ClickHouse APIに類似して、クライアントは挿入およびレスポンスのマシュアリングのために可能な限り柔軟性を持つことを目指しています。詳細については型変換を参照してください。

複雑な型

特に明記されている場合を除いて、複雑な型の処理はClickHouse APIと同様であるべきです。違いはdatabase/sqlの内部によるものです。

マップ

ClickHouse APIとは異なり、標準APIはマップをスキャンタイプで厳密に型付けする必要があります。たとえば、ユーザーはMap(String,String)フィールドに対してmap[string]interface{}を渡すことはできず、代わりにmap[string]stringを使用する必要があります。interface{}変数は常に互換性があり、より複雑な構造に使用できます。ストラクチャは読み取り時にサポートされていません。

挿入の動作はClickHouse APIと同様です。

Compression

標準APIは、ネイティブな ClickHouse API と同様に、ブロックレベルでの lz4 および zstd 圧縮アルゴリズムをサポートしています。さらに、HTTP接続に対してはgzip、deflate、およびbr圧縮もサポートされています。これらのどれかが有効になっている場合、圧縮は挿入時およびクエリ応答時のブロックに対して行われます。pingやクエリリクエストなどの他のリクエストは圧縮されません。これは lz4 および zstd オプションと一貫しています。

接続を確立するために OpenDB メソッドを使用する場合、Compression設定を渡すことができます。これには圧縮レベルを指定する機能も含まれています（以下参照）。DSNを使って sql.Open で接続する場合は、compress パラメータを使用します。これは、gzip、deflate、br、zstd、または lz4 という特定の圧縮アルゴリズム、またはブーリアンフラグである可能性があります。trueに設定された場合、lz4 が使用されます。デフォルトは none すなわち圧縮無効です。

適用された圧縮レベルは、DSNパラメータ compress_level または Compressionオプションの Level フィールドで制御できます。これはデフォルトで0ですが、アルゴリズムによって異なります：

gzip - -2 (最良の速度) から 9 (最良の圧縮)
deflate - -2 (最良の速度) から 9 (最良の圧縮)
br - 0 (最良の速度) から 11 (最良の圧縮)
zstd, lz4 - 無視される

Parameter Binding

標準APIは、ClickHouse API と同様のパラメータバインディング機能をサポートしており、Exec、Query、および QueryRow メソッド（およびそれらの相当する Context バリアント）にパラメータを渡すことができます。位置指定、名前付き、および番号付きパラメータがサポートされています。

注意特別なケースは依然として適用されます。

Using Context

標準APIは、ClickHouse API と同様に、期限、キャンセル信号、およびその他のリクエストスコープの値をコンテキストを通じて渡す機能をサポートしています。ClickHouse APIとは異なり、これは Exec のようなメソッドの Context バリアントを使用することで実現されます。デフォルトではバックグラウンドコンテキストを使用するメソッドは、コンテキストを最初のパラメータとして渡すことができる ExecContext バリアントを持っています。これにより、アプリケーションフローの任意の段階でコンテキストを渡すことができるようになります。たとえば、ユーザーは ConnContext を介して接続を確立する際や、QueryRowContext を介してクエリ行をリクエストする際にコンテキストを渡すことができます。使用可能なすべてのメソッドの例は以下に示されています。

コンテキストを使用して期限、キャンセル信号、クエリID、クォータキー、および接続設定を渡す詳細については、ClickHouse API におけるコンテキストの使用を参照してください。

Sessions

ネイティブ接続は本質的にセッションを持っていますが、HTTP経由の接続では、ユーザーがコンテキストに設定として渡すためのセッションIDを作成する必要があります。これにより、セッションにバインドされる機能（例：一時テーブル）を使用できるようになります。

Dynamic Scanning

ClickHouse API と同様に、カラム型情報が利用可能であり、これによりユーザーは正しく型付けされた変数のランタイムインスタンスを作成し、Scanに渡すことができます。これは、型が不明なカラムを読み取ることを可能にします。

External Tables

外部テーブルは、クライアントがClickHouseにデータを送信できるようにし、SELECTクエリを使用します。このデータは一時テーブルに配置され、クエリ自体で評価に使用できます。

クエリと一緒に外部データをクライアントに送信するには、ユーザーは ext.NewTable を使用して外部テーブルを構築し、それをコンテキストを介して渡す必要があります。

Open Telemetry

ClickHouseは、ネイティブプロトコルの一部としてトレースコンテキストを渡すことを許可します。クライアントは、clickhouse.withSpan 関数を介してSpanを作成し、これをコンテキストを通じて渡すことでこれを実現します。HTTPがトランスポートとして使用される場合はサポートされません。