====== Writing to the database ======

This tutorial explains basic write and update access to the polymake database. See [[poly_db_tutorial|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 ''[[https://polymake.org/release_docs/latest/common.html#common__db_insert__320|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
<code>
   db_insert(<object>, db=>"DBName", collection=>"ColName");
</code>
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 [[user_guide:howto:poly_db_write#type_information|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 [[dev_corner:polydb_format#Type Information|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:
<code>
 $t = db_get_type_information(db=>"LatticePolytopes", collection=>"SmoothReflexive", type_information_key=>'fano');
</code>

=== 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 [[dev_corner:polydb_format#Type Information|here]] for the precise format).

New type information entries are written with the command ''db_set_type_information''. The basic command is
<code>
   db_set_type_information(db=>"DBName",collection=>"ColName",type_information=>$t)
   db_set_type_information(db=>"DBName",collection=>"ColName",file=><filename>)
</code>
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''.


=== Inserting an object with type informaion ===

''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.

==== Inserting or Updating Documentation ====

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
<code>
db_write_db_info(file=>"db.json");
db_write_collection_info(file=>"collection.json");
</code>
where we read the information from the files ''db.json'' and ''collection.json'' in json format. For the format see [[dev_corner:polydb_format#Documentation entries in the database|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''.

==== Remove an entry from a collection ====

You need the ''id'' of an object in a collection to remove it from this collection. The basic form of the command is
<code>
  db_remove($id, db=>"DBName", collection=>"ColName");
</code>


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