compiler

README

SQaLice-compiler

Описание компиляции запроса

• Содержание
• Описание и назначение
• Формат запроса
• Структура запроса
• Типы математических операторов
• Типы логических операторов
• Блок fields
• Блок conditions
• Блок restrictions
• TO-DO

Описание методов парсинга запроса

• Список полей
• Список условий
• Условие по названию
• Поле сортировки
• Порядок сортировки
• Лимит
• Отступ

Описание методов изменения запроса

• Изменение списка полей
• Добавление условий
• Замена условия
• Добавление ограничений

Описание и назначение

Пакет компилятора SQaLice предназначен для гибкой обработки запросов к БД на PostgreSQL в проектах с применением go-swagger. SQaLice позволяет запрашивать конкретный набор полей из установленного target, фильтровать, сортировать и ограничивать получаемый набор строк.

Подготовка к использованию компилятора

В функцию-компилятор Compile в качестве аргумента передается modelsMap, содержащая информацию о полях моделей проекта, используемых для обработки целевого SQL кода. Рекомендуется формировать данную map динамически, например в init модуля при запуске проекта, что обеспечит консистентность сгенерированных посредством go-swagger моделей и данных, передаваемых в компилятор через map. Для этого можно использовать функцию FormDinamicModel. Также в этом случае в swagger-модели не должно быть вложенных моделей, иначе произойдут некорректное считывание тегов полей и ошибки формирования полей.

UPDATE 0.4 Начиная с данной версии считывание полей модели, используемых при компиляции запроса, а также при изменении исходной строки-аргумента params внесено внутрь целевых функций и не нуждается в отдельном формировании. В качестве аргумента model в Compile следует передавать структуру-модель, на которую планируется считывание данных из БД.

Формат запроса

В случае обращения к компилятору SQaLice все параметры целевого запроса должны содержаться в аргументе params. В target передается целевая таблица или view, к которой осуществляется запрос и которая используется при указании динамической модели.

Структура запроса

Аргумент params при парсинге запроса внутри Compile разделяется на 3 блока - fields, conditions, restrictions.

Пример адресной строки запроса, содержащей все 3 блока

http://url/.../query=ID,title,updatedAt?ID==10||ID==8?ID,desc,2,0

В случае отсутствия необходимости в указании одного из этих блоков, приведенное форматирование должно сохраняться.

Пример адресной строки запроса без блока conditions

http://url/.../query=ID,title,updatedAt??ID,desc,2,0

Запрос без указания условий в 3 блоках одновременно не рекомендуется, так как может привести к неожиданным ошибкам.

Типы математических операторов

SQaLice поддерживает следующие математические операторы:

Оператор	SQaLice	PG
РАВНО	==	=
НЕ РАВНО	!=	!=
МЕНЬШЕ	<	<
МЕНЬШЕ ИЛИ РАВНО	<=	<=
БОЛЬШЕ	>	>
БОЛЬШЕ ИЛИ РАВНО	>=	>=
СОДЕРЖИТ	>>	&&

Пример адресной строки, содержащей математический оператор

http://url/.../query=ID,name?ID!=10?,,2,0

Типы логических операторов

SQaLice поддерживает следующие логические операторы:

Оператор	SQaLice	PG
И	*	AND
ИЛИ	Двойная прямая черта	OR

Пример адресной строки запроса, содержащей оба оператора

http://url/.../query=?(ID==8*title==Тест)||ID==10?

Блок fields

Для получения всех полей из целевой SQL, содержащиеся в структуре модели modelsMap, нужно передавать данный блок пустым.

Пример адресной строки запроса с пустым блоком fields

http://url/.../query=?ID==10||ID==8?ID,desc,2,0

Для получения конкретных полей, в поле fields необходимо передавать название поля в формате json с запятыми в качестве разделителя и без пробелов.

ID,title,createdAt?

Пример адресной строки запроса для получения ID

http://url/.../query=ID?ID>=1?ID,desc,10,0

При передаче некорректного названия поля, SQaLice вернет ошибку:

"[SQaLice] Passed unexpected field name in select"

