固定プランを使用する SQL 文の条件とパラメーター設定 - Hologres

固定プラン機能は、Hologres 実行エンジン専用の機能です。このトピックでは、固定プランを使用できる SQL 文の条件とパラメータ設定について説明します。

背景

固定プラン機能は、Hologres 実行エンジン専用の機能です。ほとんどの場合、SQL 文は、オプティマイザー、コーディネーター、クエリエンジン、ストレージエンジンなど、一連の Hologres コンポーネントによって処理されます。固定プランを使用すると、オプティマイザー、コーディネーター、および特定のクエリエンジンの処理をスキップすることで、SQL 文の実行を高速化できます。固定プランでは、固定フロントエンド (FE) ノードが SQL 文を固定クエリエンジンに配信します。これにより、実行パフォーマンスが大幅に向上し、高スループットのリアルタイムデータ書き込みと多数の同時クエリが実現します。固定プラン機能の詳細については、「アーキテクチャ」をご参照ください。

Hologres では、以下のシナリオで固定プラン機能が自動的に使用されます。

Flink を使用した Hologres へのリアルタイムデータ書き込み。
DataWorks の Data Integration を使用した Hologres へのリアルタイムデータ書き込み。
Holo Client を使用した Hologres へのデータ書き込み。

その他のデータ書き込みシナリオでは、以下のセクションの手順に従って、Grand Unified Configuration (GUC) パラメータを構成し、SQL 文に対して固定プラン機能を有効にすることができます。

説明

デフォルトでは、SQL 文が上記のシナリオで指定された条件を満たしている場合、固定プラン機能を使用して処理されます。それ以外の場合、SQL 文は固定プラン機能を使用して処理されません。

固定プラン機能に関連する GUC パラメータ

GUC パラメータ

次の表に、固定プラン機能に関連する GUC パラメータを示します。すべての GUC パラメータの有効値は、on と off です。デフォルトでは、すべての GUC パラメータは Holo Client で on に設定されており、セッションレベルで有効になります。

GUC パラメータ	説明	デフォルト値	GUC 変更レコード
hg_experimental_enable_fixed_dispatcher	Hologres インスタンスに対して固定プラン機能を有効にするかどうかを指定します。単一の行のデータの書き込み、更新、削除、またはクエリに使用される SQL 文は、固定プランを使用して処理できます。このような SQL 文には、INSERT、UPDATE、DELETE 文、およびプレフィックスクエリ文が含まれます。	on	該当なし。
hg_experimental_enable_fixed_dispatcher_for_multi_values	固定プランを使用して INSERT ON CONFLICT 文を実行し、複数の行にデータを書き込むことを許可するかどうかを指定します。説明書き込み操作の原子性は保証されません。エラーが報告されない場合は、すべての行にデータが書き込まれます。エラーが報告された場合は、行にデータが書き込まれないか、指定された行にデータが書き込まれます。書き込みに失敗した行に関する情報は、上位層アプリケーションに報告されます。上位層アプリケーションは、これらの行の書き込みを再試行します。	on	Hologres V1.3.35 以降では、この GUC パラメータは、固定プランを使用して INSERT、UPDATE、および DELETE 文を複数の行で実行することを許可するかどうかを指定します。
hg_experimental_enable_fixed_dispatcher_autofill_series	固定プランを使用して、SERIAL データ型の列を含む文の実行を許可するかどうかを指定します。クライアントのセッションレベルでこの機能を有効にすることをお勧めします。	off	Hologres V1.3.25 以降では、この GUC パラメーターのデフォルト値は `on` です。
hg_experimental_enable_fixed_dispatcher_for_update	固定プランを使用して UPDATE 文の実行を許可するかどうかを指定します。クライアントのセッションレベルでこの機能を有効にすることをお勧めします。	off	Hologres V1.3.25 以降では、このパラメーターは使用されなくなりました。条件を満たす UPDATE 文は、自動的に固定プランを使用して処理されます。UPDATE 文を使用して複数行のデータを更新する場合は、`set hg_experimental_enable_fixed_dispatcher_for_multi_values = on` を構成する必要があります。
hg_experimental_enable_fixed_dispatcher_for_delete	固定プランを使用して DELETE 文の実行を許可するかどうかを指定します。クライアントのセッションレベルでこの機能を有効にすることをお勧めします。	off	Hologres V1.3.25 以降では、このパラメーターは使用されなくなりました。条件を満たす DELETE 文は、自動的に固定プランを使用して処理されます。DELETE 文を使用して複数行のデータを削除する場合は、`set hg_experimental_enable_fixed_dispatcher_for_multi_values = on` を構成する必要があります。
hg_experimental_enable_fixed_dispatcher_for_scan	固定プランを使用してプレフィックスクエリ文の実行を許可するかどうかを指定します。説明プレフィックスクエリでは、クエリの文でテーブルの最初のいくつかのプライマリキー列のみが指定されます。Hologres は、固定プランを使用した列指向テーブルに対するプレフィックスクエリの実行をサポートしていません。	off	Hologres V1.3.35 以降でこのパラメータを使用することをお勧めします。
hg_experimental_enable_bhclient_cache_on_session	キャッシュモード (cached on session または cached on FE) を使用してデータをキャッシュするかどうかを指定します。有効値： on: [セッションにキャッシュ] モードを使用します。 off: [FE 上でキャッシュ] モードを使用します。説明 [cached on session] モードと [cached on FE] モードには、次の違いがあります。セッションキャッシュモードでは、各セッションにリーダーとライターが提供されます。このモードでは、接続ごとのスループットが向上しますが、このモードではステートメントの実行に時間がかかります。これは、初めてテーブルからデータを読み取るか、テーブルにデータを書き込むときに、リーダーとライターの起動に時間がかかるためです。 cached on FE モードでは、FE ノード上のすべてのセッションがリーダーとライターを共有します。セッションが閉じても、リーダーとライターは引き続き使用できます。これにより、リーダーとライターの起動時間が節約されます。	off	該当なし。
hg_experimental_disable_fixed_planner_conflict_pk_check	`INSERT INTO <table_name> VALUES (...) ON CONFLICT(<column>)` 構文でプライマリキー以外の列を指定できるかどうかを指定します。 false：許可されません。 true：許可されます。説明このパラメーターを true に設定すると、プライマリキー以外の列が許可されます。実際の状況では、INSERT ON CONFLICT 文は `ON CONFLICT(pk)` に基づいて実行されます。	false	Hologres V1.3 から V2.1.28 では、`ON CONFLICT(<column>)` で指定された列はプライマリキー列である必要があります。 Hologres V2.1.29 以降では、GUC パラメーターを使用して、`ON CONFLICT(<column>)` でプライマリキー以外の列を許可するかどうかを指定できます。

