From 0f1838d44f8dc89eba04c9c17058c668db0e2295 Mon Sep 17 00:00:00 2001 From: Timm Fitschen <t.fitschen@indiscale.com> Date: Fri, 14 Apr 2023 14:13:59 +0200 Subject: [PATCH] DOC: rephrase doc/Query.md --- doc/Query.md | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/doc/Query.md b/doc/Query.md index c7eaee8f..f9253d61 100644 --- a/doc/Query.md +++ b/doc/Query.md @@ -1,13 +1,16 @@ # Searching Data -This chapter introduces the CaosDB Query Language (CQL) which is used to create -search commands, also called queries, in CaosDB in an intuitive way. We recommend that you -try the examples out, for example on https://demo.indiscale.com. An interactive -tour is available on that public instance, that also covers the query language. -So you can start there and continue with this more in depth description -afterwards. + +In this chapter, the CaosDB Query Language (CQL) is presented as a means of +formulating search commands, commonly referred to as queries. It is highly +recommended that you experiment with the examples provided, such as those found +on https://demo.indiscale.com. An interactive tour is also available on this +public instance, which includes a comprehensive overview of the query language. +Therefore, it is suggested that you begin there and subsequently proceed with +this more detailed explanation. ## Introduction + Queries typically start with the keyword `FIND`, followed by a description of what you want to find. For example, you can search for all musical instruments with `FIND MusicalInstrument`. @@ -27,17 +30,19 @@ While queries like the last one are great to get an impression of the data, often we need to be more specific. Therefore, queries can include various conditions to restrict the result set. -An example is: `FIND MusicalAnalysis WITH quality_factor>0.5 AND date IN 2019` -The `WITH` keyword means that for each Record, it is checked, whether it has -a Property `quality_factor` that is larger than 0.5 and another Property `date` -that has a value that lies withing 2019. +Example: `FIND MusicalAnalysis WITH quality_factor>0.5 AND date IN +2019`. The keyword `WITH` signifies that for each Record of the type +`MusicalAnalysis`, an assessment is made to determine whether it possesses a +Property labelled `quality_factor` that exceeds 0.5, as well as another +Property labelled `date` that may correspond to any day within the year 2019. In order to make CQL easier to learn and to remember we designed it to be close to natural spoken English language. For example, you can write `FIND Guitar WHICH HAS A PROPERTY price`. Here, "HAS A PROPERTY" is what we call -syntactic sugar. It lets the query role easier from the tongue than +syntactic sugar. It lets the query role off the tongue more easily than `FIND Guitar WHICH price` but it is actually not needed and does not change -the meaning of the query. +the meaning of the query. In fact, you could also write `FIND Guitar WITH +price`. If you are only interested in the number of Entities that match your query, you can replace `FIND` with `COUNT` and the query will only return the number of @@ -49,7 +54,7 @@ with some external tool. `SELECT` queries offer to represent the query result in a tabular form. If you replace the `FIND` keyword of a query with `SELECT x, y, z FROM`, then -CaosDB will return the result as a table. +CaosDB will return the result as tabular data. For example, instead of `FIND Guitar`, try out `SELECT name, electric FROM Guitar` @@ -66,6 +71,7 @@ will for example learn how you can use references among Records, or meta data like the creation time of a Record to restrict the query result set. ## What am I searching for? + We already learned, that we can provide the name of a RecordType after the `FIND` keyword. Let's call this part of the query "entity expression". In general, we need to identify with the entity expression one or more entities via their name, CaosDB ID -- GitLab