Functions for working with facts provide control over the fact database, allowing you to save, retrieve, delete, and clear data.
fact.saveSaves a fact to the fact database.
Signature: fact.save(context string, factName string, factValue mixed, botId string = nil, clientId string = nil)
Arguments:
context — a string defining the context in which the fact exists.factName — a string defining the name of the fact.factValue — a value defining the content of the fact.botId — bot identifier. Optional argument.clientId — client identifier. Optional argument.Return value: None.
Examples of use:
fact.save("place", "city", "Boston"); // Fact available to all company bots
fact.save("place", "city", "Boston", null, @clientId); // Fact linked to a client
fact.save("place", "city", "Boston", @botId); // Fact linked to a bot
fact.save("place", "city", "Boston", @botId, @clientId); // Fact linked to a bot and a client
fact.loadRetrieves a fact from the fact database.
Signature: fact.load(context string, factName string, botId string = nil, clientId string = nil) mixed
Arguments:
context — a string defining the context in which the fact exists.factName — a string defining the name of the fact.botId — bot identifier. Optional argument.clientId — client identifier. Optional argument.Return value: The content of the fact.
Examples of use:
fact.save("place", "city", "San Francisco", @botId, @clientId); // Saves the fact with a link to the bot and client
$city = fact.load("place", "city", @botId, @clientId); // Loads the fact into a variable. $city contains "San Francisco"
fact.deleteDeletes a fact from the fact database.
Signature: fact.delete(context string, factName string, botId string = nil, clientId string = nil)
Arguments:
context — a string defining the context in which the fact exists.factName — a string defining the name of the fact.botId — bot identifier. Optional argument.clientId — client identifier. Optional argument.Return value: None.
Usage examples:
fact.save("place", "city", "Los Angeles", @botId, @clientId); // Saves the fact with a link to the bot and client
$city = fact.load("place", "city", @botId, @clientId); // Loads the fact into a variable. $city contains "Los Angeles"
fact.delete("place", "city", @botId, @clientId); // Deletes the fact
$city = fact.load("place", "city", @botId, @clientId); // Attempts to load the deleted fact. Now $city contains null
fact.cleanDeletes facts from the fact database.
Signature: fact.clean(contexts: string | List = nil, factNames: string | List = nil, factValues: any = nil, botIds: string | List = nil, clientIds: string | List = nil)
Arguments:
contexts — a string or list of strings specifying contexts.factNames — a string or list of strings specifying fact names.factValues — a value or list of values specifying fact values.botIds — a string or list of strings specifying bot IDs.clientIds — a string or list of strings specifying client IDs.All arguments are optional. If at least one argument is passed, all facts corresponding to the specified values are deleted.
Deletion occurs separately for each argument. For example, if you pass both factNames and botIds, all facts will be deleted:
factNames.Return value: None.
Example of use:
// Deletes all facts with the context "Location" as well as all facts with the names fact1, fact2, regardless of context or values.
// Deletion occurs for all bots and clients.
fact.clean("Location", ["fact1", "fact2"], [123, 456]);
// Deletes all facts for the specified bot
fact.clean(null, null, null, "fa5d268c-bcc9-4734-a10f-3dfd357764ac");
// Deletes all facts for the current client
fact.clean(null, null, null, null, @clientId);
// Deletes all facts with the names factA and factB, regardless of context or values
fact.clean(null, ["factA", "factB"]);
fact.queryReturns an instance of FactQuery for constructing and executing queries to the fact database.
Signature: fact.query() FactQuery
Arguments: No arguments.
Return value: FactQuery object.
Example of use:
// Add a couple of facts to the database
fact.save("place", "country", "USA");
fact.save("place", "city", "New York");
// Load a list of places into $places, sorted by fact name in descending order
$places = fact.query().
select("name,value").
where("context", "=", "place").
sortBy("-name").
rows();
fact.condReturns an instance of FactQueryCondition for building compound conditions in queries to the fact base.
Signature: fact.cond() FactQueryCondition
Arguments: No arguments.
Return value: FactQueryCondition object.
Example of use:
// Add facts to the database
fact.save("cities", "chicago", "Chicago");
fact.save("cities", "miami", "Miami");
fact.save("cities", "tampa", "Tampa");
fact.save("cities", "seattle", "Seattle");
// Find one city starting with the letter "m" or "t" and not equal to 'Chicago' and 'Seattle'
$city = fact.query()
->select("value")
->where("context", "=", "cities")
->where(
fact.cond()
->where("name", "^@", "m")
->orWhere("name", "^@", "t")
)
->where("name", "not in", ["Chicago", "Seattle"])
->one();