¶ Specialized Direct Inject Function
TiQL query, aka the query language of thing'in, is a graph oriented language mainly based on graph pattern. This language is defined to be portable whatever is the underlying graph database. Nevertheless, to be executed on this database, TiQL is translated to the language of the database.
Both the genericity and the translation lead to a not fully optimized database query.
Then to allow a better usage of the underlying database, we introduce the Specialized Direct Inject Functions (SDIF), that allows the administrator to define their own queries, written in the targetted query language and returning results (after process) as avatars or JSON, JSON_ARRAY, String, Number, Boolean or array of that type.
The idea is to avoid translation and then have a better performance due to : (1) no lost time for translation, (2) give optimized requests for the underlying DB.
It is important to note that the security is preserved. The returned avatars respect the restrictions put on the requester and the rights defined by the ACL.
Be careful, the SDIF allow to use the full potential of the database, that means a better performance but with bad intentions, very malicious queries could be executed. So, it is the reason why we prefer to limit the creation of the SDIF to administrator. Their usages could be done by any users.
Thanks to these SDIF, it is also possible to return results other than avatars, for example a value of an avatar property, or the count or mean of a result set.
¶ Definition
A SDIF is a function, then it has a name, a result type and parameters:
sdif_name(type param1, type param2, ...) -> type
The format of the json is declared as :
{
uuid: string // uuid of the sdif
params [ // list of params of the sdif
{ // a param
name: string // name of the param
type: string // type of the param
// value in Enum: [ NUMBER, NUMBER_LIST, STRING, STRING_LIST, BOOLEAN, BOOLEAN_LIST ]
desc: string // description of the param
}]
name: string // name of the sdif
query: string // query of the sdif
type: string // result type of the sdif
// value in [ AVATAR, AVATAR_LIST, NUMBER, NUMBER_LIST, STRING, STRING_LIST, BOOLEAN, BOOLEAN_LIST ]
desc: string // description of the sdif
}
¶ Types
¶ Basic types
NUMBER : respect the Json number type, could be any of: byte, integer, long, float, double
STRING : Json string type
BOOLEAN : Json boolean type (true or false)
JSON : Json object
JSON_ARRAY : json array
¶ Avatar type (only for results)
Avatar type is a struct based on the current definition of avatar as used when we create or read/find avatars. This type could be convert in JSON, Ziggy-Json or any RDF types as defined in avatar endpoint API.
¶ List types
Any basic type could be used as item of a homogeneous list (i.e. each item has the same type)
AVATAR_LIST : list of avatars (only for result of the query)
NUMBER_LIST : list of numbers
STRING_LIST : list of strings
BOOLEAN_LIST : list of booleans
When the result type is AVATAR_LIST, from the API, like "find" resource, the output data can be converted in different formats and it can be paginated.
¶ Example
SDIF:
{
"uuid": "xxxxxxxxxxxxxxxxxxxxxxxxx",
"name": "count_domain_avatars",
"desc": "count the avatars in a given domain",
"query": "WITH avatar FOR av IN avatar FILTER av.domain == @domain COLLECT WITH COUNT INTO length RETURN length",
"type": "NUMBER",
"params": [
{
"name": "domain",
"type": "STRING",
"desc": "name of the domain"
}
]
}
Example of execution
https://coreapi.thinginthefuture.com/sdifs/xxxxxxxxxxxxxxxxxxxxxxxxx/exec
parameters:
{
"params": [
{
"name": "domain",
"value": "http://domainname/"
}
]
}
result:
{
"value": 25
}