Main Content

ormread

Read mappable objects from database

Since R2023b

    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.

    example

    obj = ormread(conn,ormClass,Name=Value) specifies one or more name-value arguments. For example, set Depth=1 to read in the ForeignKey or LinkTable properties from a class.

    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

    collapse all

    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 = receiveProduct(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

    collapse all

    Database connection, specified as a scalar database.relational.connection 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.

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

    Name-Value Arguments

    Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

    Example: obj = ormread(conn,ormClass,Depth=1)

    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)

    Class depth, specified as a nonnegative scalar integer. Use Depth to choose a subset of the ForeignKey or LinkTable property in the class hierarchy to read before stopping. By default, ormread reads all properties in the hierarchy including nested ones. For example, you can set

    • Depth=0 to read in information about the input class without reading any ForeignKey or LinkTable properties.

    • Depth=1 to read in ForeignKey or LinkTable properties of the input class, while ignoring any nested ForeignKey or LinkTable properties.

    • Depth=2 to read in ForeignKey or LinkTable properties of the input class and one level of nested ForeignKey or LinkTable properties.

    Example: obj = ormread(conn,ormClass,Depth=1)

    Version History

    Introduced in R2023b

    expand all