DOC: Queries

CHANGELOG.md

@@ -26,6 +26,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   a xml representation of entities.
 * After a SELECT statement now also all referenced files can be downloaded.
 * Automated documentation builds: `make doc`
+- documentation on queries
 
 ### Changed (for changes in existing functionality)
 

README_SETUP.md

@@ -22,6 +22,8 @@
 -->
 
 # Getting Started with the Web Interface 
+Here, we document how to install and build the CaosDB Web Interface. If you are
+only interested in how to use it, please continue [here](tutorials/first_steps.html)
 
 ## Folder Structure
 
@@ -48,8 +50,7 @@ All files in that directory will be sourced during `make install` and `make test
 Thus any customized configuration can also be added to that folder by just placing
 files in there which override the default values from `00_default.properties`.
 
-See `build.properties.d/00_default.properties` for more
-information.
+See `build.properties.d/00_default.properties` for more information.
 
 ## Setup
 

src/doc/index.rst

@@ -8,8 +8,8 @@ Welcome to the documentation of CaosDB's web UI!
    :hidden:
 
    Getting started <getting_started>
+   Tutorials <tutorials/index>
    Concepts <concepts>
-   tutorials/index
    API Index<genindex>
 
 

src/doc/tutorials/first_steps.rst

@@ -24,10 +24,64 @@ can also translate the examples to the data model that you have at hand.
 
 
 
+Main Menu (WIP)
+---------------
 
 
+.. note::  
+   By default only 10 Entities are shown on one page. You can get to
+   other pages with the “Next Page” and “Previous Page” buttons.
+
+:math:`\Rightarrow` What are the differences between the options of the
+“Entities” menu?
+
+Entities, Records, Properties…What?
+
+
+-  semantic data modeling
+
+-  entries in LinkAhead are like Objects
+
+-  RecordType: blue print for data
+
+-  Record: actual data
+
+
+See also the
+`wiki <https://gitlab.com/caosdb/caosdb/wikis/Concepts/Data%20Model>`__
+or the `paper <https://www.mdpi.com/2306-5729/4/2/83>`__
+
+|image|
+
+References in two directions
+
+-  | References in LinkAhead are directed:
+   | A Record A references another Record B
+
+-  The referencing Record A has a corresponding Property.
+
+-  The referenced Record B does not.
+
+-  In order to get referencing Records in the Web Interface, click on the following button
+    (or “Backref” on older systems).
+
+|image1|
+
+File System
+-----------
+
+-  Clicking on “File System” in the main menu allows you to browse files
+   that LinkAhead knows about.
+
+-  Typically, most files will be mounted from some file server.
+
+.. note::   You will not find any Records in this view (that are not Files).
+
 
 
 .. _here: https://gitlabio.something
 .. _`demo instance`: https://demo.indiscale.com
 .. _`IndiScale`: https://indiscale.com
+.. |image| image:: model.svg
+.. |image1| image:: References_button.png
+   :width: 4em

src/doc/tutorials/index.rst

@@ -10,4 +10,4 @@ This chapter contains tutorials.
    :hidden:
 
    first_steps
-
+   query

src/doc/tutorials/query.rst

