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.

Write access

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

Inserting Data into a Collection

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.

Type information

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.

Retrieving type information

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'); Adding a new type information entry to your collection 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>)

Creating new Databases and Collections

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
• user_guide/howto/poly_db_write.txt