GUC パラメータの使用
- GUC パラメータの設定の確認
  次の SHOW 文を実行して、GUC パラメータの設定を確認できます。
```
SHOW <GUC_name>;
```
  次の例を参考にしてください。
```
-- インスタンスレベルで固定プラン機能が有効になっているかどうかを確認します。
SHOW hg_experimental_enable_fixed_dispatcher;
```
- GUC パラメータの構成
  - セッションレベルでの GUC パラメータの構成
    SET 文を使用して、セッションレベルで GUC パラメーターを構成できます。セッションレベルで GUC パラメーターを構成した場合、設定は現在のセッションでのみ有効になります。セッションが閉じられると、設定は無効になります。SQL 文を実行する前に、次の文を実行することをお勧めします。
```
SET <GUC_name> = <values>;
```
    GUC_name パラメータは GUC パラメータの名前を指定し、values パラメータは GUC パラメータに構成する値を指定します。
    次の例を参考にしてください。
```
-- 固定プランを使用して、複数の行にデータを書き込む INSERT ON CONFLICT 文の実行を許可します。
SET hg_experimental_enable_fixed_dispatcher_for_multi_values = on;
```
  - データベースレベルでの GUC パラメータの構成
    alter database xx set xxx 文を実行して、データベースレベルで GUC パラメーターを構成できます。GUC パラメーターを構成した後、構成を有効にするには接続を再接続する必要があります。新しいデータベースの場合、設定を手動で再構成する必要があります。サンプル文:
```
ALTER DATABASE <db_name> SET <GUC_name> = <values>;
```
    db_name はデータベース名に置き換え、GUC_name は GUC パラメータ名に置き換え、values は GUC パラメータに構成する値に置き換えます。
    次の例を参考にしてください。
```
-- データベースに対して固定プラン機能を有効にします。
ALTER DATABASE <db_name> SET hg_experimental_enable_fixed_dispatcher = on;
```

データ型に関する要件

各列に MONEY 型または MONEY 配列のデータを含めることはできません。
DML 操作 (INSERT、UPDATE、DELETE など) を実行するか、SELECT 文を実行する列では、次のデータ型がサポートされています。クエリ対象の列と SELECT 文の WHERE 句で指定された列は、次のデータ型のいずれかである必要があります。
- BOOLEAN (エイリアス：BOOL)
- SMALLINT
- INTEGER (エイリアス：INT または INT4)
- BIGINT (エイリアス：INT8)
- FLOAT (エイリアス：FLOAT4)
- DOUBLE PRECISION (エイリアス：FLOAT8)
- CHAR(n)
- VARCHAR(n)
- BYTEA
- JSON および JSONB
- TEXT (エイリアス：VARCHAR)
- TIMESTAMP WITH TIME ZONE (エイリアス：TIMESTAMPTZ)
- DATE
- TIMESTAMP
- DECIMAL (エイリアス：NUMERIC)
- ROARINGBITMAP
- TIME (Hologres V2.2 以降でサポート)
- TIMETZ (Hologres V2.2 以降でサポート)
- 配列型
  - boolean[]
  - smallint[]
  - int4[]
  - int8[]
  - float4[]
  - float8[]
  - char(n)[]
  - varchar(n)[]
  - text[]

INSERT 文

Hologres V3.2 以降のバージョンでは、固定プランを介したプライマリキーテーブルへの INSERT の RETURNING 句がサポートされています。

構文
固定プランを使用するには、次の構文で INSERT 文を実行します。
```
-- 単一行にデータを書き込みます。
INSERT INTO TABLE(col1,col2,col3..) VALUES(?,?,?..) ON conflict xxx;
-- 複数の行にデータを書き込みます。
INSERT INTO TABLE(col1,col2,col3..) VALUES(?,?,?..),(?,?,?..) ON conflict xxx;
```
説明
- INSERT 文を実行して、Hologres 内部テーブルにデータを書き込むことができますが、外部テーブルには書き込むことができません。
- INSERT 文を実行して、Hologres パーティションテーブルにデータを書き込むことができます。Hologres V1.3 以降では、INSERT 文を実行して、親パーティションテーブルにデータを書き込むことができます。
- 固定プランは、INSERT 文の RETURNING キーワードをサポートしていません。

INSERT ON CONFLICT 文を実行して単一行にデータを書き込む

次のタイプの INSERT 文がサポートされています。
- ON CONFLICT 句を含まない INSERT 文。
- ON CONFLICT DO NOTHING 句を含む INSERT 文。
- ON CONFLICT DO UPDATE 句を含む INSERT 文。プライマリキー以外のすべての列を更新する必要があります。ビジネス要件に基づいてプライマリキー列を更新するかどうかを指定できます。col = excluded.col 形式で更新する列を指定する必要があります。Hologres V1.3 以降では、プライマリキー以外の列の一部を更新できます。ただし、更新する列を col = excluded.col 形式で指定する必要もあります。

次の例を参考にしてください。

BEGIN;
CREATE TABLE test_insert_oneline (
    pk1 INT,
    pk2 INT,
    col1 INT,
    col2 INT,
    PRIMARY KEY (pk1, pk2)
);
COMMIT;

