Differences

This shows you the differences between two versions of the page.

--- tutorial:poly_db_querying [2017/07/26 15:48] – paffenholz
+++ tutorial:poly_db_querying [2018/02/10 11:38] (current) – deleted after merging into doku.php/tutorial/poly_db_tutorial oroehrig
@@ Line 1: / Line 1: @@
-==== Querying the Database ====
-There are three commands that can be used to query the database:
-   * ''db_query'': Obtain one or more objects that satisfy a query
-   * ''db_count'': Count objects that satisfy a query
-   * ''db_ids'': Obtain ''id''s of objects that satisfy a query
-If you expect a large number of results (which you can check with ''db_count''), then you should use a ''db_cursor'' instead, which retrieves the matching results one by one.
-=== Queries ===
-Queries are given as perl hashes. In its most basic form a query has the form
-   { "PROPERTY1" => <value1>, "PROPERTY2" => <value2>, ... }
-for example
-   { "DIM" => 3, "N_VERTICES" => 7 }
-Note that the database is pretty strict with types, so strings always need to be quoted, while integers should not be. The following would fail:
-   { "DIM" => "3" }
-The empty query is allowed:
-   {}
-returns all objects of a collection. You can query elements in an array with their index, e.g.
-   { "F_VECTOR.1" => 12 }
-gives polytopes with 12 edges (the entry at position one of the f-vector).
-You can query ranges with ''$lt'' (<), ''$lte'' (<=), ''$gt'', and ''$gte'' in the form
-   { DIM => { '$lt' => 4 } }
-to obtain polytopes of dimension less than 4. Observe the single quotation marks around ''$lt''. Those are necessary to prevent that perl attempts to interpret them as variables. You can bound from both sides with
-   { DIM => { '$gte' => 4, '$lte' => 10 } }
-to obtain those polytopes with dimensions between 4 and 10.
-''polymake'' just passes queries to MongoDB without processing them, so you can use the full query syntax of MongoDB, as explained [[https://docs.mongodb.com/manual/reference/operator/query/|here]].
-=== Obtain Objects that Satisfy a Query ===
-With ''db_query'' you can send a database query to the polyDB and obtain documents matching the query. The command has a single mandatory argument, the query. All other arguments are optional. However, some must have values for the command to succeed, but they can also be given as default values via custom variables. A simple query command is
-   { $a=db_query({'DIM' => 3}, db=>"LatticePolytopes", collection=>"SmoothReflexive"); }
-which returns all three dimensional smooth reflexive polytopes. The first argument (the query) can be any query as in the previous section.
-The name of the database and the collection can be stored in custom variables:
-   $PolyDB::default::db_name = "LatticePolytopes";
-   $PolyDB::default::collection_name = "SmoothReflexive";
-We assume this in the following. If you want to make this persistent over the next polymake sessions then add ''set_custom'' in front. Our above query shortens to
-   { $a=db_query({'DIM' => 3}); }
-If you just want to have one (random) object that satisfies your query, then you can add ''representative=>1'' to the options, i.e.
-   { $a=db_query({'DIM' => 3}, representative=>1); }
-If you want, for a given property, the set of values that can be attained for this property, then you can use the option ''distinct'', e.g.
-   { $a=db_query({'DIM' => 3}, distinct=>"N_VERTICES"); }
-returns an array that contains all values ''N_VERTICES'' can take for a 3-dimensional polytope.
-With the option ''limit=><number>'' you can limit the number of returned results to ''<number.''. With ''skip=><number>'' you can skip the first ''<number>'' results.
-With the option ''sort'' you can specify a sort order for your results. This argument takes an hash that is essentially in the same form as a query hash, except that all arguments are interpreted as booleans, so
-   skip => { "N_VERTICES" => 1 }
-sorts by the nuber of vertices.
-=== Count Objects that Satisfy a Query ===
-Using ''db_count'' instead of ''db_query'' returns the number of objects instead of the objects. It accepts the same arguments as ''db_query'', as far as they are sensible (so specifying a sort order does not work).
-=== Obtain Object ''ID''s that Satisfy a Query ===
-Using ''db_ids'' instead of ''db_query'' returns the ''id''s of objects instead of the objects. It accepts the same arguments as ''db_query'', as far as they are sensible.
-=== Obtain Objects using a Cursor ===
-This is done with ''db_cursor''.