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 ids 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. See here for more information.

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

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.

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

Using db_ids instead of db_query returns the ids of objects instead of the objects. It accepts the same arguments as db_query, as far as they are sensible.

This is done with db_cursor. A PolyDB cursor accepts the same arguments as a normal db_query, i.e. you can specify database and collections, you can naroww the search with a query, and you can set limit and skip. The options representative and distinct don't work here. The request for a PolyDB cursor returns a pointer into the database, and each call to next retrieves another object. The advantage of this approach is that objects are obtained one after another, whenever you request a new one, instead of all objects at once. For large result sets, this saves memory locally and educes the time until you can start with computations.

Specifically, you obtain a database curser with

 $a=db_cursor({'DIM' => 3}, db=>"LatticePolytopes", collection=>"SmoothReflexive"); 

A cursor has four special methods:

• next: retrieves the next object from the database
• has_next: Checks if there are still objects that satisfy the query in the database that have not yet been retrieved.
• at_end: similar to has_next, returns true if no further object can be retrieved.
• count: tells you the number of results that match your query

Hence, a typical computation could be

 while( $a->has_next) {
     $p=$a->next;
     print $p->N_LATTICE_POINTS;
     

You can obtain information on the databases and collections in the database using the db_info command.

polytope> db_info();
DATABASE: LatticePolytopes
This database contains various classes of lattice polytopes.

Collection: SmoothReflexive
A complete collection of smooth reflexive lattice polytopes in dimensions up to 9, up to lattice equivalence. The lists were computed with the algorithm of 
Mikkel Oebro (see [[http://arxiv.org/abs/0704.0049|arxiv: 0704.0049]]) and are taken from the [[http://polymake.org/polytopes/paffenholz/www/fano.html|website 
of Andreas Paffenholz]].

In dimensions up to 7 the database contains the properties:
H_STAR_VECTOR, REFLEXIVE, DIM, LATTICE_CODEGREE, N_INTERIOR_LATTICE_POINTS, SMOOTH, N_LATTICE_POINTS, FACET_WIDTHS, VERTICES, FACETS, CENTROID, N_VERTICES, 
contributor, LATTICE_DEGREE, LATTICE_VOLUME, EHRHART_POLYNOMIAL_COEFF, N_BOUNDARY_LATTICE_POINTS, ESSENTIALLY_GENERIC, VERY_AMPLE, F_VECTOR, GORENSTEIN, 
FEASIBLE, LINEALITY_SPACE, AFFINE_HULL.

In dimension 8 the lattice points are not stored, and in dimension 9 also NORMAL is not computed

__________________

DATABASE: Manifolds
This database contains combinatorial manifolds

Collection: DIM2_3
This is a collection of  combinatorial 2-  and  3-manifolds with up to 10 vertices given as triangulations and calculcated by Frank Lutz found at: 
http://page.math.tu-berlin.de/~lutz/stellar/mixed.html

[...]

The command takes the options db to list only collections in a particular database, collection to list only one collection (in this case db must also be given), and username, if you have access to some collections not (yet) publicly available.

You can list all searchable entries of a collection with the command db_print_searchable_fields that takes the name of a database and a collection inside this database.

db_print_searchable_fields(db=>"LatticePolytopes",collection=>"SmoothReflexive");

Entries for smooth reflexive polytopes in dimensions 1 to 7
----------------------------
AFFINE_HULL  [dense, int]
CENTROID
CONE_AMBIENT_DIM  [int]
CONE_DIM  [int]
EHRHART_POLYNOMIAL_COEFF
FACETS  [dense, int]
FACET_WIDTHS  [int]
FULL_DIM  [int]
F_VECTOR  [int]
GORENSTEIN  [int]
H_STAR_VECTOR  [int]
[...]

Entries for smooth reflexive polytopes in dimension 8
----------------------------
AFFINE_HULL  [dense, int]
[...]

Entries for smooth reflexive polytopes in dimension 9
----------------------------
AFFINE_HULL  [dense, int]
[...]

There may be more than one list of searchable properties, e.g. if some properties cannot be stored or computed for some objects. Observe the header line of the list of properties to see which list applies to the objects you are looking for. The above lists apply to smooth reflexive polytopes in dimensions 1 to 7, in dimension 8 and in dimension 9. If a property appears in more than one list any search for this property will be executed on all objects that belong to one of the lists.

For most objects in the database there is a corresponding type information entry that specifies the properties present in the objects following this type information and some metadate information on the objects. Usually this is only interesting when inserting the objects into the database to ensure that all objects in a collection contain the same information (to allow comprehensive searches on the data). There can be more than one type information entry for a collection, e.g. if for some part of a collection should or cannot be computed or stored in the database (e.g. storing all lattice points for the nin-dimensional Fano polytopes is not feasible). To distinguish between these type information entries each entry in the database has a key specifying the type information used. In the objects retrieved from the database this is stored in the polyDB-attachment as the property key.

You can retrieve the type information entry with db_get_type_information. For example

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

For the format of such a typer information entry in the database see here.