-- すべてのプライマリキー以外の列を更新します。この例では、固定プランを使用できます。
INSERT INTO test_insert_oneline
    VALUES (1, 2, 3, 4)
ON CONFLICT (pk1, pk2)
    DO UPDATE SET
        col1 = excluded.col1, col2 = excluded.col2;

-- プライマリキー列とプライマリキー以外の列を含むすべての列を更新します。この例では、固定プランを使用できます。
INSERT INTO test_insert_oneline
    VALUES (1, 2, 3, 4)
ON CONFLICT (pk1, pk2)
    DO UPDATE SET
        col1 = excluded.col1, col2 = excluded.col2, pk1 = excluded.pk1, pk2 = excluded.pk2;

-- 固定プランを使用するには、すべてのプライマリキー以外の列を更新する必要があります。この例では、col2 列は文で指定されていません。固定プランは、Hologres V1.3 以降でのみ使用できます。
INSERT INTO test_insert_oneline
    VALUES (1, 2, 3, 4)
ON CONFLICT (pk1, pk2)
    DO UPDATE SET
        col1 = excluded.col1;

-- 固定プランを使用するには、SET 句で col = excluded.col 形式で更新する列を指定する必要があります。この例では、固定プランを使用できません。
INSERT INTO test_insert_oneline
    VALUES (1, 2, 3, 4)
ON CONFLICT (pk1, pk2)
    DO UPDATE SET
        col1 = excluded.col1, col2 = 5;

INSERT ON CONFLICT 文を実行して複数の行にデータを書き込む

構文：
```
SET hg_experimental_enable_fixed_dispatcher_for_multi_values = ON;

INSERT INTO TABLE (col1, col2, col3..)
    VALUES (?, ?, ?..), (?, ?, ?..)
ON CONFLICT xxx;
```
- GUC パラメーター構成 hg_experimental_enable_fixed_dispatcher_for_multi_values = on; が必要です。Hologres V1.3.35 以降では、このパラメーターはデフォルトで on に設定されています。
- 書き込み操作の原子性は保証されません。エラーが報告されない場合は、すべての行にデータが書き込まれます。エラーが報告された場合は、行にデータが書き込まれないか、一部の行にデータが書き込まれます。

次の構文を使用して、複数の行にデータを書き込むこともできます。

SET hg_experimental_enable_fixed_dispatcher_for_multi_values = ON;

INSERT INTO TABLE selectunnest (ARRAY[TRUE, FALSE, TRUE]::bool[]), unnest(ARRAY[1, 2, 3]::int4[]), unnest(ARRAY[1.11, 2.222, 3]::float4[])
ON CONFLICT xxx;

GUC パラメーター hg_experimental_enable_fixed_dispatcher_for_multi_values を on に設定する必要があります。
ARRAY 型のデータはテーブルに書き込むことができません。
UNNEST 句では、指定された配列を対応する列の配列型に明示的に変換する必要があります。

次の例を参考にしてください。

BEGIN;
CREATE TABLE test_insert_multiline (
    pk1 int8,
    col1 float4,
    PRIMARY KEY (pk1)
);
COMMIT;

-- この例では、固定プランを使用できます。
SET hg_experimental_enable_fixed_dispatcher_for_multi_values = ON;

INSERT INTO test_insert_multiline
SELECT
    unnest(ARRAY[1, 2, 3]::int8[]),
    unnest(ARRAY[1.11, 2.222, 3]::float4[])
ON CONFLICT
    DO NOTHING;

-- この例では、UNNEST 句で指定された配列は、対応する列の配列型に明示的に変換されていません。したがって、固定プランを使用できません。
INSERT INTO test_insert_multiline
SELECT
    unnest(ARRAY[1, 2, 3]),
    unnest(ARRAY[1.11, 2.222, 3])
ON CONFLICT
    DO NOTHING;

-- 最初の列のデータ型は INT8 です。したがって、配列を INT8 型に明示的に変換する必要があります。この例では、配列は INT4 型に明示的に変換されています。したがって、固定プランを使用できません。
INSERT INTO test_insert_multiline
SELECT
    unnest(ARRAY[1, 2, 3]::int4[]),
    unnest(ARRAY[1.11, 2.222, 3]::float4[])
ON CONFLICT
    DO NOTHING;

テーブル内の特定の列を更新する
Hologres では、プライマリキーに基づいてテーブル内の特定の列を更新できます。次の条件が満たされている場合、固定プランを使用してテーブル内の特定の列を更新できます。
- 挿入および更新操作の列の数と順序は一貫しています。
- 更新する列は col = excluded.col 形式で指定されます。

条件句付きで UPDATE 文または INSERT 文を実行する

同じプライマリキーを共有する行の入力データの順不同の要件に対処し、HBase CheckAndPut をサポートするために、Hologres では固定プランを使用して、条件句付きの INSERT または UPDATE 文を実行できます。

単一行にデータを書き込む場合、固定プランを使用できます。複数行にデータを書き込む場合は、set hg_experimental_enable_fixed_dispatcher_for_multi_values=on; 構成を追加する必要があります。
WHERE 句に単一の非プライマリキーフィールドのみが含まれ、=, <>, >, >=, <, <=, IS NULL, and IS NOT NULL の演算子の一部が使用されている場合、coalesce 関数を呼び出してこのフィールドを処理できます。

次の例を参考にしてください。

BEGIN;
CREATE TABLE test_check_and_insert (
    pk INT,
    col INT,
    scn INT,
    PRIMARY KEY (pk)
);
COMMIT;

-- この例では、固定プランを使用できます。
-- 列の既存の値を定数と比較します。
INSERT INTO test_check_and_insert AS old
    VALUES (1, 1, 1)
ON CONFLICT (pk)
    DO UPDATE SET
        col = excluded.col, scn = excluded.scn
    WHERE
        old.scn > 0;

