セミ構造化エンコーディング

このドキュメントでは、OceanBaseデータベースがサポートするJSONデータのセミ構造化エンコーディング機能について説明します。

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はすべて頻繁な列として導出されます。

例

1. セミ構造化エンコーディングを有効にする

   注意

   セミ構造化エンコーディング機能を有効にする場合は、クラスタ構成パラメータ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パラメータを変更できません。
   • いずれかのサブパラメータを変更しても、他のサブパラメータには影響しません。

2. 半構造化エンコードを無効にする

   SEMISTRUCT_PROPERTIES を (encoding_type=none) に設定すると、半構造化エンコードが無効になります。この操作は既存のデータには影響せず、今後書き込まれるデータにのみ適用されます。以下は半構造化エンコードを無効にする例です：

   ALTER TABLE t1 SET ROW_FORMAT=COMPRESSED SEMISTRUCT_PROPERTIES = (encoding_type=none);
   

3. 半構造化エンコードの設定を確認する

   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() 関数 の条件フィルタリングクエリのパフォーマンスを向上させることができます。JSON半構造化エンコード技術に基づき、OceanBaseは 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';