+
+Querying CaosDB
+===============
+
+You should have the web interface of a CaosDB instance at hand. If you do not
+have one, you can visit https://demo.indiscale.com
+
+Introduction
+------------
+
+The semantic data model of CaosDB allows efficient data access. The
+CaosDB Query Language (CQL) is used to search data. Queries can be entered in
+the webinterface under the respective menu entry.
+
+Let's start with a simple one::
+
+    FIND RECORD MusicalInstrument
+
+Most queries simply start with the ``FIND`` keyword and describe what we are
+looking for behind that. The ``RECORD`` keyword denotes that we are only looking
+for Records (and not Files, Properties or RecordTypes). Finally, we provided
+a RecordType name: MusicalInstrument. This means that we will get all Records
+that have this RecordType as parent. Try it out!
+
+Let's look at::
+
+    FIND Guitar
+
+When we leave out the ``RECORD`` keyword, we will get every entity that is a
+Guitar. When you submit this query you should find also a RecordType Guitar
+in the results. Using  ``FIND RecordType Guitar`` would restrict the result to
+only that RecordType.
+
+Note, that you cannot only provide RecordType names after the ``FIND``, but names
+in general: ``FIND RECORD Nice Guitar``. This will give you a Record with the
+name "Nice Guitar" (if one exists... and there should be one in the demo instance).
+
+While it does not matter whether you use capital letters or not, the names have to
+be exact. There are two features that make it easy to use names for querying
+in spite of this:
+- You can use "*" to match any string. E.g. ``FIND RECORD Nice*``
+- After typing three letters, names that start with those three are
+suggested by the auto completion.
+
+.. note::
+
+   Train yourself by trying to guess what the result will be before
+   actually executing the query.
+
+
+Searching Data  Using Properties
+--------------------------------
+
+Looking for entities with certain names or such that have certain parents is
+nice. However, the queries become really useful if we can impose further conditions
+on the results. Let's start with an example again::
+
+    FIND Guitar with price > 10000
+
+This should list expensive guitars where are in the demo instance. Thus,
+we are using a property (the price) of the Guitar Records to restrict the
+result set. In general this looks like::
+
+    FIND <Name> <Property Filter>
+
+Typically, the filter has the form ``<Property> <Operator> <Value>``,
+for example ``length >= 0.7mm``.
+There are many filters available. You can check the specification for a comprehensive description of
+those. Here, we will only look at the most common examples.
+
+
+If you only want to assure that Records have a certain Property, without imposing
+constrains on the value, you can use::
+
+   FIND RECORD MusicalInstrument WITH Manufacturer
+
+
+Similarly, to what we saw above when using incomplete names, you can use a "*"
+to match parts of text properties::
+
+     FIND RECORD WITH serialNumber like KN*
+
+There is large number of operators that can be used together with dates or
+timestamps. One of the most useful is probably::
+
+    FIND RECORD WITH date in 2019
+
+A lot of valuable information is often stored in the relations among data, i.e. in
+the references of entities. So how can we use those?::
+
+    FIND RECORD WHICH REFERENCES A Guitar
+
+This should be pretty self explanatory. And it is also possible to check for
+references in the other direction::
+
+     FIND RECORD WHICH IS REFERENCED BY A Analysis
+
+You can also simply provide the ID of the entity::
+
+   FIND RECORD WHICH IS REFERENCED BY 123``
+
+
+Using Multiple Filters
+----------------------
+
+Often, one condition is not sufficient. Thus multiple filters/conditions can be combined.
+This can for example be done using the following structure::
+
+    FIND <Name> <Property Filter> (AND|OR) <Property Filter>
+
+An example would be::
+
+    FIND Guitar WITH price>48 AND electric=TRUE
+
+Furthermore, reference conditions can be nested::
+
+    FIND <Name> WHICH REFERENCES <Name> WHICH REFERENCES <Name>
+
+
+For example::
+
+    FIND Manufacturer WHICH IS REFERENCED BY Guitar WHICH IS REFERENCED BY Analysis
+
+
+Restricting Result Information
+------------------------------
+
+Using ``COUNT`` instead of ``FIND`` will only return the number of
+entities in the result set.
+
+.. note::  This is often useful when experimenting with queries.
+
+Using ``SELECT ... FROM`` instead of ``FIND`` returns specific
+information in a table. A comma separated list of Property names can be provided behind the
+``SELECT`` keyword::
+
+   SELECT price, electric FROM Guitar
+
+Or::
+
+   SELECT quality_factor, report, date FROM  Analysis WHICH REFERENCES A Guitar WITH electric=TRUE
+
+