-- 列の既存の値を書き込む値と比較します。
INSERT INTO test_check_and_insert AS old
    VALUES (1, 1, 1)
ON CONFLICT (pk)
    DO UPDATE SET
        col = excluded.col, scn = excluded.scn
    WHERE
        old.scn > excluded.scn;

-- 既存の値が null の場合、coalesce 関数を使用できます。
INSERT INTO test_check_and_insert AS old
    VALUES (1, 1, 1)
ON CONFLICT (pk)
    DO UPDATE SET
        col = excluded.col, scn = excluded.scn
    WHERE
        coalesce(old.scn, 3) > 2;

INSERT INTO test_check_and_insert AS old
    VALUES (1, 1, 1)
ON CONFLICT (pk)
    DO UPDATE SET
        col = excluded.col, scn = excluded.scn
    WHERE
        coalesce(old.scn, 3) > excluded.scn;

-- この例では、固定プランを使用できます。
SET hg_experimental_enable_fixed_dispatcher_for_multi_values = ON;

-- 列の既存の値を定数と比較します。
INSERT INTO test_check_and_insert AS old
    VALUES (1, 1, 1), (2, 3, 4)
ON CONFLICT (pk)
    DO UPDATE SET
        col = excluded.col, scn = excluded.scn
    WHERE
        old.scn > 3;

-- UNNEST 句がサポートされています。
INSERT INTO test_check_and_insert AS old
SELECT
    unnest(ARRAY[5, 6, 7]::int[]),
    unnest(ARRAY[1, 1, 1]::int[]),
    unnest(ARRAY[1, 1, 1]::int[])
ON CONFLICT (pk)
    DO UPDATE SET
        col = excluded.col,
        scn = excluded.scn
    WHERE
        old.scn > 3;

DEFAULT 制約付きの列を含むテーブルにデータを書き込む
固定プランを使用して、DEFAULT 制約付きの列を含むテーブルにデータを書き込むことができます。
- 単一行のデータが挿入される場合、固定プランを使用できます。複数行にデータを書き込む場合、Hologres インスタンスのバージョンは V1.1.36 以降である必要があります。そうでない場合は、インスタンスを更新する必要があります。GUC パラメーター hg_experimental_enable_fixed_dispatcher_for_multi_values を on に設定する必要があります。
- Hologres V1.3 以降では、固定プランを使用して、DEFAULT 制約を持つ列を含むテーブルで INSERT ON CONFLICT 文を実行できます。Hologres V1.3 より前のバージョンでは、固定プランを使用して、DEFAULT 制約を持つ列を含むテーブルで INSERT ON CONFLICT 文を実行することはできません。
次の例を参考にしてください。
```
BEGIN;
CREATE TABLE test_insert_default (
    pk1 INT,
    col1 INT DEFAULT 99,
    PRIMARY KEY (pk1)
);
COMMIT;

-- この例では、固定プランを使用できます。
INSERT INTO test_insert_default (pk1)
    VALUES (1);

-- Hologres V1.1.36 以降のインスタンスを使用する必要があります。
SET hg_experimental_enable_fixed_dispatcher_for_multi_values = ON;

INSERT INTO test_insert_default (pk1)
    VALUES (1), (2), (3);
```
SERIAL データ型の列を含むテーブルにデータを書き込む
固定プランを使用して、SERIAL データ型の列を含むテーブルの単一行または複数行にデータを書き込むことができます。
- GUC パラメーター hg_experimental_enable_fixed_dispatcher_autofill_series を on に設定する必要があります。Hologres V1.3.25 以降では、このパラメーターのデフォルト値は on です。
- 複数行にデータを書き込む場合は、GUC パラメーター hg_experimental_enable_fixed_dispatcher_for_multi_values を on に設定する必要があります。
次の例を参考にしてください。
```
BEGIN;
CREATE TABLE test_insert_serial (
    pk1 INT,
    col1 SERIAL,
    PRIMARY KEY (pk1)
);
COMMIT;

-- この例では、固定プランを使用できます。
SET hg_experimental_enable_fixed_dispatcher_autofill_series = ON;

INSERT INTO test_insert_serial (pk1)
    VALUES (1);

-- この例では、固定プランを使用できます。
SET hg_experimental_enable_fixed_dispatcher_autofill_series = ON;

SET hg_experimental_enable_fixed_dispatcher_for_multi_values = ON;

INSERT INTO test_insert_serial (pk1)
    VALUES (1), (2), (3);
```

UPDATE 文

構文

固定プランを使用するには、次の構文で UPDATE 文を実行します。

SET hg_experimental_enable_fixed_dispatcher_for_update = ON;

UPDATE TABLE SET col1 = ?,col2 = ? WHERE pk1 = ? AND pk2 = ?;

使用上の注意

固定プランを使用して UPDATE 文を実行する場合は、次の点に注意してください。

外部テーブルではなく、内部テーブルのデータを更新できます。親パーティションテーブルではなく、子パーティションテーブルのデータを更新できます。指定されたテーブルにはプライマリキーが必要です。
GUC パラメーター hg_experimental_enable_fixed_dispatcher_for_update を on に設定する必要があります。Hologres V1.3.25 以降では、このパラメーターは使用されなくなりました。条件を満たす UPDATE 文は、自動的に固定プランを使用して処理されます。UPDATE 文を使用して複数行のデータを更新する場合は、GUC パラメーター hg_experimental_enable_fixed_dispatcher_for_multi_values を on に設定する必要があります。
SET 句でプライマリキー列を指定することはできません。
WHERE 句ですべてのプライマリキー列を指定する必要があります。
pk in (?,?,?) or pk = ANY() 形式を使用して、一度に複数の行を更新できます。例: pk1 in (1,2) and pk2 = any('{3,4}') and pk3 = 5。この場合、4 つの行 (1,3,5), (1,4,5), (2,3,5), and (2,4,5) が更新されます。
列の WHERE 句に指定できる条件は 1 つだけです。重複する条件は 1 つの条件と見なされます。

