MmParameter#

class MmParameter#

Bases: handle

MmParameter manages persistent toolbox parameters/settings using a local SQLite database.

Provides schema definition, validation, and automatic migration via a metadata table and a schema hash. Supports default entries, typed columns, and conversion between MATLAB types and SQLite storage formats.

Key features:

Metadata table for multi-table schema tracking
Schema hashing for change detection
PRAGMA table_info for schema introspection

Example:

s = YourParameterSubclass();
s.checkTable(); % ensure schema exists and is current
t = s.readTable();

Notes:

The database file is placed under getHome()/Documents/MMUser/config and is named according to DataBaseName.
String and matrix-typed columns are serialized to TEXT and converted back on read.

Constructor Summary

MmParameter()#

Construct an instance of MmParameter.

Subclasses should define their schema in the constructor by setting TableColumn, DefaultValue, and optionally DefaultEntry.

Property Summary

ColumnNameAll string#: Including the ID column

ColumnTypeAll string#: Including the ID column’s type

DataBaseName = "mmParameter.db"#: Database file name. Saved under MMUser/config

DataTypeMapping = dictionary(["int64","double","logical","string","doubleMatrix","logicalMatrix","stringMatrix","struct","table"], ... ["INTEGER","REAL","INTEGER","TEXT","TEXT","TEXT","TEXT","TEXT","TEXT"])#: Map MATLAB types to database types

DefaultEntry table#: Default entries for initial setup

DefaultValue dictionary = dictionary("Name","Name")#: Stores column name and default value. Should be defined in subclass’s construtor. Using Null is not recommended.

ExtraColumnFromJoin string#

FirstColumn (1,1) string#: The default key string will be the name of the first column after ID

ForeignKey table#: ParentTable, KeyChild, KeyParent

IsFirstColumnUnique (1,1) logical = true#: Determine if we want ot make the first column unique or not

IsIncludeDefaultEntry (1,1) logical = false#: Determine if we want to automatically include the default entries into the table

IsSchemaCurrent (1,1) logical#: Check whether the stored schema hash matches the current schema.

IsTriggerJoinOnLeft (1,1) logical = false#: Determine if we want to trigger the join automatically when this table is updated or inserted

IsTriggerJoinOnRight (1,1) logical = false#: Determine if we want to trigger the join automatically when the join table is updated or inserted

JoinCondition table#: TableRight, KeyLeft,KeyRight,ColumnLeft,ColumnRight

MetadataTableName = "SchemaMetadata"#: Table to store schema information for all tables

SchemaHash (1,1) string#: Hash of current schema definition including default entries

TableColumn dictionary = dictionary("Name","string")#: Stores column name and type. Should be defined in subclass’s construtor

TableName (1,1) string#: Table name is consistent with the subclass name

UniqueConstraint string#

Method Summary

checkConstructor()#

Validate constructor-provided schema and defaults.

Ensures TableColumn types follow DataTypeMapping, DefaultEntry rows can be serialized by prepareInputTable(), and that DefaultValue includes all columns.

checkDataBase()#

Ensure the SQLite database file and metadata table exist.

Creates the database file in MMUser/config if missing and initializes the SchemaMetadata table for schema tracking.

checkTable()#

Ensure this parameter table exists and matches the current schema.

If the table does not exist, it is created. If the schema hash differs from the stored one, an automatic schema migration is performed.

connectDatabase()#

Open a read-write connection to the SQLite database file.

Returns:: SQLite connection handle
Return type:: sqlite

connectDatabaseRead()#

Open a read-only connection to the SQLite database file.

Returns:: SQLite read-only connection handle
Return type:: sqlite

convertOutputTable(t, IsHideId, IsConvert2Struct)#

Convert SQLite-stored values back to MATLAB types.

Converts matrix-encoded strings and logical columns to their corresponding MATLAB representations based on TableColumn.

Parameters:: t (table) – Table read from the database.
Returns:: Table with converted MATLAB types.
Return type:: table

createJoin()#

Create join-backed shadow columns and triggers based on JoinCondition.

For each entry in JoinCondition with key [JoinTable, JoinKey] and value of data columns to mirror, this will:

Add missing columns to this table
Populate them once from the join table
Create triggers to keep them updated on INSERT/UPDATE of either table, according to IsTriggerJoinOnJoinTable and IsTriggerJoinOnSelf.

Called from checkTable() after ensuring the base table exists.

createTable()#

Create the SQLite table according to the current schema definition.

Uses TableColumn and DataTypeMapping to generate the CREATE TABLE statement, writes default entries if provided, and updates schema metadata. Create the table with current schema

createView()#

Hook for subclasses to create auxiliary SQL views.

Default implementation is a no-op. Subclasses may override to create helper views that support richer queries (e.g., JSON expansion). Keep implementations idempotent by checking for view existence before creating.

deleteEntry(keyColumnValue, keyColumnName)#

Delete entries by key column and value(s).

Parameters:

