| Both sides previous revision Previous revision Next revision | Previous revision |
| user_guide:howto:polydb_tutorial [2020/09/01 13:47] – [Reading Data] paffenholz | user_guide:howto:polydb_tutorial [2021/06/19 21:33] (current) – correction of a typo schroeter |
|---|
| ====== Introduction to polyDB ====== | ====== Introduction to polyDB ====== |
| |
| This tutorial explains how to access the [[:polydb|polyDB database]] from within polymake using the extension ''polyDB''. It comes bundled with ''polymake'', so there is no need to install extra software, except for the MongoDB.pm perl package. (This tutorial is for polymake version 4 and later. The old version is [[poly_db_tutorial|here]], but this needs also an old version of the database). If you encounter any errors or problems concerning ''polyDB'' ro the extension, please don't hesitate to [[https://forum.polymake.org/|ask in the forum]]. | This tutorial explains how to access the [[:polydb|polyDB database]] from within polymake using the extension ''polyDB''. It comes bundled with ''polymake'', so there is no need to install extra software, except for the MongoDB.pm perl package. (This tutorial is for polymake version 4 and later. The old version is [[poly_db_tutorial|here]], but this needs also an old version of the database). If you encounter any errors or problems concerning ''polyDB'' or the extension, please don't hesitate to [[https://forum.polymake.org/|ask in the forum]]. |
| |
| The ''polymake'' extension is not necessary to use the data. You can access the data also | The ''polymake'' extension is not necessary to use the data. You can access the data also |
| "uri" : "https://polymake.org" | "uri" : "https://polymake.org" |
| }</code> | }</code> |
| * You need to provide a full json schema describing your data. If you have a polymake object with the data you want, then the function ''create_restrictive_schema'' can help you with this and provide an initial template. In ''polyDB'' the json schema is stored as the ''schema'' entry of a document also specifying the section and collection in the entries ''section'' and ''collection''. Here is part of the schema for 0/1-Polytopes.<code>{ | * You need to provide a full json schema describing your data. If you have a polymake object with the data you want, then the function ''create_restrictive_schema'' can help you with this and provide an initial template. Here is part of the schema for 0/1-Polytopes.<code>{ |
| "type": "object", | "type": "object", |
| "$schema": "http://json-schema.org/draft-07/schema#", | "$schema": "http://json-schema.org/draft-07/schema#", |
| } | } |
| } | } |
| }</code> | }</code>This schema needs one special property ''_polyDB'', which specifies some information on the document. Among the properties you should have<code>"_polyDB": { |
| | "required": [ |
| | "collection", |
| | "creation_date", |
| | "section", |
| | "uri", |
| | "version" |
| | ], |
| | "type": "object", |
| | "properties": { |
| | "uri": { |
| | "type": "string" |
| | }, |
| | "collection": { |
| | "type": "string" |
| | }, |
| | "version": { |
| | "type": "string", |
| | "pattern": "^[0-9]{1,2}.[0-9]{1,2}$" |
| | }, |
| | "creation_date": { |
| | "pattern": "^[1-9][0-9]{3}-[0-9]{2}-[0-9]{2}$", |
| | "type": "string" |
| | }, |
| | "section": { |
| | "type": "string" |
| | } |
| | } |
| | }</code> and should be a required property with an entry also in the properties listed in ''_attr'' as <code> |
| | "_attrs": { |
| | "additionalProperties": false, |
| | "properties": { |
| | "_polyDB": { |
| | "properties": { |
| | "attachment": { |
| | "const": true |
| | } |
| | } |
| | } |
| | }, |
| | "type": "object" |
| | }</code> |
| |
| * If you want you collection to be included in the ''db_info'' command you need a json document describing you collection in the form<code>{ | * If you want you collection to be included in the ''db_info'' command you need a json document describing you collection in the form<code>{ |
| ] | ] |
| }</code> | }</code> |
| * If you want to place this also in a new section, then also this (and all new subsections created) need a description document. | * If you want to place this also in a new section, then also this (and all new subsections created) need a description document. However, a description for a section can only be edited by an administrator, so just send us the description and we will add it. |
| |
| Meta information, schema and documentation are stored with the methods | Meta information, schema and documentation are stored with the methods |
| $collection->set_info($meta); | $collection->set_info($meta); |
| $collection->set_schema($schema); | $collection->set_schema($schema); |
| $collection->set_collection_doc(file=><file>); | $collection->set_collection_doc($doc, replace=>true/false, update=>true/false); |
| </code> | </code> |
| where in the first two functions the argument is either a perl hash or the name of a file containing a json document. | where the first argument is the data as a perl hash. |
| |
| Insertion is done with the method ''insert''. This function either takes a file, a single ''polymake'' big object or an array of such as first argument and writes this data into the collection specified by the options ''section'' and ''collection''. As for queries you can set these via custom variables and then don't need to specify them in ''db_insert''. Currently you need to specify ''use_schema => 1'' in the command to use the meta information and the json schema you provided. Further options are | Insertion of data is done with the method ''insert''. This function either takes a file, a single ''polymake'' big object or an array of such as first argument and writes this data into the collection specified by the options ''section'' and ''collection'' (these can also be specified with the same custom variables as for queries). This has some more options, see <code>help "insert";</code>in the polymake shell. |
| * ''type_information'': to specify a different json schema as a perl hash | |
| * ''replace'': to replace an existing document | |
| * ''noinsert'': For a dry run of the command. | |
| |
| |
| A new collection is started with the command<code>$polydb->initiate_collection(section=><section>, collection=><collection>);</code>If the collection should not be public, then also pas the option ''public=>false''. For a public collection the read access role of the new collection is added to the default role ''polymakeUser'' which is granted to every user of ''polyDB''. One can add this later if one wants to build up and test the collection befor making it publicly available. | A new collection is started with the command<code>$polydb->initiate_collection(section=><section>, collection=><collection>);</code>If the collection should not be public, then also pas the option ''public=>false''. For a public collection the read access role of the new collection is added to the default role ''polymakeUser'' which is granted to every user of ''polyDB''. One can add this later if one wants to build up and test the collection befor making it publicly available. |
| |
| If this creates new intermediate subsections you should set the section documentation with <code>$polydb->set_section_doc(file=><file>);</code> so that the new collection appears in the list printed by ''db_info'' for all users with sufficient permissions. | If this creates new intermediate subsections you should set the section documentation with <code>$polydb->set_section_doc($doc, section=>...);</code> so that the new collection appears in the list printed by ''db_info'' for all users with sufficient permissions. |
| |
| Note that the first command essentially only creates two new roles in MongoDB, one for read access to the collection (and all sections up to the root) and one for write access to the collection (and only to the collection, not to the sections). The actual collections are only created once the first document is written into the collection. This implies that collections will not be listed with ''db_info'' if any of the intermediate sections has no documentation, as then the collection where this is stored is not created. | Note that the first command essentially only creates two new roles in MongoDB, one for read access to the collection (and all sections up to the root) and one for write access to the collection (and only to the collection, not to the sections). The actual collections are only created once the first document is written into the collection. This implies that collections will not be listed with ''db_info'' if any of the intermediate sections has no documentation, as then the collection where this is stored is not created. |