次の例を参考にしてください。

BEGIN;
CREATE TABLE test_update (
    pk1 INT,
    pk2 INT,
    col1 INT,
    col2 INT,
    PRIMARY KEY (pk1, pk2)
);
COMMIT;

-- この例では、固定プランを使用できます。詳細な例については、UPDATE 文の説明をご覧ください。
SET hg_experimental_enable_fixed_dispatcher_for_update = ON;

UPDATE
    test_update
SET
    col1 = 1,
    col2 = 2
WHERE
    pk1 = 3
    AND pk2 = 4;

-- この例では、固定プランを使用できます。
SET hg_experimental_enable_fixed_dispatcher_for_update = ON;

UPDATE
    test_update
SET
    col1 = 1
WHERE
    pk1 = 3
    AND pk2 = 4;

-- この例では、固定プランを使用できます。
SET hg_experimental_enable_fixed_dispatcher_for_update = ON;

UPDATE
    test_update
SET
    col1 = 1,
    col2 = 2
WHERE
    pk1 IN (1, 2)
    AND pk2 = ANY ('{3,4}');

-- この例では、WHERE 句の pk1 列に複数の条件が指定されています。したがって、固定プランを使用できません。
UPDATE
    test_update
SET
    col1 = 1,
    col2 = 2
WHERE
    pk1 = 3
    AND pk1 = 4;

-- この例では、WHERE 句の pk1 列に複数の条件が指定されています。したがって、固定プランを使用できません。
UPDATE
    test_update
SET
    col1 = 1,
    col2 = 2
WHERE
    pk1 IN (1, 2)
    AND pk1 = 1;

-- この例では、WHERE 句の pk1 列に複数の重複する条件が指定されています。したがって、固定プランを使用できます。
SET hg_experimental_enable_fixed_dispatcher_for_update = ON;

UPDATE
    test_update
SET
    col1 = 1,
    col2 = 2
WHERE
    pk1 IN (1, 2)
    AND pk1 IN (1, 2)
    AND pk2 = 4;

DELETE 文

構文

固定プランを使用するには、次の構文で DELETE 文を実行します。

SET hg_experimental_enable_fixed_dispatcher_for_delete = ON;

DELETE FROM TABLE
WHERE pk1 = ?
    AND pk2 = ?
    AND pk3 = ?;

使用上の注意
固定プランを使用して DELETE 文を実行する場合は、次の点に注意してください。
- 外部/外部テーブルではなく、内部テーブルのデータを削除できます。親パーティションテーブルではなく、子テーブルのデータを削除できます。指定されたテーブルにはプライマリキーが必要です。
- GUC パラメーター hg_experimental_enable_fixed_dispatcher_for_delete を on に設定する必要があります。Hologres V1.3.25 以降では、このパラメーターは使用されなくなりました。条件を満たす DELETE 文は、自動的に固定プランを使用して処理されます。DELETE 文を使用して複数行のデータを削除する場合は、GUC パラメーター hg_experimental_enable_fixed_dispatcher_for_multi_values を on に設定する必要があります。
- WHERE 句ですべてのプライマリキー列を指定する必要があります。Hologres V1.3 以降では、WHERE 句の最後のフィールドを非プライマリキーフィールドにすることができます。非プライマリキーフィールドは、=, <>, >, >=, <, <=, IS NULL, and IS NOT NULL の演算子をサポートしています。coalesce 関数を呼び出してこのフィールドを処理できます。
- pk in (?,?,?) or pk = ANY() 形式を使用して、一度に複数の行を削除できます。例: pk1 in (1,2) and pk2 = any('{3,4}') and pk3 = 5。この場合、4 つの行 (1,3,5), (1,4,5), (2,3,5), and (2,4,5) が削除されます。
- 列の WHERE 句に指定できる条件は 1 つだけです。重複する条件は 1 つの条件と見なされます。
次の例を参考にしてください。
```
BEGIN;
CREATE TABLE test_delete (
    pk1 INT,
    pk2 INT,
    col1 INT,
    col2 INT,
    PRIMARY KEY (pk1, pk2)
);
COMMIT;

-- この例では、固定プランを使用できます。詳細な例については、UPDATE 文の説明をご覧ください。
SET hg_experimental_enable_fixed_dispatcher_for_delete = ON;

DELETE FROM test_delete
WHERE pk1 = 1
    AND pk2 = 2;
```

SELECT 文

構文
固定プランを使用するには、次の構文で SELECT 文を実行します。
```
SELECT
    col1,
    col2,
    col3,
...
FROM
    TABLE
WHERE
    pk1 = ?
    AND pk2 = ?
    AND pk3 = ?;
```
- 外部テーブルではなく、内部テーブルのデータをクエリできます。
- 親パーティションテーブルではなく、子パーティションテーブルのデータをクエリできます。
- 指定されたテーブルにはプライマリキーが必要です。
キーと値のペアのポイントクエリを実行する
固定プランを使用してポイントクエリを実行する場合は、次の点に注意してください。
- WHERE 句ですべてのプライマリキー列を指定する必要があります。
- pk in (?,?,?) or pk = ANY() 形式を使用して、一度に複数の行をクエリできます。例: pk1 in (1,2) and pk2 = any('{3,4}') and pk3 = 5。この場合、4 つの行 (1,3,5), (1,4,5), (2,3,5), and (2,4,5) がクエリされます。
- 列の WHERE 句に指定できる条件は 1 つだけです。重複する条件は 1 つの条件と見なされます。
- 返される結果に制限を指定する場合、制限の値は 0 より大きい必要があります。
次の例を参考にしてください。
```
BEGIN;
CREATE TABLE test_select (
    pk1 INT,
    pk2 INT,
    col1 INT,
    col2 INT,
    PRIMARY KEY (pk1, pk2)
);
CALL set_table_property ('test_select', 'orientation', 'row');
COMMIT;

-- この例では、固定プランを使用できます。
SELECT * FROM test_select WHERE pk1 = 1 AND pk2 = 2;
```