Блок conditions

В данном блоке возможно указание условий получения записей. Допускается передача пустого блока conditions, в таком случае происходит выборка без дополнительных условий.

Пример запроса без блока conditions

http://url/.../query=ID,title,createdAt??ID,asc,10,0

Условия должны разделяться допустимыми математическими операторами и не содержать пробелов.

Пример использования простой условной конструкции

?title==Тест?

Разделение нескольких условий осуществляется с помощью допустимых логических операторов, так же без пробелов. Кроме того могут быть использованы условные блоки в круглых скобках. Количество таких блоков не ограничено.

Пример использования сложной условной конструкции

(ID>8*ID<10)||title==Тест

ВАЖНО! При использовании сочетания условных блоков в скобках и без, блок без скобок должен указываться последним, как на приведенном выше примере. В противном случае запрос будет некорректным.

Для оператора == возможно указание нескольких значений через запятую, без пробелов. В таком случае происходит отбор значения по переданному массиву.

Пример условной конструкции с выбором по массиву

?ID==7,8,10?

При передаче условной конструкции с неверным логическим оператором, SQaLice вернет ошибку:

"[SQaLice] Unsupported operator in condition"

При передаче условной конструкции с неверным названием поля, SQaLice вернет ошибку:

"[SQaLice] Passed unexpected field name in condition"

Блок restrictions

В данном блоке возможно указание ограничений конечной выборки. Допускается передача пустого блока ограничений, в таком случае SQaLice не накладывает дополнительных условий на выборку.

Пример запроса без блока ограничений

http://url/.../query=ID,title,createdAt?ID>1?

При заполнении ограничений в блоке restrictions необходимо соблюдать порядок параметров блока, разделять их запятыми и не использовать пробелы

Порядок указания ограничений

Параметр	Допустимые значения
Поле сортировки	Поле, переданное в fieldsMap
Порядок сортировки	asc, desc
Лимит	Целое число >= 0
Оффсет	Целое число >= 0

Пример запроса со всеми параметрами ограничений

http://url/.../query=ID,title,createdAt?ID>1?ID,asc,10,0

Пример запроса с частью параметров (лимит, оффсет)

http://url/.../query=ID,title,createdAt?ID>1?,,10,0

При передаче некорректного названия поля сортировки, SQaLice вернет ошибку:

"[SQaLice] Unexpected selection order field"

При передаче некорректного порядка сортировки, SQaLice вернет ошибку:

"[SQaLice] Unexpected selection order"

При передаче некорректного лимита, SQaLice вернет ошибку:

"[SQaLice] Unexpected selection limit"

При передаче некорректного оффсета, SQaLice вернет ошибку:

"[SQaLice] Unexpected selection offset"

TO-DO

TO-DO	Статус
Покрытие тестами	Выполнено
Обработка сложных условий (вложенность, дополнительные операторы)	Выполнено частично
Снятие ограничений порядка условий	Не выполнено

Описание методов парсинга запроса

Список полей

Функция GetFieldsList позволяет получать список полей, приведенных к формату запроса в базу.

Пример строки запроса:

http://url/.../query=ID,title,updatedAt?ID==10||ID==8?ID,desc,2,0

Получаемый массив полей:

["id", "title", "updated_at"]

При обработке строки запроса, не содержащей список полей, будет возвращен пустой массив:

http://url/.../query=??

[]

При запросе поля, не входящего в модель, компилятор вернет ошибку:

"[SQaLice] Passed unexpected field name in select - field"

Список условий

Функция GetConditionsList позволяет получить список условий, содержащихся в запросе. При этом элементы условий приводятся к формату запроса к БД.

Формат условной структуры:

Имя	Тип	Описание
fieldName	string	Название поля
operator	string	Оператор
value	interface	Значение
isBracket	string	Признак "Условие в скобках"

Пример строки запроса:

http://url/.../query=ID,title,updatedAt?(title==testText)*ID!=8?ID,desc,2,0

Получаемый массив условий:

