tutorial:poly_db_querying

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
Last revisionBoth sides next revision
tutorial:poly_db_querying [2017/07/26 15:18] – paffenholztutorial:poly_db_querying [2017/08/09 09:46] – paffenholz
Line 5: Line 5:
    * ''db_count'': Count objects that satisfy a query    * ''db_count'': Count objects that satisfy a query
    * ''db_ids'': Obtain ''id''s of 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. See [[#Obtain Objects using a Cursor|here]] for more information. 
  
 === Queries === === Queries ===
Line 56: Line 58:
  
 === Count Objects that Satisfy a Query === === 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 === === 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''. 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;
 +       
 +=== Obtain Information about Searchable Fields in a Collection ===
 +
 +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. 
 +<code>
 +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]
 +[...]
 +</code>
  
 +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. 
 +       
 +=== Type Information ===
  
 +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 type information entry in the database see [[devel/polydb/format|here]].
 +