Skip to content
Snippets Groups Projects
Verified Commit 0f1838d4 authored by Timm Fitschen's avatar Timm Fitschen
Browse files

DOC: rephrase doc/Query.md

parent 64c238d4
No related branches found
No related tags found
2 merge requests!96DOC: Added CITATION.cff to the list of files in the release guide where the...,!89DOC: enhance query documentation
Pipeline #35704 failed
# 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
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment