11.5.5 Append API

Machbase Append APIは複数行を連続して入力する大量入力APIです。JDBCではMachStatementの拡張メソッドを使用します。このページはLOG入力の例を中心に説明します。他のテーブルタイプのサポート範囲はSDKサポート表も確認してください。

API

メソッド	説明
`executeAppendOpen(tableName, errorCheckCount)`	Appendセッションを開始し、列メタデータを返します。
`executeAppendOpen(tableName, inputColumns, errorCheckCount)`	Machbase DBMS 8.7.0で選択列またはARRAY要素を対象にAppendセッションを開始します。
`executeAppendData(metadata, data)`	1行を送信します。
`executeAppendDataByTime(metadata, time, data)`	ナノ秒の時刻を指定して1行を送信します。
`executeAppendFlush()`	保留中の応答を同期します。
`executeAppendClose()`	Appendセッションを終了します。
`executeSetAppendErrorCallback(callback)`	行エラーのコールバックを登録します。
`getAppendSuccessCount()`	成功した行数を返します。
`getAppendFailureCount()`	失敗した行数を返します。

公開メソッドexecuteAppendData()は成功すると1を返し、無効な内部結果にはSQLExceptionをスローします。最終的な成功・失敗件数とコールバックも確認します。

入力例

CREATE LOG TABLE sensor_data (
    time DATETIME,
    name VARCHAR(40),
    value DOUBLE
);

import com.machbase.jdbc.MachStatement;
import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.util.ArrayList;

try (MachStatement statement =
         (MachStatement) connection.createStatement()) {
    ResultSet appendResult =
        statement.executeAppendOpen("sensor_data", 100);
    ResultSetMetaData metadata = appendResult.getMetaData();

    statement.executeSetAppendErrorCallback(
        (errorNumber, errorMessage, rowMessage) ->
            System.err.printf(
                "Append error [%05d]: %s%n%s%n",
                errorNumber, errorMessage, rowMessage));

    long baseTime = System.currentTimeMillis() * 1_000_000L;

    for (int index = 0; index < 10_000; index++) {
        ArrayList<Object> row = new ArrayList<>();
        row.add(baseTime + index);
        row.add("sensor-" + (index % 10));
        row.add(20.0 + index * 0.001);

        int result = statement.executeAppendData(metadata, row);
        if (result != 1 && result != 2) {
            throw new SQLException(
                "Append failed at row " + index);
        }
    }

    statement.executeAppendFlush();
    statement.executeAppendClose();
    appendResult.close();

    System.out.printf("success=%d failure=%d%n",
        statement.getAppendSuccessCount(),
        statement.getAppendFailureCount());
}

ARRAYと選択列

スパースARRAY入力に列選択は必須ではありません。通常の executeAppendOpen(tableName, errorCheckCount)で開き、返されたメタデータに合わせて MachSparseArrayを行のARRAY値として渡します。

ResultSet opened = statement.executeAppendOpen("ARRAY_APPEND_FULL_EXAMPLE", 0);

接続・入力・Close・検索を含む通常Openの例を先に確認してください。IDとARRAY列を宣言順で渡し、自動の_arrival_timeは行に追加しません。

Machbase DBMS 8.7.0では、executeAppendOpen()のオーバーロードに列名や ARRAY_COLUMN[position]を渡せます。

ResultSet appendResult = statement.executeAppendOpen(
    "sensor_array",
    new String[] {"ID", "CHANNELS[0]", "CHANNELS[3]"},
    0);

行ごとに異なるARRAY位置を入力する場合は、MachConnection.createSparseArrayOf()で MachSparseArrayを作成します。mapキーは0から始まり、空のmapは全要素がNULLのARRAYです。 Javaのnullは配列全体のNULLです。

Map<Integer, Object> entries = new HashMap<Integer, Object>();
entries.put(Integer.valueOf(1), Integer.valueOf(200));
entries.put(Integer.valueOf(3), Integer.valueOf(400));

MachSparseArray sparse = connection.createSparseArrayOf(
    "INT32", 4, entries);

密なARRAYの検索とprepared入力には、java.sql.Array、Connection.createArrayOf()、 PreparedStatement.setArray()を使用します。全体例と対象の衝突規則は Sparse ARRAYと選択列Append APIを参照してください。

SQLのARRAY要素対象とMachSparseArrayの位置は0始まりです。JDBC標準のパラメーター番号と java.sql.Array.getArray(index, count)のスライスインデックスは従来どおり1始まりのため、混同しないでください。

DATETIME

AppendのDATETIME値はエポックナノ秒単位のlongで渡します。

long epochNanoseconds =
    System.currentTimeMillis() * 1_000_000L;

executeAppendDataByTime()は別の時刻値を受け取るテーブル入力経路で使用します。入力列の順序とJavaの型は、executeAppendOpen()が返したResultSetMetaDataに合わせます。

フラッシュとクローズ

executeAppendOpen()でセッションを開始します。
executeAppendData()を繰り返し呼び出します。
途中の確認が必要な場合はexecuteAppendFlush()を呼び出します。
全入力を送った後、executeAppendClose()を呼び出します。
成功・失敗件数とコールバックの結果を確認します。

例外時にもAppendセッションとStatementが閉じるよう、try-with-resourcesとfinallyを使用します。コールバックでは失敗行を別途保存またはログ記録し、無条件の再試行で重複入力を作らないよう業務キーを使用します。

サイズと使用範囲

ordered appendはプロトコルのパケット上限を共有するため、1行全体のエンコード後サイズを64KiB未満に保ちます。BLOB/CLOBなど大きな値を入力する場合は、行サイズとクライアントのメモリ使用量を合わせて確認します。

TRANSACTIONテーブルのAppendバッチはSQLトランザクションに含まれず、独立して反映されます。ロールバックが必要な複数のDMLにはJDBCトランザクションを使用します。

最終更新日 9月 10, 2026

11.5.4 DatabaseMetaData 11.5.6 移行とトラブルシューティング