プレフィックスクエリを実行する

構文

テーブルのプライマリキーに複数の列が含まれている場合、最初のいくつかのプライマリキー列のみを指定してプレフィックスクエリを実行できます。プレフィックスクエリは、左端のプレフィックスマッチングの原則に基づいて実行されます。構文：

SET hg_experimental_enable_fixed_dispatcher_for_scan = on;
SELECT col1,col2,col3,... FROM TABLE WHERE pk1 = ? AND pk2 = ?;
SELECT col1,col2,col3,... FROM TABLE WHERE pk1 = ? AND pk2 < ?;-- Hologres V1.1.48 以降では、最後のプライマリキー列を使用してクエリ範囲を指定できます。
SELECT col1,col2,col3,... FROM TABLE WHERE pk1 = ? AND pk2 BETWEEN ? AND ?;-- Hologres V1.1.48 以降では、最後のプライマリキー列を使用してクエリ範囲を指定できます。

使用上の注意
固定プランを使用してプレフィックスクエリを実行するには、次の点に注意してください。
- GUC パラメーター hg_experimental_enable_fixed_dispatcher_for_scan=on; を on に設定する必要があります。Hologres インスタンスのバージョンは V1.3.35 以降である必要があります。
- テーブルには分散キーを指定する必要があります。WHERE 句ですべての分散キー列を指定する必要があります。
- WHERE 句では、すべてのプライマリキー列のプレフィックスのみを指定する必要があります。Hologres V1.1.48 以降では、最後のプライマリキー列を使用してクエリ範囲を指定できます。
  説明
  プレフィックス列の例: プライマリキーに (pk1,pk2,pk3) が指定されている場合、プレフィックスとして (pk1) または (pk1,pk2) が使用されます。
- プレフィックスクエリは、行指向テーブルと行と列のハイブリッドテーブルに対してのみ実行できます。
- 列の WHERE 句に指定できる条件は 1 つだけです。重複する条件は 1 つの条件と見なされます。
- 返される結果に制限を指定する場合、制限の値は 0 より大きい必要があります。
説明
プレフィックスクエリは、すべての結果行を一度に返します。行のサイズが hg_experimental_fixed_scan_bytesize_limit パラメーターで指定された制限を超えると、エラーメッセージ scan result size larger than fixed scan size limit が報告されます。hg_experimental_fixed_scan_bytesize_limit パラメーターを適切な値に設定できます。デフォルト値は 1048576 で、1 MB を示します。
プライマリキーに (pk1,pk2,pk3,pk4) が構成され、分散キーに pk1,pk3 が構成されている場合。
```
BEGIN;
CREATE TABLE test_select_prefix (
    pk1 INT,
    pk2 INT,
    pk3 INT,
    pk4 INT,
    PRIMARY KEY (pk1, pk2, pk3, pk4)
);
CALL set_table_property ('test_select_prefix', 'orientation', 'row');
CALL set_table_property ('test_select_prefix', 'distribution_key', 'pk1,pk3');
COMMIT;

-- この例では、WHERE 句ですべての分散キー列が指定されていません。したがって、固定プランを使用できません。
SELECT * FROM test_select_prefix WHERE pk1 = ? AND pk2 = ?;
-- この例では、プライマリキー列のプレフィックスが使用されていません。したがって、固定プランを使用できません。
SELECT * FROM test_select_prefix WHERE pk1 = ? AND pk3 = ?;

-- この例では、固定プランを使用できます。
SET hg_experimental_enable_fixed_dispatcher_for_scan = ON;

SELECT * FROM test_select_prefix WHERE pk1 = ? AND pk2 = ? AND pk3 = ?;
```
pk in (?,?,?) または pk = ANY() 形式を使用して、一度に複数の行をクエリできます。構文:
```
pk1 IN (1,2) AND pk2 = 3 <=> (1,3) 行と (2,3) 行をクエリします。
pk2 =any('{3,4}') AND pk1 IN (1,2) <=> (1,3)、(1,4)、(2,3)、および (2,4) 行をクエリします。
```

次の例を参考にしてください。

BEGIN;
CREATE TABLE test_scan (
    pk1 INT,
    pk2 INT,
    pk3 INT,
    col1 INT,
    PRIMARY KEY (pk1, pk2, pk3)
);
CALL set_table_property ('test_scan', 'orientation', 'row');
CALL set_table_property ('test_scan', 'distribution_key', 'pk1,pk2');
COMMIT;

INSERT INTO test_scan
    VALUES (1, 2, 3, 4);

-- この例では、固定プランを使用できます。
SET hg_experimental_enable_fixed_dispatcher_for_scan = ON;

SELECT * FROM test_scan WHERE pk1 = 1 AND pk2 = 2;

-- この例では、固定プランを使用できます。
SET hg_experimental_enable_fixed_dispatcher_for_scan = ON;

SELECT * FROM test_scan WHERE pk1 = 1 AND pk2 IN (2, 3);

-- この例では、固定プランを使用できます。
SET hg_experimental_enable_fixed_dispatcher_for_scan = ON;

SELECT * FROM test_scan WHERE pk1 = ANY ('{3,4}') AND pk2 IN (2, 3);

-- この例では、固定プランを使用できます。最後のプライマリキー列を使用してクエリ範囲を指定できます。これは、Hologres V1.1.48 以降でサポートされています。
SET hg_experimental_enable_fixed_dispatcher_for_scan = ON;

SELECT * FROM test_scan WHERE pk1 = 1 AND pk2 = 1 AND pk3 > 1 AND pk3 < 4;

-- この例では、固定プランを使用できます。最後のプライマリキー列を使用してクエリ範囲を指定できます。これは、Hologres V1.1.48 以降でサポートされています。
SET hg_experimental_enable_fixed_dispatcher_for_scan = ON;

