Writing to the database

This tutorial explains basic write and update access to the polymake database. See here for an introduction tutorial on querying the database.

Note that you need write access to use the functions in this tutorial. For that, you usually need an account for our database. username and password are taken from the custom variables, but you can also pass them as options to all functions that modify the database:

• username : specify a different username for database acccess, e.g. if you write to restricted collections
• password : specify a different password for database acccess, e.g. if you write to restricted collections

Data can be inserted with the db_insert command. You can insert a single object, an array of objects, or a single object stored in a file. Usually it is advisable to apply a type information entry to your objects to ensure that they contain a coherent set of properties within a collection, but that is not necessary.

The basic command is

   db_insert(<object>, db=>"DBName", collection=>"ColName");

where <object> is either a polymake object, a file name, or an array of polymake objects. With this command, the object is inserted into the db DBName and collection ColName.

Every object in the collection has to have a unique id. The id defaults to the property name of the object; if an object with that id is already present in the collection you get an error.

Some useful options are:

• id : Sets the id of the object
• contributor : The contributor of the data
• noinsert : only simulate insertion of objects up to the point when the data would actually be written to the database (useful to check feasibility of computation of additional properties)

By default, all properties present in your object are copied in the database. For most of them it might not be interesting to filter by, so check out the section on type information to restrict the data that is actually searchable.

Collections in the database have corresponding type_information entries that specify a list of properties, and metadata about contributer, type of objects inside the collection, etc. (see here for a complete list of what metadata is stored). All objects in the database have a type_information key, and only the properties specified there will be searchable in the database. All other properties will only be available after actually retrieving the object from the database.

There can be more than one type information entry for a collection. This is useful if, for some part of a collection a property should or cannot be computed or stored in the database. E.g., storing all lattice points for the nine-dimensional Fano polytopes is not feasible.

You can get the type information entry of an existing collection with db_get_type_information. For example:

 $t = db_get_type_information(db=>"LatticePolytopes", collection=>"SmoothReflexive", type_information_key=>'fano');

To create a new type information entry, write it into a perl hash in the polymake shell, or into a JSON file (See here for the precise format).

New type information entries are written with the command db_set_type_information. The basic command is

   db_set_type_information(db=>"DBName",collection=>"ColName",type_information=>$t)
   db_set_type_information(db=>"DBName",collection=>"ColName",file=><filename>)

where in the first case $t should be a type information document as a perl hash, and in the second, <filename> should point to a json file. Obviously the two options are mutually exclusive. If a type information document for the same database and collection with the same key already exists, then it is updated. If you want to replace the document, then pass replace⇒1 with the command.

You can override id, key, and polyDB version given in the type information document by specifying the options key, id, or polyDB_version.

db_insert provides options to specify the type_informaiton key and computing of properties of the object you insert.

• use_type_information⇒1: uses a type information document with name default, if present. If you want to use a type information with a different key use the option type_information_key⇒<name> instead.
• type_information⇒<type information hash>: uses a type information given by a perl hash or JSON file.
• nonew: If set to true, polymake will not attempt to compute properties specified in the type information but not present in the object. Use this with care, as this makes the data inconsistent in a way not visible to other users (e.g. if only some objects contain a property a query involving this property will only return objects that actually have the property computed).
• keep_all_props : If true properties present in the object but not required by the type information will not be deleted.

Writing information documents for a database or a collection is done with the commands db_write_db_info and db_write_collection_info. Both can read the data either from a perl hash (with the option documentation) or a file (with the option file). The basic format is

db_write_db_info(file=>"db.json");
db_write_collection_info(file=>"collection.json");

where we read the information from the files db.json and collection.json in json format. For the format see here.

Existing entries are updated. With the option replace⇒1 you can replace an entry instead.

You can override id and polyDB version given in the information document by specifying the options id or polyDB_version.

You need the id of an object in a collection to remove it from this collection. The basic form of the command is

  db_remove($id, db=>"DBName", collection=>"ColName");

New databases and collections are created as soon as a first entry is written into them, so you can just use a db_insert to create a new database/collection. You should, however, remember to

• add a type_information first if you intend to write data using a type information template.
• add corresponding entry in the documentation database, otherwise your new database or collection is not listed with the db_info command