このドキュメントでは、OceanBaseデータベースがサポートするJSONデータのセミ構造化エンコーディング機能について説明します。
注意
V4.4.1バージョン以降、テーブルレベルパラメータSEMISTRUCT_ENCODING_TYPEは廃止され、SEMISTRUCT_PROPERTIESに置き換えられました。
OceanBaseデータベースは、MySQLテナントでテーブル作成時にセミ構造化エンコーディングを有効にすることをサポートしています。主にテーブルレベルパラメータSEMISTRUCT_PROPERTIESで制御されますが、テーブルのROW_FORMAT=COMPRESSEDも設定する必要があります。そうでない場合、エラーが発生します。
注意点
SEMISTRUCT_PROPERTIES=(encoding_type=encoding)の場合、テーブルは半構造化テーブルと見なされ、テーブル全体のJSON列に半構造化エンコードが有効になります。SEMISTRUCT_PROPERTIES=(encoding_type=none)の場合、テーブルは構造化テーブルと見なされます。- また、
freq_thresholdパラメーターを使用して頻度しきい値を設定することもできます。半構造化エンコードを有効にすると、システムはJSONデータ内の各パスの出現頻度を分析し、設定されたしきい値よりも高い頻度で現れるパスを独立したサブ列として格納します。これらのサブ列は頻繁な列と呼ばれます。例えば、ユーザーテーブルがあり、JSONフィールドにユーザー情報が格納されていると仮定します。90%のユーザーがnameとageフィールドを持っている場合、システムは自動的にnameとageを独立した頻繁な列として抽出し、クエリ時にはJSON全体を解析することなくこれらの列に直接アクセスすることで、クエリ性能を向上させます。具体的な構文とパラメータ説明については、CREATE TABLEを参照してください。 - 現在の
encoding_typeとfreq_thresholdはOnline DDL構文であり、Offline DDL構文はサポートされていません。
データ形式
JSONデータを一定の形式に従って構造化列に分割して格納する場合、JSON列から分割された列はサブ列と呼ばれます。サブ列は、疎列や頻繁な列など、さまざまなタイプに分割することができます。
- 疎列：一部のJSONには存在し、一部のJSONには存在しないサブ列で、その出現頻度がテーブルレベルパラメータ
freq_thresholdで指定されたしきい値を下回ります。 - 頻繁な列：JSON内での出現頻度がテーブルレベルパラメータ
freq_thresholdで指定されたしきい値を上回るサブ列です。これらのサブ列は独立した列として格納され、フィルタリングクエリの性能を向上させます。
例：
{"id": 1001, "name": "n1", "nickname": "nn1"}
{"id": 1002, "name": "n2", "nickname": "nn2"}
{"id": 1003, "name": "n3", "nickname": "nn3"}
{"id": 1004, "name": "n4", "nickname": "nn4"}
{"id": 1005, "name": "n5"}
ここで、id と name はすべてのJSONに含まれるフィールドで、出現頻度は100%です。nickname は4つのJSONにしか含まれておらず、出現頻度は80%です。
freq_threshold を100%に定義すると、nickname は疎列として導出され、id と name は頻繁な列として導出されます。80%に定義すると、nickname、id、name はすべて頻繁な列として導出されます。
例
- セミ構造化エンコーディングを有効にする
注意
セミ構造化エンコーディング機能を有効にする場合は、クラスタパラメータ micro_block_merge_verify_level をデフォルト設定の 2 に保つ必要があります。マイクロブロックマージ検証を無効にしないでください。
CREATE TABLE t1( j json)
ROW_FORMAT=COMPRESSED
SEMISTRUCT_PROPERTIES=(encoding_type=encoding, freq_threshold=50);
詳細な構文については、CREATE TABLEを参照してください。
CREATE TABLE t1(j json);
ALTER TABLE t1 SET ROW_FORMAT=COMPRESSED SEMISTRUCT_PROPERTIES = (encoding_type=encoding, freq_threshold=50);
その他の構文については、ALTER TABLEを参照してください。
一部の変更制限：
- フリーズン列のしきい値を変更する場合、半構造化データが有効になっていないとエラーは発生しませんが、変更は反映されません。
- ダイレクトロード中またはテーブルがロックされている場合、
freq_thresholdパラメータは変更できません。 - いずれかのサブパラメータを変更しても、残りのサブパラメータには影響しません。
- セミ構造化エンコーディングを無効にする
SEMISTRUCT_PROPERTIES を (encoding_type=none) に設定すると、セミ構造化エンコーディングが無効になります。この操作は既存のデータには影響せず、以降に書き込まれるデータにのみ適用されます。以下はセミ構造化エンコーディングを無効にする例です：
ALTER TABLE t1 SET ROW_FORMAT=COMPRESSED SEMISTRUCT_PROPERTIES = (encoding_type=none);
- セミ構造化エンコーディングの設定を確認する
SHOW CREATE TABLE ステートメントを使用して、セミ構造化エンコーディングの設定を確認します。例：
SHOW CREATE TABLE t1;
実行結果は次のとおりです：
+-------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Table | Create Table |
+-------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| t1 | CREATE TABLE `t1` (
`j` json DEFAULT NULL
) ORGANIZATION INDEX DEFAULT CHARSET = utf8mb4 ROW_FORMAT = COMPRESSED COMPRESSION = 'zstd_1.3.8' REPLICA_NUM = 1 BLOCK_SIZE = 16384 USE_BLOOM_FILTER = FALSE ENABLE_MACRO_BLOCK_BLOOM_FILTER = FALSE TABLET_SIZE = 134217728 PCTFREE = 0 SEMISTRUCT_PROPERTIES=(ENCODING_TYPE=ENCODING, FREQ_THRESHOLD=50) |
+-------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1 row in set
SEMISTRUCT_PROPERTIES=(encoding_type=encoding) の場合にのみ、このパラメータ情報がクエリ結果に表示されます。これはセミ構造化エンコーディング機能が有効であることを意味します。
セミ構造化エンコーディングを使用すると、JSON_VALUE() 関数 の条件フィルタリングクエリのパフォーマンスを向上させることができます。OceanBaseは、JSONセミ構造化エンコーディング技術に基づき、JSON_VALUE 式を使用した条件フィルタリングクエリのパフォーマンスを最適化しています。JSONデータがサブ列に分割されているため、システムはエンコード後のサブ列データに直接基づいてフィルタリングを実行でき、完全なJSON構造を復元する必要がないため、クエリ効率が大幅に向上します。
クエリ例：
-- nameフィールドの値が'Devin'の行を照会する
SELECT * FROM t WHERE JSON_VALUE(j_doc, '$.name' RETURNING CHAR) = 'Devin';
文字セットに関する注意事項：
OceanBaseのJSONは
utf8_binエンコードを使用します。文字列ホワイトボックスフィルタリングが正常に動作するようにするため、次の設定を推奨します：
SET @@collation_server = 'utf8mb4_bin';
SET @@collation_connection='utf8mb4_bin';