forked from hinterland/documentation
168 lines
4.2 KiB
Markdown
168 lines
4.2 KiB
Markdown
База на которой основанны запросы
|
||
```mermaid
|
||
erDiagram
|
||
PEOPLE ||--|{ ORDERS : "id -> person_id"
|
||
|
||
PEOPLE {
|
||
int id PK
|
||
string name
|
||
int age
|
||
string status
|
||
boolean active
|
||
date created_at
|
||
}
|
||
|
||
ORDERS {
|
||
int id PK
|
||
int person_id FK
|
||
date order_date
|
||
decimal total
|
||
}
|
||
```
|
||
|
||
# Базовый запрос
|
||
```http
|
||
GET /people
|
||
```
|
||
|
||
Вернёт все доступные записи таблицы.
|
||
|
||
# Фильтры и условия
|
||
```http
|
||
GET /people?колонка=оператор.значение
|
||
```
|
||
|
||
## Основные операторы
|
||
- `eq` — равно `?age=eq.20`
|
||
- `gt` / `gte` — больше / больше либо равно `?age=gt.18`
|
||
- `neq` — не равно `?age=neq.20`
|
||
- `lt` / `lte` — меньше / меньше либо равно `?age=lt.65`
|
||
- `like` / `ilike` — шаблон (регистр учитывается / не учитывается) `?name=ilike.*alex*`
|
||
- `in` — входит в набор `?id=in.(1,2,3)`
|
||
- `not.in` — не входит в набор `?id=not.in.(1,2,3)`
|
||
- `match` / `imatch` — [patern matching documentation](https://www.postgresql.org/docs/current/functions-matching.html)
|
||
- `isdistinct` - !=, но можно использовать с NULL `?age=neq.null`
|
||
- `is` — проверка на NULL (или true/false) `?status=is.null` / `?active=is.true`
|
||
|
||
## Логические операторы (объединение)
|
||
- `and` — несколько условий вместе
|
||
`?and=(status.eq.active,age.gt.18)`
|
||
- `or` — логическое «или»
|
||
`?or=(name.eq.John,name.eq.Mike)`
|
||
- `all`
|
||
|
||
## Поноценный поиск по тексту
|
||
<!-- TODO: нормальное описание -->
|
||
- `fts` - по по...
|
||
- `plfts` - поиск по по тексту
|
||
- `phfts` - поиск по фразам
|
||
- `wfts` - поиск по словам
|
||
|
||
# Селекторы (выбор колонок)
|
||
```http
|
||
GET /people?select=id,name,age
|
||
```
|
||
Вернёт только указанные колонки.
|
||
|
||
## Переименование полей
|
||
```http
|
||
GET /people?select=person_id:id,person_name:name
|
||
```
|
||
Вернёт указанные колонки с указанными именами.
|
||
```json
|
||
[
|
||
{
|
||
"person_id": null,
|
||
"person_name": null
|
||
}
|
||
]
|
||
```
|
||
|
||
## Многоуровневый селект
|
||
Если есть связь, например `people` → `orders` (по `people.id = orders.person_id`), то:
|
||
```http
|
||
GET /people?select=id,name,orders(*)
|
||
```
|
||
Вернёт людей вместе со всеми их заказами.
|
||
```json
|
||
[
|
||
{
|
||
"id": null,
|
||
"name": null,
|
||
"orders": [
|
||
...
|
||
]
|
||
}
|
||
...
|
||
]
|
||
```
|
||
```http
|
||
GET /people?order=id,total,person(id, name)
|
||
```
|
||
Вернёт заказы вместе с заказчиками.
|
||
```json
|
||
[
|
||
{
|
||
"id": null,
|
||
"total": null,
|
||
"person": {
|
||
"id": null,
|
||
"name": null
|
||
}
|
||
}
|
||
...
|
||
]
|
||
```
|
||
```http
|
||
GET /people?order=id,total,...person(name)
|
||
```
|
||
Вернёт заказ встроив поля заказчика на верхний уровень.
|
||
```json
|
||
[
|
||
{
|
||
"id": null,
|
||
"total": null,
|
||
"name": null
|
||
}
|
||
...
|
||
]
|
||
```
|
||
|
||
# Сортировка
|
||
```http
|
||
GET /people?order=age.desc
|
||
```
|
||
Сортировка по колонке `age` в обратном порядке.
|
||
Может быть цепочка: `?order=age.desc,name.asc`
|
||
|
||
# Лимиты и сдвиги
|
||
```http
|
||
GET /people?limit=10&offset=20
|
||
```
|
||
Вернёт 10 записей начиная с 21-й.
|
||
|
||
# Агрегации
|
||
Для агрегаций есть расширенный синтаксис:
|
||
|
||
- `count=exact` вернёт общее кол-во строк в заголовке `Content-Range`.
|
||
- `Prefer: count=exact` в заголовке запроса даёт то же самое.
|
||
|
||
## Пример: агрегированные поля
|
||
<!-- TODO: -->
|
||
|
||
# Пример комбинированного запроса
|
||
Вернуть людей:
|
||
|
||
- Только id, name.
|
||
- Возраст > 18.
|
||
- Отсортировать по убыванию по created_at.
|
||
- Вернуть не более 5 записей.
|
||
|
||
```http
|
||
GET /people
|
||
?select=id,name
|
||
&age=gt.18
|
||
&order=created_at.desc
|
||
&limit=5
|
||
```
|