The FactQuery object is used to make queries to the database of facts. The fact database is a collection of records, where each record (fact) has the following fields:
context) — a string up to 255 characters long, indicating the subject area. Participates in the search.name) is a string up to 255 characters long that identifies the fact within the context. Participates in the search.value) is an arbitrary value representing the content of the fact. The search for this field is not supported.botId) is a string that can be specified to link a fact to a specific bot. Participates in the search.clientId) is a string that can be specified to link a fact to a client. Participates in the search.select(fields)Sets a list of fields from the database of facts, the values of which should be returned as a result of the request. By default, the fields context, name and value are returned.
Arguments: fields is a comma-separated string of fields or a collection of fields to be returned.
Usage Example:
$facts = fact.query().rows() // select is not called, we return all fields.
$facts = fact.query().select(["value", "context"]).rows() // Returning a list of facts for which we need only value and context.
$facts = fact.query().select("botId").rows() // We return only the botId field to which the facts are linked.
where(field, operator, value)Adds a search condition for filtering facts. Multiple calls are combined by a logical And. Is equivalent to andWhere.
Arguments:
field is the name of the field for which the condition is set (i.e. the first argument of the operator operation).operator — an operator indicating the operation performed on the field. See the list of available operations below.value is the second argument of the operation.Return value: The FactQuery object.
List of available operations:
"=" — checking that field is equal to value."!=" or "<>" — check for the inequality that field is not equal to value.">" — checks that field is greater than value."<" — checks that field is less than value.">=" — checks that field is greater than or equal to value."<=" — checks that field is less than or equal to value."^@" or "startsWith" — searches for a match between the string valueand the beginning offield`. The search is case-sensitive."~" — checks whether the field matches the regular expression value. The search is case-sensitive."!~" — checks if field does not match the regular expression value. The search is case-sensitive."~*" — checks whether the field matches the regular expression value. The search is case-independent."!~*" — checks if field does not match the regular expression value. The search is case-independent."in" — checks if field matches at least one value in the value collection."not in" — checks if field does not match all values from the value collection.Usage Example:
// Searching for facts where context contains the substring test
$facts = fact.query().
select("name,value").
where("context", "~", "^.*test.*$").
rows()
orWhere(field, operator, value)Adds a search term combined with the previous ones by a logical "OR". At least one of the conditions must be met.
Arguments:
field is the name of the field to which the condition applies.operator — comparison operator (for example, "=", "~", " in", see available operators).value — the value that the field is compared to.Usage Example:
$facts = fact.query()
.where("context", "=", "test")
.orWhere("name", "=", "example")
.rows();
// Searches for facts where "context" is equal to "test" or "name" is equal to "example".
andWhere(cond FactQueryCondition)Adds a compound search term combined with the previous ones by a logical “And".
It is equivalent to calling where(cond).
Signature: andWhere(cond FactQueryCondition) FactQuery
Arguments: cond is a FactQueryCondition object containing one or more nested conditions.
Return value: The FactQuery object.
sortBy(fields string|Collection)Sets the sorting of facts by the specified fields.
Signature: sortBy(fields string|Collection) FactQuery
Arguments: fields is a comma—separated string of fields or a collection of field names.
Each field can have a prefix:
+ — ascending sorting (default if no prefix is specified);- — sort in descending order.Return value: A FactQuery object with sorting applied.
Usage Example:
// We get all the facts for the bot with double sorting:
// First by context in ascending order (i.e. in alphabetical order)
// And then by the name of the fact in descending order.
$facts = fact.query().
select("name,value").
where("botId", "=", @botId)
sortBy("+context,-name"). // You can also use collectibles. For example, sortBy(["+context", "-name"])
rows()
limit(limit int)Sets a limit on the maximum number of extracted facts.
Signature: limit(limit int) FactQuery
Arguments: limit is an integer specifying a limit on the number of results.
Return value: The FactQuery object.
Usage Example:
// We get the first 10 facts
$facts = fact.query().
select("name,value").
sortBy("name").
limit(10).
rows()
skip(count int)Sets the number of facts to skip when executing the query.
Signature: skip(count int) FactQuery
Arguments: count is an integer specifying the number of facts to skip.
Return value: The FactQuery object.
Usage Example:
// Skip the first 5 facts and extract the next 10
$facts = fact.query().
select("name,value").
sortBy("name").
skip(5).
limit(10).
rows()
one()Returns the value of the first fact found — only the first field specified via select is used.
Signature: one() mixed
Arguments: Missing.
Return value: The value of the first selected field.
Usage Example:
// Extracts the name of the first fact found
$firstFactName = fact.query().
select("name,value"). // value is specified, but it will be ignored
one()
column()Retrieves the list of values of the first selected field of all found facts.
Signature: column() List
Arguments: Missing.
Return value: A list of values.
Usage Example:
// Retrieves a list of names from all matching facts
$names = fact.query().
select("name,value"). // value is specified but will be ignored
column()
row()Returns all selected fields as an associative array for the first fact found.
Signature: row() Map
Arguments: Missing.
Return value: An associative array containing the values of all selected fields of the first fact.
Usage Example:
// Extracts the name and value of the first fact found
$names = fact.query().
select("name,value").
row()
rows()Returns a list of all found facts.
Each fact is represented as an associative array, where the keys are the names of the fields, and the values are the contents of these fields.
Signature: rows() List<Map>
Arguments: Missing.
Return value: A list of associative arrays— one for each fact found.
Usage Example:
// Extracts the name and value of all facts
$names = fact.query().
select("name,value").
rows()