[
    {
        "fieldName": "title",
        "operator": "=",
        "value": {"testText"},
        "isBracket": true
    },
    {
        "fieldName": "id",
        "operator": "!=",
        "value": {"8"},
        "isBracket": false
    },
]

При обработке строки запроса, не содержащей условий, будет возвращен пустой массив:

http://url/.../query=??

[]

Пример ошибки:

"[SQaLice] Unsupported operator in condition - <<"

Условие по названию

Функция GetConditionByName позволяет получить первое по порядку условие по с переданным названием поля, содержащегося в запросе. При этом элементы условия приводятся к формату запроса к БД.

Формат условной структуры:

Имя	Тип	Описание
fieldName	string	Название поля
operator	string	Оператор
value	interface	Значение
isBracket	string	Признак "Условие в скобках"

Пример строки запроса:

http://url/.../query=ID,title,updatedAt?(ID==3)*ID!=8?ID,desc,2,0

Получаемый массив условий:

{
    "fieldName": "id",
    "operator": "=",
    "value": {"3"},
    "isBracket": true
}

При обработке строки запроса, не содержащей условий, будет возвращен пустой массив:

http://url/.../query=??

[]

Пример ошибки:

"[SQaLice] Unsupported operator in condition - <<"

Поле сортировки

Функция GetSortField позволяет получить поле сортировки, содержащееся в запросе. При этом название поля приводится к формату запроса к БД.

Пример строки запроса:

http://url/.../query=ID,title,updatedAt?(ID==3)*ID!=8?ID,desc,2,0

Получаемое название поля:

{
"id"
}

При обработке строки запроса, не содержащей ограничений, будет возвращена пустая строка:

http://url/.../query=??

""

Пример ошибки:

"[SQaLice] Unsupported field in restrictions - field"

Порядок сортировки

Функция GetSortOrder позволяет получить порядок сортировки, содержащийся в запросе.

Пример строки запроса:

http://url/.../query=ID,title,updatedAt?(ID==3)*ID!=8?ID,desc,2,0

Получаемый порядок сортировки:

{"desc"}

При обработке строки запроса, не содержащей ограничений, будет возвращена пустая строка:

http://url/.../query=??

""

Пример ошибки:

"[SQaLice] Unsupported field in restrictions - field"

Лимит

Функция GetLimit позволяет получить лимит, содержащийся в запросе.

Пример строки запроса:

http://url/.../query=ID,title,updatedAt?(ID==3)*ID!=8?ID,desc,2,0

Получаемый порядок сортировки:

2

При обработке строки запроса, не содержащего ограничений, будет возвращен nil:

http://url/.../query=??

nil

Пример ошибки:

"[SQaLice] Invalid negative selection limit - -1"

Отступ

Функция GetOffset позволяет получить отступ, содержащийся в запросе.

Пример строки запроса:

http://url/.../query=ID,title,updatedAt?(ID==3)*ID!=8?ID,desc,2,0

Получаемый порядок сортировки:

0

При обработке строки запроса, не содержащей ограничений, будет возвращен nil:

http://url/.../query=??

nil

Пример ошибки:

"[SQaLice] Invalid negative selection offset - -1"

TO-DO	Статус
Покрытие тестами	Выполнено
Расширение получения условий запроса	Не выполнено

Изменение списка полей

Функция AddQueryFieldsToSelect позволяет добавлять дополнительные поля в SELECT блок запроса, либо полностью заменить его. Это регулируется флагом isDeleteCurrent. Передаваемые поля проверяются по аргументу fieldsMap на наличие в модели, если он передан. В случае передачи неверного поля, компилятор пропустит данное поле. Если fieldsMap не передан, все поля добавляются в запрос без проверки

UPDATE 0.4 Начиная с данной версии считывание полей модели, используемых при компиляции запроса, а также при изменении исходной строки-аргумента params внесено внутрь целевых функций и не нуждается в отдельном формировании. В качестве аргумента model при получении/изменении условий запроса необходимо передавать модель, на которую планируется считывание данных

Добавление условий

Функция AddQueryConditions позволяет добавлять дополнительные условия в запрос, либо полностью заменить их. Это регулируется флагом isDeleteCurrent. Если в условии передан некорректный оператор, компилятор вернет ошибку:

"[SQaLice] Passed incorrect operator in query condition"

Добавляемые поля разделяются логическим оператором AND между собой, а также с текущими условиями запроса.

Замена условия

Функция ReplaceQueryCondition позволяет заменить текущее условие в запросе по названию поля. Если условия с переданным именем нет в запросе, компилятор вернет ошибку:

"[SQaLice] Condition with passed name not found"

Добавление ограничений

Функция AddQueryRestrictions позволяет заменить поле и порядок сортировки, лимит и оффсет в запросе.

Documentation

Index

• func AddQueryConditions(query string, conds []CondExpr, isDeleteCurrent bool) (string, error)
• func AddQueryFieldsToSelect(model interface{}, query string, fieldsArray []string, isDeleteCurrent bool) (string, error)
• func AddQueryRestrictions(query string, sortField string, sortOrder string, limit string, offset string) (string, error)
• func Compile(model interface{}, target string, params string, withCount bool) (string, string, error)
• func GetFieldsList(model interface{}, q string) (fieldsList []string, err error)
• func GetLimit(q string) (limit *int, err error)
• func GetOffset(q string) (limit *int, err error)
• func GetSortField(model interface{}, q string) (field string, err error)
• func GetSortOrder(q string) (order string, err error)
• func ReplaceQueryCondition(model interface{}, query string, newCond CondExpr) (string, error)
• type CondExpr
  • func GetConditionByName(model interface{}, q string, fieldName string, toDBFormat bool) (condExpr *CondExpr, err error)
  • func GetConditionsList(model interface{}, q string, toDBFormat bool) (condExprsList []*CondExpr, err error)

Functions

func AddQueryConditions

func AddQueryConditions(query string, conds []CondExpr, isDeleteCurrent bool) (string, error)

AddQueryConditions adds conditions to query conditions list with AND separators If isDeleteCurrent argument passed, conds list peplacing current query conditions

func AddQueryFieldsToSelect

func AddQueryFieldsToSelect(model interface{}, query string, fieldsArray []string, isDeleteCurrent bool) (string, error)

AddQueryFieldsToSelect adds fieldsMap JSON or fieldsArray fields in SELECT block, replacing current fields in query if isDeleteCurrent passed as true

func AddQueryRestrictions

func AddQueryRestrictions(query string, sortField string, sortOrder string, limit string, offset string) (string, error)

AddQueryRestrictions adds restrictions to query restrictions block instead of current If argument is not passed, query saves current parameter

func Compile

func Compile(model interface{}, target string, params string, withCount bool) (string, string, error)

Compile assembles a query strings to PG database for main query and count query

func GetFieldsList

func GetFieldsList(model interface{}, q string) (fieldsList []string, err error)

GetFieldsList returns a list of query fields in SQL format

func GetLimit

func GetLimit(q string) (limit *int, err error)

GetLimit returns selection limit from query

func GetOffset

func GetOffset(q string) (limit *int, err error)

GetOffset returns selection offset from query

func GetSortField

func GetSortField(model interface{}, q string) (field string, err error)

GetSortField returns selection sort field from query

func GetSortOrder

func GetSortOrder(q string) (order string, err error)

GetSortOrder returns selection order from query

func ReplaceQueryCondition

func ReplaceQueryCondition(model interface{}, query string, newCond CondExpr) (string, error)

ReplaceQueryCondition replaces query condition by fieldName

Types

type CondExpr

type CondExpr struct {
	FieldName string
	Operator  string
	Value     interface{}
	IsBracket bool
}

CondExpr describes structure of query condition

func GetConditionByName

func GetConditionByName(model interface{}, q string, fieldName string, toDBFormat bool) (condExpr *CondExpr, err error)

GetConditionByName returns first condition with passed name and operator

func GetConditionsList

func GetConditionsList(model interface{}, q string, toDBFormat bool) (condExprsList []*CondExpr, err error)

GetConditionsList returns a list of all query conditions in SQL format