SELECT * FROM test_scan WHERE pk1 = 1 AND pk2 = 1 AND pk3 BETWEEN 1 AND 4;

-- この例では、WHERE 句ですべての分散キー列が指定されていません。したがって、固定プランを使用できません。
SELECT * FROM test_scan WHERE pk1 = 1;

-- この例では、プライマリキー列のプレフィックスが使用されていません。したがって、固定プランを使用できません。
SELECT * FROM test_scan WHERE pk2 = 2;

ページネーション付きの PrefixScan

Hologres V3.2 以降では、固定プランを使用してプライマリキープレフィックスに基づいてデータをクエリし、ページ分割された結果を返すことがサポートされています。

説明

デフォルトでは、結果はプライマリキーに基づいて昇順で返されます。たとえば、以下の最初の SQL コードブロックは、pk3 に基づいて昇順で結果を返します。
特定順序で結果を返すには、クラスタリングキーの定義で順序を定義し、データクエリ中に対応する GUC パラメーターを有効にします。クラスタリングキー列はプライマリキー列と一致している必要があります。たとえば、以下の 2 番目の SQL コードブロックは pk3:desc を指定し、pk3 に基づいて降順で結果を返します。

ページ分割された結果を昇順で返す

-- テーブルを作成する
CREATE TABLE test_scan(
  pk1 INT, 
  pk2 INT, 
  pk3 INT, 
  col1 INT, 
  PRIMARY KEY(pk1, pk2, pk3)
) WITH (
  orientation = 'row',
  distribution_key = 'pk1,pk2',
  clustering_key = 'pk1:asc,pk2:asc,pk3:asc'
);

-- テーブルにデータを挿入する
INSERT INTO test_scan VALUES (1,2,3,4),(1,2,5,6),(1,2,7,8);

-- offset を設定して特定の行から結果を返し、limit を設定して特定の数の行を返します。
SET hg_experimental_enable_fixed_dispatcher_for_scan = on;
-- デフォルトでは、ページ分割された結果は昇順で返されます。
SELECT * FROM test_scan WHERE pk1 = 1 AND pk2 = 2 OFFSET 1 limit 2;

ページ分割された結果を降順で返す

-- テーブルを作成する
CREATE TABLE test_scan(
  pk1 INT, 
  pk2 INT, 
  pk3 INT, 
  col1 INT, 
  PRIMARY KEY(pk1, pk2, pk3)
) WITH (
  orientation = 'row',
  distribution_key = 'pk1,pk2',
  clustering_key = 'pk1:asc,pk2:asc,pk3:desc'
);

-- テーブルにデータを挿入する
INSERT INTO test_scan VALUES (1,2,3,4),(1,2,5,6),(1,2,7,8);

-- 2 つの GUC パラメーターを有効にして、pk3 に基づいてページ分割された結果を降順で返します。
SET hg_experimental_enable_fixed_dispatcher_for_scan = on;
SET hg_experimental_enable_fixed_dispatcher_for_clustering_key_scan = on;
SELECT * FROM test_scan WHERE pk1 = 1 AND pk2 = 2 OFFSET 1 limit 2;

COPY 文

Hologres V1.3.17 以降では、固定プランを使用して COPY 文を実行できます。これは Fixed Copy と呼ばれます。COPY と Fixed Copy の違いの詳細については、「バッチ書き込みモードの比較」をご参照ください。

固定コピーのパラメータ構成の詳細については、「COPY」をご参照ください。文の例：

COPY table_name (column0, column1, column2)
FROM
    STDIN WITH (
        format BINARY,
        stream_mode TRUE,
        on_conflict UPDATE);

すべての列がコピーされない場合、特定の COPY 文は異なります。

列の一部がコピーされる場合、テーブルは部分的に更新されます。文：

CREATE TABLE t0 (
    id INT NOT NULL,
    name TEXT,
    age INT,
    PRIMARY KEY (id)
);

COPY t0 (id,
    name)
FROM
    STDINWITH (stream_mode TRUE, on_conflict UPDATE);

-- COPY 文は、次の INSERT INTO 文と同じです。
INSERT INTOINSERT INTO t0 (id, name)
    VALUES (?, ?)
ON CONFLICT (id)
    DO UPDATE SET id = excluded.id, name = excluded.name;

列の一部のみがコピーされ、コピーされない列にデフォルト値が構成されている場合、次の文が使用されます。

CREATE TABLE t0 (
    id INT NOT NULL,
    name TEXT,
    age INT DEFAULT 0,
    PRIMARY KEY (id)
);

COPY t0 (id,
    name)
FROM
    STDINWITH (stream_mode TRUE, on_conflict UPDATE);

-- COPY 文は、次の INSERT INTO 文と同じです。
-- データ行の id 列にデータが含まれていない場合、その行の age 列にはデフォルト値が割り当てられます。
-- データ行の id 列にデータがある場合、その行の age 列は更新されません。
INSERT INTO t0 (id, name, age)
    VALUES (?, ?, DEFAULT)
ON CONFLICT (id)
    DO UPDATE SET id = excluded.id, name = excluded.name;

サポートされている SQL 式 (ベータ)

Hologres V3.2 以降のバージョンでは SQL 式がサポートされています。式の詳細については、PostgreSQL のドキュメントの「SQL expressions」をご参照ください。式は以下でサポートされています。

INSERT:
- VALUES
- ON CONFLICT DO UPDATE
- ON CONFLICT DO WHERE の条件
- RETURNING
SELECT
SELECT リスト

制限事項

スカラー式とスカラー関数のみがサポートされています。集計関数、ウィンドウ関数、およびサブクエリはサポートされていません。
VALUES を除くすべての INSERT 式と関数は HQE をサポートしている必要があります。
SELECT 文の場合、定数引数を受け入れる IMMUTABLE な式と関数のみがサポートされます。

