Skip to content

Commit 4ac2e6e

Browse files
oleksiib-humaoleksiib-huma
authored
Add a new page for advanced queries (#140)
1 parent d130735 commit 4ac2e6e

2 files changed

Lines changed: 150 additions & 63 deletions

File tree

‎data-collection/builder/advanced-queries/index.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
sidebar_position: 5
3+
title: Advanced Query Language
4+
---
5+
6+
# Advanced Query Language (DSL)
7+
8+
The Advanced Query feature uses a Domain-Specific Language (DSL) to create dynamic, personalized filters for articles and recommendations. This powerful system allows you to build complex logic using variables, primitives, functions, and conditional statements to deliver relevant content based on user data and context.
9+
10+
## Key Variables
11+
12+
These built-in variables provide essential context for your queries:
13+
14+
- **`EMPTY`**: Represents an empty result set. Use when you want to return no results under certain conditions.
15+
16+
**Example:** `unread(articles) if user.age >= 18 else EMPTY`
17+
18+
Returns unread articles for users 18+, otherwise returns nothing.
19+
20+
- **`NOW`**: Current date and time timestamp.
21+
22+
- **`TODAY`**: Current date (without time component).
23+
24+
- **`articles`**: Collection of all available articles. Use this for article-specific queries like `unread(articles)`, `limit(articles, 5)`, or `filter(articles, tags="HR")`.
25+
26+
- **`recommendations`**: Collection of all available recommendations. Use this for recommendation-specific queries like `limit(recommendations, 3)`, or `filter(recommendations, tags="exercise")`.
27+
28+
## Data Primitives
29+
30+
Access user health data through the `data` object structure:
31+
32+
### Basic Metrics
33+
- **`data.<primitive>`**: Access any recorded health metric (HeartRate, Weight, Temperature, etc.)
34+
- **`data.<primitive>.value`**: The actual recorded value (number or decimal)
35+
- **`data.<primitive>.flags`**: Severity level indicators with three levels:
36+
- `flags.gray`: Normal range
37+
- `flags.amber`: Warning level
38+
- `flags.red`: Critical level
39+
40+
### Complex Metrics
41+
For metrics with multiple values:
42+
- `data.BloodPressure.systolicValue`
43+
- `data.BloodPressure.diastolicValue`
44+
45+
## Functions
46+
47+
### Core Functions
48+
49+
- **`limit(collection: array, count: int)`**
50+
51+
Restricts the number of returned items from the specified collection.
52+
53+
**Examples:**
54+
- `limit(unread(articles), 2)` - Shows maximum 2 unread articles
55+
- `limit(recommendations, 3)` - Shows maximum 3 recommendations
56+
57+
- **`unread(articles: array)`**
58+
59+
Filters to show only unread articles.
60+
61+
**Example:**
62+
```
63+
unread(articles)
64+
```
65+
Returns all unread articles.
66+
67+
- **`filter(collection: array, tags: string)`**
68+
69+
Filters items by specific tags from the specified collection.
70+
71+
**Examples:**
72+
- `filter(articles, tags="HR")` - Shows articles tagged with "HR"
73+
- `filter(recommendations, tags="exercise")` - Shows recommendations tagged with "exercise"
74+
75+
- **`random(collection: array, count: int)`**
76+
77+
Returns a random selection from the specified collection.
78+
79+
**Examples:**
80+
- `random(articles, 3)` - Shows 3 randomly selected articles
81+
- `random(recommendations, 2)` - Shows 2 randomly selected recommendations
82+
83+
## Conditional Logic
84+
85+
The DSL uses Python-style syntax for building complex conditions:
86+
87+
### If/else Statements
88+
89+
**Syntax:** `<result_if_true> if <condition> else <result_if_false>`
90+
91+
**Example:**
92+
```
93+
filter(articles, tags="HR") if data.HeartRate.flags.red > 0 else limit(unread(articles), 2)
94+
```
95+
Shows heart rate articles if the last reading is critical, otherwise shows 2 unread articles.
96+
97+
### Logical Operators
98+
99+
- **`and`**: Both conditions must be true
100+
- **`or`**: Either condition can be true
101+
102+
**Example:**
103+
```
104+
unread(articles) if data.HeartRate.flags.amber or data.HeartRate.flags.red else random(recommendations, 2)
105+
```
106+
Returns unread articles if heart rate is in warning or critical range, otherwise shows 2 random recommendations.
107+
108+
### Combination Operator
109+
110+
- **`+`**: Combines multiple article sets
111+
112+
**Example:**
113+
```
114+
filter(articles, tags="HR") + filter(recommendations, tags="sport")
115+
```
116+
Shows all articles tagged with "HR" plus all recommendations tagged with "sport".
117+
118+
## Practical Examples
119+
120+
### Basic Filtering
121+
```
122+
limit(unread(articles), 5)
123+
limit(recommendations, 3)
124+
```
125+
Show 5 most recent unread articles, or 3 most recent recommendations.
126+
127+
### Health-Based Filtering
128+
```
129+
filter(articles, tags="diabetes") if data.BloodSugar.flags.red else unread(articles)
130+
```
131+
Show diabetes articles if blood sugar is critical, otherwise show all unread articles.
132+
133+
### Complex Conditions
134+
```
135+
filter(articles, tags="exercise") if data.HeartRate.value > 100 and data.Weight.flags.amber else limit(articles, 3)
136+
```
137+
Show exercise articles if heart rate is elevated and weight is in warning range, otherwise show 3 articles.
138+
139+
### Combining Collections
140+
```
141+
filter(articles, tags="nutrition") + filter(recommendations, tags="diet")
142+
```
143+
Show nutrition articles combined with diet recommendations.
144+
145+
---
146+
147+
This guide provides a comprehensive understanding of how to leverage the Advanced Query feature using DSL. Use these tools to create personalized, context-aware queries that can target either articles or recommendations based on user health data and preferences.

‎data-collection/builder/creating-app-content/index.md‎

Lines changed: 3 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -75,67 +75,7 @@ Once you have created a few content pieces, you can start adding those to the de
7575

7676
![alt text](<../assets/Feature articles-4.png>)
7777

78-
- <span style={{ backgroundColor: '#EBEBEB', padding: '0 5px', borderRadius: '5px' }}>Advanced query</span> allows you to apply advanced logic to which content pieces will be shown.
79-
80-
### Advanced Query
81-
82-
In Advanced query, there are some key variables, primitives, functions, and basic conditional logic you can use to create your query.
83-
* **Key Variables**
84-
- `EMPTY`: Represents an empty list. Use this when you don't want to return any articles. For example, `unread(articles) if user.age >= 18 else EMPTY` will return a list of unread articles if the user is an adult, and no articles if they are not.
85-
- `NOW`: Refers to the current date and time.
86-
- `TODAY`: Refers to the current date.
87-
- `articles` : Represents all available articles. This is typically used as the first parameter in most functions, such as `unread(articles)`, `limit(articles, 5)`, or `filter(articles, tag="HR")`.
88-
89-
* **Primitives**
90-
- `data.<primitive>`: Serves as a placeholder for any last recorded basic metric, such as HeartRate, Weight, or BMI. This can include multiple nested fields like:
91-
- `data.<primitive>.flags`: A flags object that includes `flags.gray`, `flags.amber`, and `flags.red`. These attributes represent the severity levels calculated for the metric.
92-
- `data.<primitive>.value`: The value recorded by the user, typically a number or a decimal, depending on the metric.
93-
- More complex primitives:
94-
- `data.BloodPressure.systolicValue`
95-
- `data.BloodPressure.diastolicValue`
96-
- `data.CVDRiskScore.roundedValue`
97-
98-
* **Functions**
99-
- `limit(articles: array, count: int)`: Limits the number of articles to the specified count.
100-
Example:
101-
`limit(unread(articles), 2)` will show a maximum of 2 unread articles.
102-
- `unread(articles: array)`: Filters articles to show only those that are unread.
103-
104-
Example:
105-
106-
unread(articles)
107-
108-
It will display all unread articles.
109-
110-
111-
* **Conditions**
112-
113-
Our DSL follows Python syntax, enabling the creation of complex conditional logic.
114-
- `if/else`:
115-
116-
Example:
117-
118-
<if true result> if data.HeartRate.flags else <else result>
119-
120-
Usage:
121-
```
122-
filter(articles, tag="HR") if data.HeartRate.flags.red > 0 else limit(unread(articles), 2)
123-
```
124-
This condition displays articles tagged with "HR" if the last HeartRate record is in the red severity level. Otherwise, it shows 2 unread articles.
125-
126-
- `and/or`:
127-
128-
Example:
129-
130-
unread(articles) if data.HeartRate.flags.amber or data.HeartRate.flags.red else random(articles, 2)
131-
This condition returns all unread articles if the last HeartRate record is within amber or red severity levels. Otherwise, it shows 2 random articles.
132-
133-
- `+` (add operation):
134-
135-
Example:
136-
137-
filter(articles, tag="HR") + filter(articles, tag="sport")
138-
This will display all articles tagged with either "HR" or "sport."
139-
140-
This guide should provide a clear understanding of how to leverage the "Featured Article" feature using DSL Queries. Use these tools to tailor the content you see to match your specific needs and interests.
78+
- <span style={{ backgroundColor: '#EBEBEB', padding: '0 5px', borderRadius: '5px' }}>Advanced query</span> allows you to apply advanced logic to which content pieces will be shown.
79+
80+
[Learn more about Advanced Query](../advanced-queries/).
14181

0 commit comments

Comments
 (0)