mirror of
https://github.com/Infinidat/infi.clickhouse_orm.git
synced 2024-11-28 19:53:44 +03:00
85 lines
3.0 KiB
Markdown
85 lines
3.0 KiB
Markdown
|
|
Expressions
|
|
===========
|
|
|
|
One of the ORM's core concepts is _expressions_, which are composed using functions, operators and model fields. Expressions are used in multiple places in the ORM:
|
|
|
|
- When defining [field options](field_options.md) - `default`, `alias` and `materialized`.
|
|
- In [table engine](table_engines.md) parameters for engines in the `MergeTree` family.
|
|
- In [queryset](querysets.md) methods such as `filter`, `exclude`, `order_by`, `aggregate` and `limit_by`.
|
|
|
|
Using Expressions
|
|
-----------------
|
|
|
|
Expressions usually include ClickHouse database functions, which are made available by the `F` class. Here's a simple function:
|
|
```python
|
|
from infi.clickhouse_orm.models import F
|
|
expr = F.today()
|
|
```
|
|
|
|
Functions that accept arguments can be composed, just like when using SQL:
|
|
```python
|
|
expr = F.toDayOfWeek(F.today())
|
|
```
|
|
|
|
You can see the SQL expression that is represented by an ORM expression by calling its `to_sql` or `repr` methods:
|
|
```python
|
|
>>> print(expr.to_sql())
|
|
toDayOfWeek(today())
|
|
```
|
|
|
|
### Operators
|
|
|
|
ORM expressions support Python's standard arithmetic operators, so you can compose expressions using `+`, `-`, `*`, `/` and `%`. For example:
|
|
```python
|
|
# A random integer between 1 and 10
|
|
F.rand() % 10 + 1
|
|
```
|
|
|
|
There is also support for comparison operators (`<`, `<=`, `==`, `>=`, `>`, `!=`) and logical operators (`&`, `|`, `~`, `^`) which are often used for filtering querysets:
|
|
```python
|
|
# Is it Friday the 13th?
|
|
(F.toDayOfWeek(F.today()) == 6) & (F.toDayOfMonth(F.today()) == 13)
|
|
```
|
|
|
|
### Referring to model fields
|
|
|
|
To refer to a model field inside an expression, use `<class>.<field>` syntax, for example:
|
|
```python
|
|
# Convert the temperature from Celsius to Fahrenheit
|
|
Sensor.temperature * 1.8 + 32
|
|
```
|
|
|
|
Inside model class definitions omit the class name:
|
|
```python
|
|
class Person(Model):
|
|
height_cm = fields.Float32Field()
|
|
height_inch = fields.Float32Field(alias=height_cm/2.54)
|
|
...
|
|
```
|
|
|
|
### Creating new "functions"
|
|
|
|
Since expressions are just Python objects until they get converted to SQL, it is possible to invent new "functions" by combining existing ones into useful building blocks. For example, we can create a reusable expression that takes a string and trims whitespace, converts it to uppercase, and changes blanks to underscores:
|
|
```python
|
|
def normalize_string(s):
|
|
return F.replaceAll(F.upper(F.trimBoth(s)), ' ', '_')
|
|
```
|
|
|
|
Then we can use this expression anywhere we need it:
|
|
```python
|
|
class Event(Model):
|
|
code = fields.StringField()
|
|
normalized_code = fields.StringField(materialized=normalize_string(code))
|
|
```
|
|
|
|
### Which functions are available?
|
|
|
|
ClickHouse has many hundreds of functions, and new ones often get added. If you encounter a function that the database supports but is not available in the `F` class, please report this via a GitHub issue. You can still use the function by providing its name:
|
|
```python
|
|
expr = F("someFunctionName", arg1, arg2, ...)
|
|
```
|
|
|
|
---
|
|
|
|
[<< Models and Databases](models_and_databases.md) | [Table of Contents](toc.md) | [Querysets >>](querysets.md) |