SQL 式を使用するには、hg_experimental_enable_fixed_plan_expression パラメーターを有効にします。

-- セッションレベルで有効にする
SET hg_experimental_enable_fixed_plan_expression = on;

-- データベースレベルで有効にする
ALTER DATABASE <db_name> SET hg_experimental_enable_fixed_plan_expression = on;

例

INSERT で式を使用する

-- テーブルを作成する
CREATE TABLE test_t (
    id INT PRIMARY KEY,
    col INT,
    ts TIMESTAMP
)
WITH (
    orientation = 'row',
    distribution_key = 'id'
);

-- GUC パラメーターを有効にする
SET hg_experimental_enable_fixed_plan_expression = ON;

-- VALUES
INSERT INTO test_t VALUES (1, 1, now());

-- ON CONFLICT DO UPDATE
INSERT INTO test_t AS old 
    VALUES (1, 1, now())
    ON CONFLICT (id) 
    DO UPDATE SET col = excluded.col + old.col, ts = excluded.ts;

-- ON CONFLICT DO WHERE 条件
INSERT INTO test_t AS old
    VALUES (1, 1, now())
    ON CONFLICT (id)
    DO UPDATE SET col = excluded.col + old.col, ts = excluded.ts
    WHERE excluded.ts > old.ts;

-- RETURNING
INSERT INTO test_t AS old
    VALUES (1, 1, now())
    ON CONFLICT (id)
    DO UPDATE SET col = excluded.col + old.col, ts = excluded.ts
    WHERE excluded.ts > old.ts
    RETURNING 2 * col, ts;

SELECT リストで式を使用する

プライマリキーに基づいてポイントクエリを実行します。

-- テーブルを作成する
CREATE TABLE test_t (
    id int PRIMARY KEY,
    ts TIMESTAMP NOT NULL,
    col JSONB
)
WITH (
    orientation = 'row',
    distribution_key = 'id'
);

-- SELECT リストで式を指定します。JSONB 演算子がサポートされています。
SELECT
    (col ->> 'b')::int + (col ->> 'a')::int,
    date_trunc('day', ts)
FROM
    test_t
WHERE
    id = 1;

PrefixScan クエリを実行する

-- テーブルを作成する
CREATE TABLE test_t (
    id INT,
    ts TIMESTAMP NOT NULL,
    col JSONB,
    PRIMARY KEY (id, ts)
)
WITH (
    orientation = 'row',
    distribution_key = 'id'
);

-- GUC パラメーターを有効にする
SET hg_experimental_enable_fixed_dispatcher_for_scan = TRUE;

-- SELECT リストで式を指定する
SELECT
    (col ->> 'b')::int + (col ->> 'a')::int,
    date_trunc('day', ts)
FROM
    test_t
WHERE
    id = 1;

固定プランをサポートするには、関数と式は IMMUTABLE であり、定数引数を受け入れる必要があります。

-- テーブルを作成する
CREATE TABLE test_t (
    id INT PRIMARY KEY,
    ts TIMESTAMP NOT NULL,
    col JSONB
)
WITH (
    orientation = 'row',
    distribution_key = 'id'
);

-- random() はイミュータブルな関数ではないため、固定プランではサポートされていません
SELECT
    id + random()
FROM
    test_t
WHERE
    id = 1;

-- toString() 関数は定数引数を受け入れないため、固定プランではサポートされていません。
SELECT
    toString (id)
FROM
    test_t
WHERE
    id = 1;

固定プランが使用されていることを確認する

Hologres コンソールでは、固定プランを使用して実行された更新文は、[リアルタイムインポート (RPS)] セクションの [監視情報] ページに、SDK を使用して実行された INSERT、UPDATE、および DELETE 操作として表示されます。データ更新効率を向上させるために、固定プランを使用して INSERT、UPDATE、および DELETE 文を実行することをお勧めします。
EXPLAIN 文を実行して SQL 実行計画を表示し、固定プランが使用されていることを確認できます。返された実行計画に FixedXXXNode が含まれている場合、次の図に示すように、SQL 文を処理するために固定プランがトリガーされます。FixedXXXNode が実行計画で返されない場合は、前のセクションで説明した要件が満たされているかどうかを確認してください。

パフォーマンスを最適化する

固定プランが使用される特定のシナリオでは、次のいずれかの方法を使用してパフォーマンスを最適化できます。

Hologres V1.1.49 以降では、固定プランを使用して実行されるポイントクエリのパフォーマンスが最適化されています。大量のデータを含むポイントクエリでは、スループットが 30% 以上向上します。ビジネス要件に基づいて、インスタンスを V1.1.49 以降に更新してください。
一度に実行する SQL 文の数を 512 の倍数に設定します。実際には、一度に実行する SQL 文の数を 512 の倍数に設定すると、パフォーマンスが最適になることが証明されています。Holo Client では、SQL 文の数は自動的に 512 の倍数に設定されます。

FAQ

質問 1: 接続でエラーメッセージ role/database does not exist. が報告された場合はどうすればよいですか?
- 原因：ユーザーアカウントまたはデータベースが存在しません。
- 解決策：接続情報を確認し、ユーザー名またはデータベース名が有効であることを確認してください。
  Hologres コンソールにログインし、目的のインスタンスを見つけ、[操作] 列の [管理] をクリックします。[インスタンスの詳細] ページの左側のナビゲーションウィンドウで [アカウント管理] をクリックします。そして、[ユーザー管理] ページでユーザー名、[データベース認証] ページでデータベース名を取得できます。
質問 2: データ書き込み中にエラーメッセージ the requested table name: xxx (id: xx, version: xx) mismatches the version of the table (id: xx, version: xx) from server が報告された場合はどうすればよいですか?
- 原因：データ書き込み中に列の追加などの操作により、テーブルメタデータが変更されます。その結果、テーブルバージョンが変更されます。
- 解決策：接続を再確立します。固定プランでは、新しいテーブルメタデータが取得され、データが書き込まれます。