keyColumnName (string) – Key column used for deletion
keyColumnValue (vector) – Key values to delete (vector)

duplicateEntry(keyColumnValue, firstColumnValue, keyColumnName)#

getLastID()#

prepareInputTable(t, isAllColumnsRequired, isIgnoreId)#

Validate and normalize input rows against the schema.

Ensures column names and MATLAB types match TableColumn regardless of the input column order. Partial inputs are allowed unless isAllColumnsRequired is true. Matrix-typed columns are serialized to TEXT: non-cell inputs are wrapped per row; cell inputs are validated and serialized. Supports empty [], missing/NaN/Inf in numeric matrices and empty strings in string matrices.

Parameters:: t (table or struct) – Input rows. Struct inputs are converted to table.
Returns:: Normalized table (column order and types aligned to schema) ready for SQL writes.
Return type:: table

prepareInputValue(updateColumnName, value, isScalar)#

readColumn(readColumnName)#

readEntry(keyColumnValue, keyColumnName, IsHideId)#

Read entries filtered by a key column and specific values.

Filtering is supported for base table columns.

Parameters:

keyColumnName (string) – Column to filter on.
keyColumnValue (vector) – Values to match in the key column.

Returns:

Matching rows with MATLAB-typed columns.

Return type:

table

readEntryTwoKey(keyColumnValue, keyColumnValue2, keyColumnName, keyColumnName2, IsHideId)#

Read entries filtered by a key column and values.

When a single column is requested, a vector is returned instead of a table.

Parameters:

keyColumnName (string) – Column to filter on
keyColumnValue (vector) – Key values to match (vector)

Returns:

Table of selected columns, or a vector when a single column is requested

Return type:

table or vector

readTable(IsHideId)#

Read the entire table and convert columns to MATLAB types.

Returns:: All rows in this parameter table.
Return type:: table

readValue(keyColumnValue, readColumnName, keyColumnName)#

Read one or more columns filtered by a key column and values.

When a single column is requested, a vector is returned instead of a table.

Attention: the output order is not guarenteed to match the keyColumnValue.

Parameters:

keyColumnName (string) – Column to filter on
keyColumnValue (vector) – Key values to match (vector)
readColumnName (string or string vector) – Column name(s) to return

Returns:

Table of selected columns, or a vector when a single column is requested

Return type:

table or vector

readValueTwoKey(keyColumnValue, keyColumnValue2, readColumnName, keyColumnName, keyColumnName2)#

Read one or more columns filtered by a key column and values.

When a single column is requested, a vector is returned instead of a table.

Parameters:

keyColumnName (string) – Column to filter on
keyColumnValue (vector) – Key values to match (vector)
readColumnName (string or string vector) – Column name(s) to return

Returns:

Table of selected columns, or a vector when a single column is requested

Return type:

table or vector

recreateTable()#

Recreate the table from scratch to remove extra columns or change types.

Backs up the current table, creates a new table with the target schema, copies compatible columns, and then drops the backup. Recreate table with current schema (for removing columns or changing types)

setProperty()#

throwError(me)#

updateColumn(updateColumnName, value)#

updateDefaultEntry()#

Insert default entries into the table if present.

Uses DefaultEntry and the first key in TableColumn to write initial rows. No action if DefaultEntry is empty. Insert default entries if provided and not empty

updateEntry(t, keyColumnName)#

Upsert rows using sqlupdate for matching keys and sqlwrite for new rows. It can handle multiple keyColumnName when these key columns are scalar columns.

Parameters:

t (table or struct) – Input rows to write (all schema columns, any order)
keyColumnName (string, optional) – Conflict key when ID is absent; default “ID”

updateMatrixElement(keyColumnValue, updateColumnName, value, index, keyColumnName)#

updateSchemaMetadata()#

Update or insert the current schema hash into the metadata table.

Records TableName, SchemaHash, and LastUpdated for change tracking. Insert or update schema metadata for this table Uses INSERT OR REPLACE to handle both new entries and updates

updateTable(t, isRequireAll)#

Overwrite the entire database table with validated content.

Drops and recreates the table according to the current schema, then upserts rows from t using DefaultKey, and finally inserts the configured default entries.

param t:

New table content that matches TableColumn names and types

type t:

table

Raises:

error
If input table names or types do not match the schema.

Overwrite the entire database table

updateTableSchema()#

Migrate the SQLite table to match the current schema.

Adds missing columns with default values when provided, and recreates the table if extra columns or type mismatches are detected. Updates metadata afterward. Update table schema to match current definition

updateValue(keyColumnValue, updateColumnName, value, keyColumnName)#

Update values in a specific column for selected key values.

Parameters:

keyColumnName (string) – Key column to match
keyColumnValue (vector) – Key values to update (vector)
updateColumnName (string) – Column to be updated
value (vector or cell) – New values (vector; for matrix columns use cell array)

writeEntry(t)#

Append entries to the table.

Parameters:: t (table or struct) – Rows to write. Struct inputs are converted to table.