ormread

Read mappable objects from database

Since R2023b

Syntax

obj = ormread(conn,ormClass)

obj = ormread(conn,ormClass,RowFilter=rf)

obj = ormread(conn,ormObject)

Description

obj = ormread(conn,ormClass) reads one or more mappable objects from a database connection of a given class and returns a vector of mappable objects. For more information on mappable objects, see database.orm.mixin.Mappable.

obj = ormread(conn,ormClass,RowFilter=rf) specifies a subset of objects to read from the database.

obj = ormread(conn,ormObject) returns an array of objects containing the most recent property values from the database, where ormObject specifies a vector of objects to refresh.

Examples

Read Mappable Object from Database

This example depends on the Product class that maps to a database table. This class contains several properties that map to the database, as well as some methods that alter those properties.

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(ColumnName = "Manufacturer")
        Supplier string
    end

    properties(ColumnType = "date")
        InventoryDate datetime
    end

    methods
        function obj = Product(id,name,description,supplier,cost,quantity,inventoryDate)
            if nargin ~= 0
                inputElements = numel(id);
                if numel(name) ~= inputElements || ...
                        numel(description) ~= inputElements || ...
                        numel(supplier) ~= inputElements || ...
                        numel(cost) ~= inputElements || ...
                        numel(quantity) ~= inputElements || ...
                        numel(inventoryDate) ~= inputElements
                    error('All inputs must have the same number of elements')
                end
    
                % Preallocate by creating the last object first
                obj(inputElements).ID = id(inputElements);
                obj(inputElements).Name = name(inputElements);
                obj(inputElements).Description = description(inputElements);
                obj(inputElements).Supplier = supplier(inputElements);
                obj(inputElements).CostPerItem = cost(inputElements);
                obj(inputElements).Quantity = quantity(inputElements);
                obj(inputElements).InventoryDate = inventoryDate(inputElements);

                for n = 1:inputElements-1
                    % Fill in the rest of the objects
                    obj(n).ID = id(n);
                    obj(n).Name = name(n);
                    obj(n).Description = description(n);
                    obj(n).Supplier = supplier(n);
                    obj(n).CostPerItem = cost(n);
                    obj(n).Quantity = quantity(n);
                    obj(n).InventoryDate = inventoryDate(n);
                end
            end
        end
        function obj = adjustPrice(obj,amount)
            arguments
                obj (1,1) Product
                amount (1,1) {mustBeNumeric}
            end
           obj.CostPerItem = obj.CostPerItem + amount; 
        end

        function obj = shipProduct(obj,amount)
            arguments
                obj (1,1) Product
                amount (1,1) {mustBePositive,mustBeInteger}
            end

            obj.Quantity = obj.Quantity - amount;
        end

        function obj = recieveProduct(obj,amount)
            arguments
                obj (1,1) Product
                amount (1,1) {mustBePositive,mustBeInteger}
            end

            obj.Quantity = obj.Quantity + amount;
            obj.InventoryDate = datetime('today');
        end

    end

end

First, create an sqlite database file that does not require a connection to a live database.

filename = "orm_demo.db";
if exist(filename,"file")
    conn = sqlite(filename);
else
    conn = sqlite(filename,"create");
end

% Remove it to maintain consistency
execute(conn,"DROP TABLE IF EXISTS products");

Use the orm2sql function to display the database column information based on the class defined in Product.m.

orm2sql(conn,"Product")

ans = 
    "CREATE TABLE products
     (ProductNumber double, 
     Name text, 
     Description text, 
     Quantity double, 
     UnitCost double, 
     Manufacturer text, 
     InventoryDate date, 
     PRIMARY KEY (ProductNumber))"

Create a Product object to create and populate a table.

toy = Product(1,"Toy1","Descr1","CompanyA",24.99,0,datetime(2023,1,1))

toy = 
  Product with properties:

               ID: 1
             Name: "Toy1"
      Description: "Descr1"
         Quantity: 0
      CostPerItem: 24.9900
         Supplier: "CompanyA"
    InventoryDate: 01-Jan-2023

Use the ormwrite function to populate the database with the data from toy.

ormwrite(conn,toy);

Use the ormread method to read data from the database. This method uses the mapping to determine which tables to read, and also determines how the column values correspond to the properties.

clear toy 
ormread(conn,"Product")

ans = 
  Product with properties:

               ID: 1
             Name: "Toy1"
      Description: "Descr1"
         Quantity: 0
      CostPerItem: 24.9900
         Supplier: "CompanyA"
    InventoryDate: 01-Jan-2023

clear ans
close(conn)

Input Arguments

conn — Database connection

scalar database.relational.connection object

Database connection, specified as a scalar database.relational.connection object.

ormClass — Class identity

character vector | string scalar | scalar matlab.metadata.Class object

Class identity, specified as a character vector, string scalar, or scalar matlab.metadata.Class object containing the class name to read from the database. Use matlab.metadata.Class to resolve class name conflicts such as two classes with the same name in different packages.

rf — Row filter condition

scalar | vector

Row filter condition, specified as a scalar or vector of matlab.io.RowFilter objects returned from the rowfilter function.

Example: rf = rowfilter("productnumber"); rf = rf.productnumber <= 5; ormread(conn,tablename,RowFilter=rf)

ormObject — Mappable object

vector

Mappable object to refresh, specified as a vector. For more information on mappable objects, see database.orm.mixin.Mappable.

Version History

Introduced in R2023b