Query <T, R>
Index
Constructors
constructor
Type parameters
- T: CloudObject<T>
- R
Returns Query<T, R>
Methods
andReturn
Add the current working set of nodes to the result.
Example: Query returning the instances of a model and the model itself
Query
.from(myModelTag).andReturn()
.follow(CloudObject.modelRel.getInverse()).andReturn()
.execute();The result tuples are [modelCloudObject, instance1], [modelCloudObject, instance2], …
Returns Query<T, R extends never ? T : R extends CloudObject[] ? [...R[], T] : [R, T]>
a new query object with the current level flagged to be returned.
back
The Query.back() function is used to move the cursor of a query backwards to the previous level. This allows the query to start from the place where it was before a Query.follow() call, but with a different relation. The
times
parameter is optional and specifies the number of steps to go back. If hops is not specified, the default value of 1 is used. If a value <= 0 is specified, the output query is the same as the input query.Example: const people = [ { name: “Alice”, children: [“Bob”, “Carol”], siblings: [“David”] }, { name: “Bob”, children: [“Emily”], siblings: [“Alice”, “Carol”, “David”] }, { name: “Carol”, children: [“Frank”], siblings: [“Alice”, “Bob”, “David”] }, { name: “David”, children: [“Greg”], siblings: [“Alice”, “Bob”, “Carol”] }, { name: “Emily”, children: [], siblings: [] }, { name: “Frank”, children: [], siblings: [] }, { name: “Greg”, children: [], siblings: [] } ];
// Create a new query starting from Alice const aliceQuery = Query.from(“Alice”);
// Follow the “children” relation to get Alice’s children (Bob, Carol) const aliceChildrenQuery = aliceQuery.follow(“children”).andReturn();
// Go back to the previous level and follow the “siblings” relation to get Alice’s siblings (David) const aliceSiblingsQuery = aliceChildrenQuery.back().follow(“siblings”).andReturn();
// Execute the query, the output is: Output: [ { sibling: ‘David’, child: ‘Bob’ }, { sibling: ‘David’, child: ‘Carol’ } ]
Parameters
optionaltimes: number
Returns Query<CloudObject, R>
cast
Cast the type of the instances in the current working set of nodes
Type parameters
- S: CloudObject<S>
Parameters
type: Class<S>
cast type for
CloudObjects
Returns Query<S, R>
the
execute
Execute the query asynchronously on the datacloud and deletes it afterwards. In other words, one cannot call execute twice on the same
Query
.Parameters
context: Context
context in which the query must be executed. As this is an asynchronous operation, one has to provide a context that won’t be destroyed before the query has a result.
Returns Promise<QueryResult<R extends never ? T : R extends CloudObject | CloudObject[] ? R : never>>
promise resolving to query result or failing otherwise.
executeFromCache
Execute synchronously the query on the local datacloud cache.
executeFromCache
can only be called once on a givenQuery
.Returns QueryResult<R extends never ? T : R extends CloudObject | CloudObject[] ? R : never>
query result of the execution on the local cache
filter
follow
Instruct the query to follow a specified relation. This does not add any key-value pair to the result. (see Query.andReturn). This operation defines a new step in the path defined by our graph query.
Example: Find the model of a single object.
Query.from(myTag).follow(CloudObject.modelRel).andReturn()
Type parameters
- D: CloudObject<D>
Parameters
relation: Relation<T, D>
relation to follow, specifies type and direction
optionaloptional: boolean
whether or not the relation creates a mandatory path in the graph to be part of the result.
Returns Query<D, R>
a new query object
followRecursively
Follow a relation recursively, see Query.follow. The relation that is followed is automatically recursively followed. All nodes that are recursively followed are part of the same step in the path defined by this graph query.
Type parameters
- D: CloudObject<D>
Parameters
relation: Relation<T, D>
relation to follow recursively, specifies type and direction
optionalincludeSelf: boolean
if a starting node includes itself when the relation loops on itself
optionaloptional: boolean
whether or not the relation creates a mandatory path in the graph to be part of the result.
Returns Query<D, R>
a new query object
limit
Set the maximum number of tuples the executed query will return with an optional offset.
Only the last call to limit matters.
Example :
const queryLimited = query.limit(50).follow(myRel2).limit(100, 200).follow(myRel1);
// is equivalent to
const queryLimited2 = query.follow(myRel2).follow(myRel1).limit(100, 200);queryLimited
, when executed, will return at most the 200th to the 299th (included) results.Parameters
max: number
maximum number of tuple to fetch from the final result
optionaloffset: number
number of skipped tuples for the final result
Returns Query<T, R>
new query with limit operation
observe
Get an observable to the current value of the QueryResult for this Query instance.
The observable gets the new value each time data modification in the datacloud changes the result of the query.
The observable gets completed automatically once the specified context is cleared.
Parameters
Returns Observable<QueryResult<R extends never ? T : R extends CloudObject | CloudObject[] ? R : never>>
Observable of QueryResult values
parse
Returns RootQueryPart
the query transformed as a tree of QueryPart. To be used by Data Source.
sortBy
Sort the result tuples according to a property of a data type with a specified order. * For the sortBy operator to be properly defined, the following must be true:
- the property is defined on the instances that will be used for sorting.
- the instances on which the sorting property is defined must be part of the result,
i.e.,
andReturn()
has been called beforesortBy()
.
Only the last call to
sortBy
matters as it will be the last comparator set on the query. You should remove previous calls tosortBy
for the same query.Example :
const sortQuery = Query
.fromInstances(myModel1).andReturn()
.sortBy(nameProperty)
.follow(rel1).andReturn()
.execute();This query fetches instances of a model, flags them as first element of result tuples. Then the query follows a relation to other instances and return them as second element of the result tuples.
sortBy
will sort the results according to thenameProperty
of the first element in the result tuples in ascending order.Parameters
property: Property<any>
the property used for sorting
optionalorder: Order
optional Order.ASC (default) or Order.DESC order
Returns Query<T, R>
new query with sort operation
staticfollowRule
Create a query starting from a specific root instance, then following relations based on a rule constraint.
Type parameters
- T: Tag
Parameters
ctx: Context
Context in which the Query is observed
root: T
Starting point of the query. See
root
of RootQueryPartrule: FollowRule
Discriminate which relations to follow
optionalsource: string
The tag of the source responsible for executing the query
Returns Observable<QueryResult<T extends CloudObject ? T : CloudObject>>
staticfrom
Create a query starting from the
CloudObject
specified tag. ThatCloudObject
must already exist in the local database. In case you have the tag as astring
and need to get the object from a remote database, use Query.fromTag instead.Type parameters
- T: Tag
Parameters
tag: T
tag of the
CloudObject
the query is starting fromoptionalsource: string
optional source of the data to answer the query
Returns Query<T extends CloudObject ? T : CloudObject, never>
an empty Query whose starting point is defined by a single
CloudObject
staticfromTag
Create a query starting from the
CloudObject
specified tag. The difference with Query.from method is that you specify the data type of the Tag: this allows to execute queries with a tag that is unknown by the local database, on the right remote database.Type parameters
- T: CloudObject<T>
Parameters
tag: string
tag of the
CloudObject
the query is starting fromdataType: Tag | Class<T>
data type of the
tag
CloudObject
.optionalsource: string
optional source of the data to answer the query
Returns Query<T, never>
an empty Query whose starting point is defined by a single
CloudObject
staticinstancesOf
Create a query starting from the instances of the specified model. By default, it does include the instances of the models that inherit from the given one.
Type parameters
- T: Tag
Parameters
model: Tag | Class<T>
tag/class of the model to find the instances of
optionalincludeInheritance: boolean
if set to false, the result will not include instances of models that inherit from the given model.
optionalsource: string
optional source of the data to answer the query A source can be the orchestrator (‘server’), local (‘self’) or an external data source (Tag of a
DBConnectorTag
)
Returns Query<T extends CloudObject ? T : CloudObject, never>
a new query object starting from model instances
A Query is an immutable object used to build queries on the datacloud. It is a graph query builder. It starts from an
origin
Tag (typically, theTag
of a data type or of an instance). From there, it can follow relations between data types and filter results.Example:
origin --a--> X --b--> Y --c--> Z
Example:
This will return a Promise of a QueryResult whose values are of type X:
Promise<QueryResult<X>>
.A query defines a starting working set of nodes and operations that will mutate it. From our example,the working set is first the
origin
graph node. Then thefollow
operations create a new working set only containing the nodes related to the origin through relationa
.Multiple relations can be followed at once to create the equivalent of JOIN operations in relational databases.
The next operation defines a working set containing the nodes related through relation
b
to nodes that are related through relationa
to the origin. A similar operation is defined for relationc
. At each level, “andReturn()” method can be called to add the current level to the result. This will return a Promise of a QueryResult whose values are of type [X, Z]:Promise<QueryResult<[X, Z]>>
.Out of the 4 working sets created, only the second and fourth are flagged to be returned and part of the result. But the operations in the middle impact this result: e.g., all returned tuples (t1, t2) are object that have an intermediate
i
of type Y. such thatt1 --b-> i --c-> t2
but thei
was not flagged to be returned.Queries define a path from a starting point following a specific list of relations. As explained with our example, only nodes part of a full path can be returned.
A query can be executed with 3 different ways: