Объект FactQuery предназначен для выполнения запросов к базе фактов. База фактов представляет собой коллекцию записей, где каждая запись (факт) имеет следующие поля:
select(fields)Задает список полей из базы фактов, значения которых следует вернуть в результате запроса. По умолчанию возвращаются поля context, name и value.
Аргументы: fields — строка с перечислением полей через запятую или коллекция полей, которые необходимо вернуть.
Пример использования:
$facts = fact.query().rows() // select не вызван возвращаем все поля.
$facts = fact.query().select(["value", "context"]).rows() // Возвращаем список фактов, для которых нам нужны только value и context.
$facts = fact.query().select("botId").rows() // Возвращаем только поле botId, к которому привязаны факты.
where(field, operator, value)Добавляет условие поиска для фильтрации фактов. Несколько вызовов объединяются по логическому «И». Эквивалентен andWhere.
Аргументы:
field – название поля, для которого задаётся условие (т.е. первый аргумент операции operator).operator – оператор, обозначающий операцию, выполняющуюся над field. Список доступных операций смотри ниже.value – второй аргумент операции.Возвращаемое значение: Объект FactQuery.
Список доступных операций:
"=" — проверка, что field равно value."!=" или "<>" — проверка на неравенство, что field не равно value.">" — проверяет, что field больше value."<" — проверяет, что field меньше value.">=" — проверяет, что field больше или равно value."<=" — проверяет, что field меньше или равно value."^@" или "startsWith" — ищет совпадение строки valueс началомfield`. Поиск регистрозависимый."~" — проверяет соответствие field регулярному выражению value. Поиск регистрозависимый."!~" — проверяет несоотвествие field регулярному выражению value. Поиск регистрозависимый."~*" — проверяет соответствие field регулярному выражению value. Поиск регистронезависимый."!~*" — проверяет несоотвествие field регулярному выражению value. Поиск регистронезависимый."in" — проверяет совпадение field хотя бы с одним значением в коллекции value."not in" — проверяет несовпадение field со всеми значениями из коллекции value.Пример использования:
// Ищем факты, у которых context содержит подстроку test
$facts = fact.query().
select("name,value").
where("context", "~", "^.*test.*$").
rows()
orWhere(field, operator, value)Добавляет условие поиска, объединенное с предыдущими по логическому «ИЛИ». Должно выполняться хотя бы одно из условий.
Аргументы:
field — название поля, к которому применяется условие.operator — оператор сравнения (например, "=", "~", "in", см. доступные операторы).value — значение, с которым сравнивается поле.Пример использования:
$facts = fact.query()
.where("context", "=", "test")
.orWhere("name", "=", "example")
.rows();
// Ищет факты, у которых "context" равно "test" или "name" равно "example".
andWhere(cond FactQueryCondition)Добавляет составное условие поиска, объединенное с предыдущими по логическому “И”.
Эквивалентен вызову where(cond).
Сигнатура: andWhere(cond FactQueryCondition) FactQuery
Аргументы: cond — объект FactQueryCondition, содержащий одно или несколько вложенных условий.
Возвращаемое значение: Объект FactQuery.
sortBy(fields string|Collection)Задает сортировку фактов по указанным полям.
Сигнатура: sortBy(fields string|Collection) FactQuery
Аргументы: fields — строка с перечислением полей через запятую или коллекция названий полей.
Каждое поле может иметь префикс:
- + — сортировка по возрастанию (по умолчанию, если префикс не указан);
- - — сортировка по убыванию.
Возвращаемое значение: Объект FactQuery с примененной сортировкой.
Пример использования:
// Получаем все факты для бота с двойной сортировкой:
// Сначала по контексту по возрастанию (т.е. в алфавитном порядке)
// И далее по имени факта по убыванию.
$facts = fact.query().
select("name,value").
where("botId", "=", @botId)
sortBy("+context,-name"). // Можно также использовать коллеции. Например, sortBy(["+context", "-name"])
rows()
limit(limit int)Ставит ограничение на максимальное количество извлекаемых фактов.
Сигнатура: limit(limit int) FactQuery
Аргументы: limit — целое число, определяющее лимит на количество результатов.
Возвращаемое значение: Объект FactQuery.
Пример использования:
// Получаем первые 10 фактов
$facts = fact.query().
select("name,value").
sortBy("name").
limit(10).
rows()
skip(count int)Задает количество фактов, которые следует пропустить при выполнении запроса.
Сигнатура: skip(count int) FactQuery
Аргументы: count — целое число, определяющее количество фактов для пропуска.
Возвращаемое значение: Объект FactQuery.
Пример использования:
// Пропускаем 5 первых фактов и извлекаем следующие 10
$facts = fact.query().
select("name,value").
sortBy("name").
skip(5).
limit(10).
rows()
one()Возвращает значение первого найденного факта — используется только первое указанное через select поле.
Сигнатура: one() mixed
Аргументы: Отсутствуют.
Возвращаемое значение: Значение первого выбранного поля.
Пример использования:
// Извлекает имя первого найденного факта
$firstFactName = fact.query().
select("name,value"). // value хоть и указано, но будет проигнорировано
one()
column()Возвращает список значений первого выбранного поля всех найденных фактов.
Сигнатура: column() List
Аргументы: Отсутствуют.
Возвращаемое значение: Список значений.
Пример использования:
// Извлекает список имён всех найденных фактов
$names = fact.query().
select("name,value"). // value хоть и указано, но будет проигнорировано
column()
row()Возвращает все выбранные поля в виде ассоциативного массива для первого найденного факта.
Сигнатура: row() Map
Аргументы: Отсутствуют.
Возвращаемое значение: Ассоциативный массив — значения всех выбранных полей первого факта.
Пример использования:
// Извлекает имя и значение первого найденного факта
$names = fact.query().
select("name,value").
row()
rows()Возвращает список всех найденных фактов.
Каждый факт представлен как ассоциативный массив, где ключи — это имена полей, а значения — содержимое этих полей.
Сигнатура: rows() List<Map>
Аргументы: Отсутствуют.
Возвращаемое значение: Список ассоциативных массивов — по одному на каждый найденный факт.
Пример использования:
// Извлекает имя и значение всех фактов
$names = fact.query().
select("name,value").
rows()