matlab-map-database-objects

MATLAB オブジェクトリレーショナルマッパー

Database Toolbox のオブジェクトリレーショナルマッピング（ORM）レイヤーを使用して、MATLAB クラスをリレーショナルデータベースのテーブルにマッピングする場合に使用します。プロパティと列のマッピングを定義する Mappable クラスを作成し、オブジェクトに対する CRUD 操作には ormread、ormwrite、ormupdate を使用します。R2023b 以降で利用できます。

このスキルを使用する場面

• MATLAB クラスをデータベースのテーブルにマッピングする
• データベースの行を MATLAB オブジェクトとして読み取る
• MATLAB オブジェクトをデータベースのテーブルに書き込む
• 変更したオブジェクトからデータベースの行を更新する
• クラス定義から SQL の CREATE TABLE 文を生成する
• オブジェクト指向のデータベースワークフロー
• ユーザーが次のキーワードに言及した場合：ORM、オブジェクトリレーショナルマッピング、Mappable、ormread、ormwrite、ormupdate、orm2sql、クラスマッピング、プロパティマッピング、オブジェクトデータベース

使用しない場面

• アドホッククエリやデータ探索 — 代わりに RowFilter を指定して sqlread／fetch を使用します
• 数千行の一括インポート／エクスポート — 一括操作では ORM は sqlwrite／sqlread よりも低速です
• MongoDB、Cassandra、Neo4j — ORM はリレーショナルデータベース（JDBC、ODBC、ネイティブの MySQL／PostgreSQL／SQLite）でのみ動作します
• R2023b より前の MATLAB リリース — ORM は利用できません

重要なルール

ORM の要件

• ORM 機能には必須のため、必ず database.orm.mixin.Mappable を継承します。
• ORM ではオブジェクトの識別に必須のため、必ず 1 つ以上の PrimaryKey プロパティを定義します。
• データベースのテーブル名を指定するには、必ず クラスレベルの属性 TableName を使用します。
• ORM による事前割り当てを可能にするため、nargin == 0 に対応するコンストラクターを必ず含めます。
• ORM には R2023b 以降が必要です。

対応する接続

• ORM が動作する接続：JDBC、ODBC、ネイティブの PostgreSQL、ネイティブの MySQL、ネイティブの SQLite、ネイティブの DuckDB。
• ORM が動作しない接続：MongoDB（mongoc）、Cassandra（apacheCassandra）、Neo4j。

選択の指針

シナリオ	ORM を使用	sqlread/sqlwrite を使用
オブジェクトの同一性とビジネスロジックが必要	はい	いいえ
クラスベースの型安全性が必要	はい	いいえ
読み取り／書き込み時にドメイン検証が必要	はい	いいえ
アドホッククエリやデータ探索	いいえ	はい
一括操作（数千行）	いいえ	はい（より高速）
オブジェクトマッピングが不要	いいえ	はい

主な概念

Mappable クラスの定義

Mappable クラスは MATLAB のプロパティをデータベースの列にマッピングします。

classdef (TableName = "employees") Employee < database.orm.mixin.Mappable

    properties (PrimaryKey, ColumnName = "EmployeeID")
        ID int32
    end

    properties
        Name string
        Department string
        Salary double
    end

    properties (ColumnName = "HireDate", ColumnType = "date")
        StartDate datetime
    end

    methods
        function obj = Employee(id, name, dept, salary, startDate)
            if nargin ~= 0
                obj.ID = id;
                obj.Name = name;
                obj.Department = dept;
                obj.Salary = salary;
                obj.StartDate = startDate;
            end
        end

        function obj = promote(obj, raise)
            obj.Salary = obj.Salary + raise;
        end
    end
end

プロパティ属性のリファレンス

属性	用途	例
PrimaryKey	プロパティを主キーとして指定します（必須）	properties (PrimaryKey)
ColumnName	プロパティを異なる名前の列にマッピングします	properties (ColumnName = "EmpID")
ColumnType	データベースの列の型を指定します	properties (ColumnType = "date")
TableName	対象テーブル名を指定するクラスレベルの属性です	classdef (TableName = "employees")

よくある間違い

% INCORRECT — class without PrimaryKey (ormwrite will error)
classdef (TableName = "employees") Employee < database.orm.mixin.Mappable
    properties
        Name string
        Dept string
    end
end
% ormwrite(conn, emp) → Error: No PrimaryKey defined

% CORRECT — PrimaryKey is required for ORM operations
classdef (TableName = "employees") Employee < database.orm.mixin.Mappable
    properties(PrimaryKey)
        EmployeeID int32
    end
    properties
        Name string
        Dept string
    end
end

% INCORRECT — class not inheriting Mappable
classdef Employee
    properties(PrimaryKey)
        EmployeeID int32
    end
end
% ormread(conn, "Employee") → Error! Not a Mappable class.

% CORRECT — must inherit from database.orm.mixin.Mappable
classdef Employee < database.orm.mixin.Mappable
    properties(PrimaryKey)
        EmployeeID int32
    end
end

% INCORRECT — constructor without nargin==0 guard
classdef (TableName = "emp") Employee < database.orm.mixin.Mappable
    methods
        function obj = Employee(id, name)
            obj.EmployeeID = id;
            obj.Name = name;
        end
    end
end
% ormread will fail because ORM needs to construct empty objects

% CORRECT — nargin==0 guard allows ORM to construct empty objects
classdef (TableName = "emp") Employee < database.orm.mixin.Mappable
    methods
        function obj = Employee(id, name)
            if nargin == 0
                return;
            end
            obj.EmployeeID = id;
            obj.Name = name;
        end
    end
end

ormwrite によるオブジェクトの書き込み

% Create and insert a single object
emp = Employee(1, "Alice", "Engineering", 95000, datetime(2023,3,15));
ormwrite(conn, emp);

% Create and insert an array of objects
emps = [Employee(2, "Bob", "Sales", 72000, datetime(2023,6,1)), ...
        Employee(3, "Carol", "Engineering", 105000, datetime(2022,1,10))];
ormwrite(conn, emps);

ormread によるオブジェクトの読み取り

% Read all objects
allEmployees = ormread(conn, "Employee");

% Read with a row filter
rf = rowfilter("Salary");
highEarners = ormread(conn, "Employee", RowFilter=rf.Salary > 90000);

% Refresh an existing object from database
emp = ormread(conn, emp);

ormupdate によるオブジェクトの更新

% Modify object in MATLAB
emp = promote(emp, 5000);

% Push changes to database
ormupdate(conn, emp);

レコードの削除

ORM には ormdelete 関数がありません。削除には execute を使用します。

execute(conn, "DELETE FROM employees WHERE EmployeeID = 42");

エラー処理

try
    ormwrite(conn, employeeObj);
catch ME
    if contains(ME.message, "UNIQUE") || contains(ME.message, "primary key")
        warning("Duplicate primary key. Use ormupdate instead.");
        ormupdate(conn, employeeObj);
    else
        rethrow(ME);
    end
end

クラス定義からの SQL 生成

% View the CREATE TABLE SQL that corresponds to the class
sql = orm2sql(conn, "Employee");
disp(sql);
% Output: "CREATE TABLE employees (EmployeeID integer, Name text, ...)"

完全な例

例 1：ORM の全ワークフロー — 定義、書き込み、読み取り、更新

手順 1：クラスを定義します（Product.m として保存）：

classdef (TableName = "products") Product < database.orm.mixin.Mappable

    properties (PrimaryKey, ColumnName = "ProductNumber")
        ID int32
    end

    properties
        Name string
        Description string
        Quantity int32
    end

    properties (ColumnName = "UnitCost")
        CostPerItem double
    end

    properties (ColumnType = "date")
        InventoryDate datetime
    end

    methods
        function obj = Product(id, name, desc, cost, qty, invDate)
            if nargin ~= 0
                obj.ID = id;
                obj.Name = name;
                obj.Description = desc;
                obj.CostPerItem = cost;
                obj.Quantity = qty;
                obj.InventoryDate = invDate;
            end
        end

        function obj = restock(obj, amount)
            obj.Quantity = obj.Quantity + amount;
            obj.InventoryDate = datetime("today");
        end
    end
end

手順 2：ORM 操作を使用します（ormWorkflow.m として保存）：

（上記で定義した Product クラスを使用します。）

% Connect to SQLite (no driver needed)
conn = sqlite("inventory.db", "create");

% Create and insert products
p1 = Product(1, "Widget", "Small widget", 9.99, 100, datetime(2024,1,1));
p2 = Product(2, "Gadget", "Large gadget", 29.99, 50, datetime(2024,1,1));
ormwrite(conn, [p1, p2]);

% Read all products back as objects
allProducts = ormread(conn, "Product");
disp(allProducts(1));

% Filter: find products under $15
rf = rowfilter("CostPerItem");
cheapProducts = ormread(conn, "Product", RowFilter=rf.CostPerItem < 15);

% Update: restock a product
cheapProducts(1) = restock(cheapProducts(1), 200);
ormupdate(conn, cheapProducts(1));

% Verify
refreshed = ormread(conn, cheapProducts(1));
disp(refreshed.Quantity); % Should be 300

close(conn);

ベストプラクティス

• 必ず、Mappable クラスはそれぞれ独立した .m ファイルで定義してください（MATLAB の要件により、1 ファイルにつき 1 クラス）。
• 必ず、nargin == 0 に対応するコンストラクターを含めてください（事前割り当てが可能になります）。
• PrimaryKey を指定するプロパティブロックは、必ず 1 つだけにしてください。
• MATLAB のプロパティ名がデータベースの列名と異なる場合は、ColumnName を使用してください。
• 明示的なマッピングが必要な型（例：datetime に対する "date"）には、ColumnType を使用してください。
• 必要なオブジェクトのみをインポートするには、RowFilter を指定して ormread を使用してください。フィルターはデータベースに渡されます。
• 書き込み前に、クラスのマッピングが想定するデータベーススキーマと一致していることを確認するには、orm2sql を使用してください。
• MATLAB でクラスメソッドを使用してオブジェクトを変更し、ormupdate で変更を反映してください。

よくあるパターン

パターン 1：定義・書き込み・読み込み・更新

% Define class → Product.m
p = Product(1, "Item", "Desc", 9.99, 10, datetime("today"));
ormwrite(conn, p);
p = ormread(conn, p);        % Refresh from DB
p = restock(p, 50);          % Modify in MATLAB
ormupdate(conn, p);          % Push to DB

パターン 2：業務ロジックを使用したフィルター付き読み込み

rf = rowfilter("Quantity");
lowStock = ormread(conn, "Product", RowFilter=rf.Quantity < 10);
for i = 1:numel(lowStock)
    lowStock(i) = restock(lowStock(i), 100);
    ormupdate(conn, lowStock(i));
end

パターン 3：スキーマの確認

sql = orm2sql(conn, "MyClass");
disp(sql); % Verify CREATE TABLE matches expectations

チェックリスト

最終確認の前に、次の項目を確認してください。

• Mappable クラスが database.orm.mixin.Mappable を継承している
• クラスの classdef に TableName 属性がある
• 少なくとも 1 つのプロパティブロックに PrimaryKey 属性がある
• コンストラクターが事前割り当て用に nargin == 0 に対応している
• クラスが独立した .m ファイルに保存されている
• 接続が確立され、確認されている（isopen(conn)）
• 接続の種類がサポートされている（JDBC、ODBC、MySQL／PostgreSQL／SQLite／DuckDB のネイティブ接続）
• R2023b 以降である（それ以前のリリースでは ORM を使用できません）

トラブルシューティング

問題：ormwrite が "class is not Mappable" というエラーで失敗する

• 解決策：クラスが database.orm.mixin.Mappable を継承していることを確認してください。クラス定義には < database.orm.mixin.Mappable を含める必要があります。

問題：ormread が空の配列を返す

• 解決策：sqlfind(conn, tableName) を使用して、テーブルがデータベースに存在することを確認してください。クラスの TableName 属性が実際のテーブル名と一致することも確認してください。

問題：ormupdate を実行してもデータベースの値が変わらない

• 解決策：ormupdate は主キーで行を照合します。オブジェクトの主キープロパティの値がデータベースに存在することを確認してください。ormread を使用して再読み込みし、確認してください。

問題：プロパティと列のマッピングが正しくない

• 解決策：orm2sql(conn, "ClassName") を使用して、生成された SQL を確認してください。ColumnName および ColumnType 属性がデータベーススキーマと一致していることを確認してください。

問題：ORM 関数が見つからない（"Undefined function"）

• 解決策：ORM を使用するには R2023b 以降が必要です。ver('database') でリリースを確認してください。それ以前のリリースでは、代わりに sqlread／sqlwrite を使用してください。

---

Copyright 2026 The MathWorks, Inc.

---