JDBC catalog
JDBC catalog は、データを取り込むことなく、JDBC を通じてアクセスされるデータソースからデータをクエリすることを可能にする一種の external catalog です。
また、JDBC catalog を使用して、JDBC データソースからデータを直接変換してロードすることもできます。INSERT INTO を使用します。
JDBC catalog は MySQL と PostgreSQL をサポートしています。
PostgreSQL の精度未指定 numeric
精度とスケールを指定していない PostgreSQL の numeric および decimal 列は、VARCHAR ではなく StarRocks の DECIMAL(38,18)(Decimal128)にマッピングされます。整数部は最大 20 桁、小数部は最大 18 桁です。値は正確に表現できる必要があります。オーバーフロー、小数点以下 18 桁を超えるゼロ以外の数字、NaN、無限大は読み取りエラーになります。小数部の余分な末尾ゼロは許可され、NULL は NULL のままです。
この変更により、これらの列の並べ替え、比較、グループ化、関数解決には数値のセマンティクスが使用されます。精度とスケールを明示した numeric 列のマッピングは変更されません。精度未指定 numeric 列を読み取るスキャンでは、変換後に StarRocks で評価するため、述語、式、集約、結合のプッシュダウンを保守的に無効にします。PostgreSQL ビューや native_query の戻り値も、メタデータが精度未指定 numeric を示す場合は同じマッピングを使用します。
範囲外の値には、業務に適した精度とスケールへ明示的に変換する PostgreSQL ビューを使用できます。テキスト表現の保持が必要な場合は、ビューからテキストを返してください。
PostgreSQL の uuid
v4.2 以降、PostgreSQL の uuid 列は VARBINARY ではなく StarRocks の VARCHAR(36) にマッピングされます。値そのものは変わりません。JDBC ドライバーは java.util.UUID を返し、JDBC bridge は以前からそれを正規形(小文字)の 36 文字のテキストとして書き出しているため、同じバイト列のラベルがバイナリからテキストに変わるだけです。NULL は NULL のままで、uuid[] は引き続きサポートされません。
StarRocks の他の UUID 経路はもともとすべてテキストです。uuid() と uuid_v7() 関数、Iceberg の UUIDType、FILES() で読む Parquet の UUID 列がそれにあたります。
この変更により、これらの列の比較、並べ替え、グループ化、関数解決には文字列のセマンティクスが使用されます。uuid 列に対する比較は、これまで失敗していましたが、PostgreSQL へプッシュダウンされるようになります。=、!=、<=>、範囲比較、BETWEEN、ORDER BY ... LIMIT はいずれもリモートのステートメントに渡され、どれも COLLATE "C" を伴いません。正規形テキストの順序は PostgreSQL が値を並べる順序と完全に一致するため collation は不要であり、そもそも PostgreSQL はこの型への collation 指定を拒否します。したがってプッシュダウンされた比較は、その列の PostgreSQL インデックスを引き続き利用できます。uuid 列に対する MIN と MAX だけは例外で、StarRocks 側で計算されます。値の順序は明確であるにもかかわらず、PostgreSQL はこの型に対する min、max 集約関数を定義していないためです。列がバイナリだったために 16 進数で表示されていた値(binary_encoding_level が ALL の場合や、ARRAY や STRUCT に入れ子になっている場合)は、UUID のテキストそのものが返るようになります。
uuid 列をそのまま射影する非同期マテリアライズドビューはその列を VARBINARY として実体化しているため、型の変更によって次回のリフレッシュで無効化されます。ALTER MATERIALIZED VIEW ... ACTIVE では復旧できず、削除して作り直す必要があります。列をキャストしているマテリアライズドビューと通常の論理ビューは影響を受けません。そうしたマテリアライズドビューをまだ作り直していない catalog では、catalog プロパティ postgresql.uuid.mapping を varbinary に設定すると従来のマッピングを維持できます。
前提条件
- StarRocks クラスター内の FEs と BEs または CNs が、
driver_urlパラメーターで指定されたダウンロード URL から JDBC ドライバーをダウンロードできること。
JDBC catalog の作成
構文
CREATE EXTERNAL CATALOG <catalog_name>
[COMMENT <comment>]
PROPERTIES ("key"="value", ...)
パラメーター
catalog_name
JDBC catalog の名前。命名規則は以下の通りです:
- 名前には文字、数字 (0-9)、アンダースコア (_) を含めることができます。文字で始める必要があります。
- 名前は大文字と小文字を区別し、長さは 1023 文字を超えることはできません。
comment
JDBC catalog の説明。このパラメーターはオプションです。
PROPERTIES
JDBC catalog のプロパティ。PROPERTIES には以下のパラメーターを含める必要があります:
| Parameter | Description |
|---|---|
| type | リソースのタイプ。値を jdbc に設定します。 |
| user | ターゲットデータベースに接続するために使用されるユーザー名。 |
| password | ターゲットデータベースに接続するために使用されるパスワード。 |
| jdbc_uri | JDBC ドライバーがターゲットデータベースに接続するために使用する URI。MySQL の場合、URI は "jdbc:mysql://ip:port" 形式です。PostgreSQL の場合、URI は "jdbc:postgresql://ip:port/db_name" 形式です。詳細は PostgreSQL を参照してください。 |
| driver_url | JDBC ドライバー JAR パッケージのダウンロード URL。例えば、https://repo1.maven.org/maven2/org/postgresql/postgresql/42.3.3/postgresql-42.3.3.jar です。 |
| driver_class | JDBC ドライバーのクラス名。一般的なデータベースエンジンの JDBC ドライバークラス名は以下の通りです:
|
オプションの PostgreSQL プロパティ
driver_class が PostgreSQL に設定されている場合、以下のオプションのプロパティを設定できます:
| パラメータ | デフォルト | 説明 |
|---|---|---|
| postgresql.uuid.mapping | varchar | PostgreSQL の uuid のマッピングを制御します。varchar は列を VARCHAR(36) にマッピングします。varbinary は v4.2 より前のマッピングに戻すもので、uuid 列を参照するマテリアライズドビューをまだ作り直していない catalog のための移行用です。認識できない値は無視され、varchar が使用されます。変更には ALTER CATALOG を使用してください(catalog のコネクタが再構築されます)。REFRESH EXTERNAL TABLE では JDBC テーブルのスキーマは再導出されません。 |
オプションの統計情報キャッシュプロパティ
StarRocks は JDBC データソースから読み取ったテーブルごとの統計情報をキャッシュし、クエリプランニング時のブロッキングを回避します。1 つのキャッシュエントリはテーブルの行数とデータソースが報告する列統計情報の両方を保持し、両者は一体として読み込みおよび削除されます。これらのプロパティを使用して、カタログごとにキャッシュの動作を調整できます。設定しない場合は、グローバル FE 設定値が使用されます。パラメータ名は列統計情報の導入以前のもので、変更されていません。
| パラメータ | デフォルト | 説明 |
|---|---|---|
| jdbc_row_count_cache_refresh_sec | 600 | バックグラウンド更新間隔(秒)。この間隔を過ぎると、古いキャッシュエントリを即座に返しながらバックグラウンドで非同期に再読み込みします。 |
| jdbc_row_count_cache_expire_sec | 1200 | 強制削除 TTL(秒)。この期間内にアクセスされなかったキャッシュエントリは削除されます。jdbc_row_count_cache_refresh_sec より大きい値を設定してください。 |
| jdbc_row_count_cache_max_size | 10000 | このカタログの統計情報キャッシュの最大テーブルエントリ数。 |
注意
FEs は JDBC catalog 作成時に JDBC ドライバー JAR パッケージをダウンロードし、BEs または CNs は最初のクエリ時に JDBC ドライバー JAR パッケージをダウンロードします。ダウンロードにかかる時間はネットワークの状況によって異なります。
PostgreSQL の配列
org.postgresql.Driver を使用すると、次の PostgreSQL 配列列を読み取れます。
| PostgreSQL の列型 | StarRocks の型 |
|---|---|
boolean[] | ARRAY<BOOLEAN> |
smallint[] | ARRAY<SMALLINT> |
integer[] | ARRAY<INT> |
bigint[] | ARRAY<BIGINT> |
real[] | ARRAY<FLOAT> |
double precision[] | ARRAY<DOUBLE> |
date[] | ARRAY<DATE> |
timestamp[](タイムゾーンなし) | ARRAY<DATETIME> |
text[]、varchar[]、char(n)[] | ARRAY<VARCHAR> |
一次元配列の要素順序、UTF-8 文字列、NULL 配列、空配列、NULL 要素は保持されます。char(n)[] は ARRAY<CHAR> ではなく ARRAY<VARCHAR> にマッピングされ、要素は PostgreSQL が格納する空白埋めをそのまま保持します。date[] と timestamp[] の要素はセッションのタイムゾーンに影響されない壁時計の値として読み取られ、0001-01-01 から 9999-12-31 の範囲外の要素(紀元前の日付や infinity)は別の値として読まれるのではなくクエリが失敗します。
その他の配列要素型はすべて未対応の型にマッピングされ、その列はクエリできません。numeric[]、uuid[]、time[]、bytea[]、json[]、jsonb[] に加えて timestamptz[] も含まれます。timestamp with time zone を ARRAY<DATETIME> として読み込むと、夏時間の繰り下げにあたる 2 つの時刻が同じ壁時計に潰れ、後段では区別できなくなるためです。
StarRocks 配列の位置は 1 から始まり、PostgreSQL の配列の下限は保持されません。たとえば PostgreSQL の [0:1]={a,b} は ["a","b"] として読み込まれ、StarRocks の items[1] は a を返します。このような列に対する定数の添字(items[1]、および等価な element_at(items, 1))は PostgreSQL で評価され、その要素だけが返されます。配列全体を読み戻してからローカルで添字を取ることはありません。添字はそのままプッシュダウンされ、下限は 1 であると仮定されます。PostgreSQL 自身が構築する配列の下限は 1 です。そのため、別の下限で格納された値では、プッシュダウンされた添字は StarRocks でローカルに評価した同じ添字とは異なる要素を、警告なく返します。[0:2]={zero,one,two} では、リモートの items[1] は one、ローカルでは zero です。
プッシュダウンの結果をローカルの評価と完全に一致させるには、enable_jdbc_array_lower_bound_correction を true に設定してください。この場合、プッシュダウンされる添字は各値自身の下限に合わせて補正されます。enable_jdbc_array_subscript_push_down を false に設定すると、このプッシュダウン自体を完全に無効化できます。フィルターと射影の両方の経路が閉じられ、配列カラム全体を読み戻して StarRocks で添字を取る動作に戻ります。
2 つの変数が組み合わさる方向は 1 つだけです。プッシュダウンを無効にすると、PostgreSQL に添字が届かないため、enable_jdbc_array_lower_bound_correction は何も制御しなくなります。変数の添字(items[id] など)、配列全体の比較、結合、ソート、およびグループ化や重複排除集約は StarRocks で実行されます。多次元配列の読み込みは明示的な未対応エラーとなり、一次元には展開されません。ただし多次元の値を保持する列に対する定数の添字は、他と同様にプッシュダウンされます。PostgreSQL は全次元を指定しない添字に対して NULL を返すため、列を直接読めばエラーになるところでクエリは NULL を返します。enable_jdbc_array_lower_bound_correction のどちらの設定でもこの挙動は変わりません。PostgreSQL は列に次元を記録しないためです(attndims は強制されず、同一の列が行ごとに異なる次元の値を保持できます)。ただし enable_jdbc_array_subscript_push_down を無効にすると変わります。その場合はカラムが再び直接読み取られるため、クエリは NULL ではなく未対応エラーになります。
例
以下の例では、2 つの異なる JDBC catalog を作成します。
-- PostgresSQL
CREATE EXTERNAL CATALOG jdbc0
PROPERTIES
(
"type"="jdbc",
"user"="postgres",
"password"="changeme",
"jdbc_uri"="jdbc:postgresql://127.0.0.1:5432/jdbc_test",
"driver_url"="https://repo1.maven.org/maven2/org/postgresql/postgresql/42.3.3/postgresql-42.3.3.jar",
"driver_class"="org.postgresql.Driver"
);
-- MySQL
CREATE EXTERNAL CATALOG jdbc1
PROPERTIES
(
"type"="jdbc",
"user"="root",
"password"="changeme",
"jdbc_uri"="jdbc:mysql://127.0.0.1:3306",
"driver_url"="https://repo1.maven.org/maven2/mysql/mysql-connector-java/8.0.28/mysql-connector-java-8.0.28.jar",
"driver_class"="com.mysql.cj.jdbc.Driver"
);
JDBC catalog の表示
現在の StarRocks クラスター内のすべての catalog をクエリするには、SHOW CATALOGS を使用します。
SHOW CATALOGS;
また、external catalog の作成ステートメントをクエリするには、SHOW CREATE CATALOG を使用します。以下の例では、jdbc0 という名前の JDBC catalog の作成ステートメントをクエリします。
SHOW CREATE CATALOG jdbc0;
JDBC catalog の削除
JDBC catalog を削除するには、DROP CATALOG を使用します。
以下の例では、jdbc0 という名前の JDBC catalog を削除します。
DROP Catalog jdbc0;
JDBC catalog のテーブルをクエリする
-
JDBC 互換クラスター内のデータベースを表示するには、SHOW DATABASES を使用します。
SHOW DATABASES FROM <catalog_name>; -
現在のセッションで目的の catalog に切り替えるには、SET CATALOG を使用します。
SET CATALOG <catalog_name>;次に、現在のセッションでアクティブなデータベースを指定するには、USE を使用します。
USE <db_name>;または、目的の catalog 内でアクティブなデータベースを直接指定するには、USE を使用します。
USE <catalog_name>.<db_name>; -
指定されたデータベース内の目的のテーブルをクエリするには、SELECT を使用します。
SELECT * FROM <table_name>;
Join プッシュダウン
v4.2 以降、同一の JDBC カタログに属する複数テーブルに対する結合(INNER JOIN および CROSS JOIN)を、外部データベース側へプッシュダウンできるようになりました。これにより、ソースデータベースは自身のインデックスやオプティマイザを用いて結合処理を実行し、結合結果のみをシステムへ返します。
Join プッシュダウンの設定
Join プッシュダウンはデフォルトで有効です。無効化するには、セッション変数 enable_jdbc_join_push_down を false に設定します。
SET enable_jdbc_join_push_down = false;
動作の仕組み
この最適化ルールが適用されると、オプティマイザは複数の JDBC スキャンにまたがるローカル結合を、リモートデータベースに対して JOIN を含む単一の SQL を発行する 1 つの JDBC スキャンに書き換えます。
例えば、同一の JDBC カタログ内にある 2 つの MySQL テーブルに対する以下のクエリを考えます。
SELECT o.order_id, c.region, o.amount
FROM jdbc0.db.orders o
JOIN jdbc0.db.customers c ON o.customer_id = c.customer_id
WHERE o.amount >= 20 AND c.region IN ('east', 'west');
enable_jdbc_join_push_down が false の場合、システムは 2 回のスキャンを実行し、その結果をローカルで結合します。一方、この変数が true の場合、結合を含むサブツリー全体がリモートデータベースへプッシュダウンされます。ローカルの実行計画には 1 つの JDBC スキャンノードのみが残り、プッシュダウンされる SQL は次のようになります。
SELECT `c1`, `c2`, `c3` FROM (
SELECT t0.`order_id` AS c1, t1.`region` AS c2, t0.`amount` AS c3
FROM (SELECT `order_id`, `customer_id`, `amount` FROM `db`.`orders` WHERE `amount` >= 20) t0
INNER JOIN (SELECT `region`, `customer_id` FROM `db`.`customers` WHERE `region` IN ('east', 'west')) t1
ON t0.`customer_id` = t1.`customer_id`
) sr_merged;
クエリに対して EXPLAIN を実行することで、結合がプッシュダウンされているかを確認できます。
適用範囲と制限事項
- 結合タイプ: INNER JOIN および CROSS JOIN のみがプッシュダウン対象です。外部結合、セミ結合、アンチ結合はローカル実行にフォールバックします。
- 同一カタログ: マージ対象となるすべてのテーブルは、同一の JDBC カタログ(同一の JDBC URI、認証情報、ドライバ)に属している必要があります。異なる JDBC カタログ間の結合や、JDBC テーブルとネイティブテーブルを混在させた結合はローカルで実行されます。
- テーブル間述語が必須: グループ内の 2 テーブルを結合する述語が少なくとも 1 つ存在する場合にのみプッシュダウンされます。純粋な直積(デカルト積)をリモートに送信することを避けるため、この条件を満たさない場合は適用されません。
- 述語プッシュダウンは全体適用: グループに属するすべての述語は、リモートの SQL 方言に完全に変換可能である必要があります。1 つでもプッシュダウンできない述語(例:StarRocks 固有の関数)がある場合、グループ全体がローカル結合にフォールバックします。
- 統計情報: マージされた JDBC スキャンは、単一テーブルの JDBC スキャンと同じデフォルト統計情報を再利用します。下流のオペレータからは、結合結果はデフォルトサイズの単一テーブルとして扱われ、基となるテーブルに基づくカーディナリティ推定は行われません。
PostgreSQL の日付とタイムスタンプ
JDBC catalog を通じて PostgreSQL の date と timestamp without time zone を読み取る場合、元の年月日と時刻が保持されます。JVM のデフォルトタイムゾーンによる時刻の変更はなく、タイムスタンプはマイクロ秒精度を保持します。サポートされる年の範囲は西暦 0001 年から 9999 年です。紀元前の日付、infinity、-infinity、または範囲外の値を読み取ると、年代や値を暗黙に変更せずエラーを返します。
ネイティブ SQL で JDBC データをクエリする
v4.1 以降、StarRocks は native_query テーブル関数を使用して、データベースネイティブの SELECT 文で JDBC データをクエリできます。
ソースデータベース側の Join、事前にフィルタリングしたサブクエリ、またはベンダー固有の SQL 構文など、単一の external table クエリでは表現できない SQL をソースデータベースで実行する必要がある場合に native_query を使用できます。StarRocks はパススルークエリの結果を通常のリレーションとして公開するため、StarRocks 側でさらにフィルター、Join、集計、射影を適用できます。
構文、制限事項、例については、native_query を参照してください。
FAQ
「Malformed database URL, failed to parse the main URL sections」というエラーが発生した場合はどうすればよいですか?
このようなエラーが発生した場合、jdbc_uri に渡した URI が無効です。渡した URI を確認し、有効であることを確認してください。詳細については、このトピックの「PROPERTIES」セクションのパラメーター説明を参照してください。