Overview of the PersistentTable package
List of PersistentTable Package Commands
The PersistentTable package provides a connection object that behaves somewhat like a table, except it is (by default) backed by a file containing an SQLite table. As a consequence, any information stored in the table persists when Maple is shut down or restarted. Furthermore, there is some extra functionality for searching through the stored information.
The interface is deliberately kept simple; it does not come close to giving access to all of SQLite's functionality. If you need more functionality, you can use the package Database:-SQLite. However, the PersistentTable package is easier to use for programmers who have experience with Maple, but not much experience with SQL. Conversely, if you don't need persistent storage or the extra searching functionality provided by this package, you are probably better off using a plain table.
The commands in the PersistentTable package are:
A PersistentTable object has a fixed number of columns with associated types, say k. The first column, or the first n columns for some positive integer n <= k, are taken to make up the primary key of the object. This means that when viewed as a key/value store, the object's keys are all expression sequences of n Maple expressions, and the values are expression sequences of n - k Maple expressions.
Storing values in columns with data type anything converts them to the so-called "dot m" format, as generated by the %m specifier for the sprintf command and as described in the Format,m help page. Retrieving them translates them back to Maple. If your value will not survive such a process (for example, if it involves locals from modules), use of persistent tables will lead to unexpected results.
If float columns are used, be aware that the float operations done inside SQLite, and conversion to SQLite and back, do not necessarily comply with the rules with respect to precision that hold in Maple. Similarly, any constraints involving equality of expressions involving floating-point computation should be viewed with suspicion.
Internally, if there are multiple connection objects for the same file at one time in a single Maple session (presumably, though not necessarily, with a different prefix), and the file is specified in the same way for all invocations of Open (in particular, the string is the same after being run through FileTools:-AbsolutePath), only a single connection object is created through SQLite:-Open. It is required that either all of these connections are read-only, or none of them are. (Connections to different files can, of course, have different read-only status.) Referring to the same file through different paths is not advised. SQLite enforces certain restrictions as to opening the same file in different concurrent Maple sessions; this is, therefore, also not advised.
This is the only thread safety issue - persistent tables are thread safe as of Maple 2021 otherwise.
For more information on thread safety, see index/threadsafe.
Generate three file names that we can overwrite.
path1 ≔ FileTools:-JoinPath⁡FileTools:-TemporaryDirectory⁡,foo.mks
path2 ≔ FileTools:-JoinPath⁡FileTools:-TemporaryDirectory⁡,bar.mks
path3 ≔ FileTools:-JoinPath⁡FileTools:-TemporaryDirectory⁡,baz.mks
Make sure these files do not currently exist.
Create the first persistent table: entries are indexed by two integers and the value is an arbitrary Maple expression.
store1 ≔ Open⁡path1,style=k1::integer,k2::integer,v::anything,primarykey=2
store1≔<< 3-column persistent table at /tmp/mpldoc4/foo.mks >>
The expression that is the value can be, for example, a list.
One can access this value using the Get command or indexing.
The Has and Count commands give us information about the existence of entries.
store13,6 ≔ x,y
We can use the RawCommand command to manage transactions.
store13,2 ≔ 6
The Get command generates an error if you try to access an entry that does not exist. Indexing is the same. The MaybeGet command instead returns a default value that you specify.
store2 ≔ Open⁡path2,style=k1::integer,k2::integer,v::anything,b::boolean,primarykey=2
store2≔<< 4-column persistent table at /tmp/mpldoc4/bar.mks >>
Error, (in PersistentTable:-Get) bad index into PersistentTable
Error, bad index into PersistentTable
The GetAll command returns all rows satisfying some criterion. The GetKeys command returns information from the same rows, but returns only the primary key columns.
store21,4 ≔ 5,true
You can't open two connections to the same file with different readonly settings, even if they have different prefixes:
store3 ≔ Open⁡path3,style=k::anything,v::anything
store3≔<< 2-column persistent table at /tmp/mpldoc4/baz.mks >>
store4 ≔ Open⁡path3,'prefix'=duck,style=k1::integer,k2::integer,v1::anything,v2::integer,v3::anything,primarykey=2,'index'⁡v2,'readonly'=true
Error, (in PersistentTable:-Open) tried to connect to /tmp/mpldoc4/baz.mks, which is already open with a different read-only status
store4 ≔ Open⁡path3,'prefix'=duck,style=k1::integer,k2::integer,v1::anything,v2::integer,v3::anything,primarykey=2,'index'⁡v2
store4≔<< 5-column persistent table at /tmp/mpldoc4/baz.mks with prefix duck_ >>
store5 ≔ Open⁡path3,'prefix'=drijfsijs,style=k1::integer,v1::float,v2::float
store5≔<< 3-column persistent table at /tmp/mpldoc4/baz.mks with prefix drijfsijs_ >>
store31+x ≔ y
store33,4 ≔ y
store43,4 ≔ duck,2,bill
store42,4 ≔ goose,3,egg
Because the key and value are arbitrary Maple expressions, you cannot use inequalities when calling GetAll on store3: the comparison needs to be carried out inside the database engine, and it does not understand Maple expressions.
Error, (in PersistentTable:-GetAll) invalid condition (k < 5): column k is of type anything, so it does not support inequalities
However, store4 supports arbitrary polynomial conditions involving its integer columns:
The files should still be present.
store1 ≔ Open⁡path1
store2 ≔ Open⁡path2,readonly
store21,4 ≔ 6
Error, attempt to write a readonly database
store3 ≔ Open⁡path3
store4 ≔ Open⁡path3,'prefix'=duck
The PersistentTable package was introduced in Maple 2021.
For more information on Maple 2021 changes, see Updates in Maple 2021.
Download Help Document