Queries vs live queries

Queries and live queries retrieve asset data. This article explains their functional differences.

Queries in censhare Web allow to get asset data, there are two types of queries:

Query - Returns the requested data
Live Query - Returns the requested data and any updates on these data

JavaScript API

Query

csApiSession.asset.query(query, $scope).then(
    function handleSuccess(result) { ... },
    function handleError(error) { ... }
);

The query returns a promise, in which the first argument is a promise resolve (handleSuccess) function where also the query result is coming. The second parameter is a promise reject (handleError) function, as it always recommended to check for errors.

Live query

csApiSession.asset.liveQuery(query, $scope). then(
    function neverHappens() { ... },
    function handleError() { ... },
    function handleUpdate(result) { ... }
);

The live query also returns a promise. The difference is that in case of the Live Query we will never get a promise resolved but we will receive updates in the third argument function (handleUpdate). The first argument of the live query can be set to null.

Query object

The Query object specifies what kind of data to query and how the data will be represented.

Query parameters

limit - Controlling amount of returned assets
offset - Specifies the start row, adds support for paging
view - Transformation applied to a query result
sortorders - Set order/grouping
condition/and/or/relation - Specify conditions

Example 1

query = {
    limit: 1,
    view: {
        trafo: 'censhare:cs5.query.asset.list',
        condition: [
            { name: 'censhare:asset.id', value: id }
        ]
    }
};

Example 2

query = {
    condition: [
        { name: "censhare:asset.state", value: 1 },
        { name: "censhare:asset.checked_out_by", value: 10, op: "=" }
    ],
    sortorders: {
        order: [
            { by: "censhare:asset.checked_out_date", ascending: false }
        ]
    },
    view: { trafo: "censhare:cs5.query.asset.list" },
    limit: 10
}

A query object can contain the following properties to specify a query: "conditions", "and", "or" and "relation" .

Conditions & "and"/"or" nodes

condition - Can contain one condition or an array of conditions. When an array of conditions is specified it uses the AND logic. For simple conditions an object contains:
- name - To specify the condition parameter name
- value - To specify the condition patameter value

The property condition can have also other parameters provided by censhare search engine.

"condition": [
    {"name": "censhare:function.my-created", "value": 1},
    {"name": "censhare:asset.creation_date","value": "n-00.01.0000-00:00:00", "op": ">"},
    {"name": "censhare:asset.created_by", "value": 10, "op": "=" }
]

"condition":{"name":"censhare:asset.id","value":10000}

and & or: contain arrays of "conditions" and use AND/OR logic

"or": [
    {"condition": [{"name": "censhare:asset.type", "altresults": true, "refid": 16}]},
    {"condition": [{"name": "censhare:rating-average", "altresults": true, "refid": 18}]}
]

Conditions can be added directly to the query object (root node) or to the nodes. When the root node contains any conditions and there are other nodes on that object with different logics and conditions, then this set up will use the AND logic. For example, the object below is equal to condition1 AND condition2 AND condition3 AND (condition4 OR condition5):

{
    "condition": [ condition1, condition2, condition3],
    "or": [condition4, condition5]
}

Relation nodes

The Relation nodes are special nodes to search for the related assets of the target asset(s). The following relation will correspond to the query:

Find all assets where the target asset with ID = 33034 is a child with the relation type 'actual.'

"relation": [{
    "target": {"condition": [{"name":"censhare:asset.id", "value": "33034"}]},
    "direction": "child",
    "type": "actual."
}]

A relation node which contains a relation object or an array of objects:

"relation":{relationObject}
"relation":[
    {relationObject1},
    {relationObject2},
    {relationObject3}
]

A relation node which contains an array of relation objects and implements the AND logic:

"relation": [
    {relationObject1},
    {relationObject2}
]

The illustration above, it's equal to relationObject1 AND relationObject2.

A target can contain a condition/ an array of conditions for a target asset(s)

Grouping

Grouping is applied on the sort-by feature option:

none -> The grouping of values should not take place, even if the feature is configured with grouping.
auto -> The grouping of values is done automatically (depending on the data type of the sort-by feature)
min-values -> Values that are defined at a minimum range, given by the user.
max-values -> Values that are defined at a maximum range, given by the user.

With min and max, you should provide a value and a name for the groups:

<grouping mode="min-values">
 <group name="between 1 and 2" value="1"/><!— 1 is a min value for that group—>
 <group name="higher than 2" value="2"/>
 <group name="all other values (less than 1)"/><—! i.e. all the other values —>
</group>

For max-values, it will be more like this:

<grouping mode="min-values">
 <group name="all lower than 1" value="1"/><!— 1 is a max value for that group —>
 <group name="between 1 and 2" value="2"/>
 <group name="higher than 2"/><— i.e. all the other values —>
</group>

Using the Java-Client to build a query

The Java-Client provides an interface for the "Expert Search", which can help to create complex queries with the censhare Search Engine.

The Java-Client generates XML versions of queries, which could be found in the client logs.

To enable the client logs for queries:

Enable the Admin mode
Enable logs to get the RMI Communication XML-Protocols:
- File > Preferences > Logs > XML-Protocols > RMI Communication
Build a query using the "Asset Search" dialog (use CMD+R for a second try)
Find the query in the Logs' window:

JavaScript API to create queries: csQueryBuilder

The csQueryBuilder provides an API to construct and build queries
It allows to create complex query objects with small amount of code
Existing query objects could be re-engineered and enhanced by additional conditions or filters

To use the csQueryBuilder:

Add the csQueryBuilder as a dependency to a module
Create the csQueryBuilder:

var qb = new csQueryBuilder();

To build a query with the csQueryBuilder:

csApiSession.asset.liveQuery(qb.build()).then(function(result) {
    ...
});

`csQueryBuilder`: example 1

qb.setLimit(100); //set query limit
qb.setOffset(50); // set query offset

qb.view().setTransformation("censhare:cs5.query.asset.list"); //set view XSLT transformation

qb.order().orderBy('censhare:asset.checked_out_date', false); //set order

`csQueryBuilder`: example 2

qb.condition("censhare:in-trash-marker"); //Find all assets with Trash marker

`csQueryBuilder`: example 3

Find all assets witch are censhare:availability-calendars for the current asset(id = assetId) and have type module.availability-calendar.*":

andNode = qb.and(); //create AND node
relationNode = andNode.relation("feature-reverse", "censhare:availability-calendar");
relationNode.condition("censhare:asset.id", assetId);
andNode.condition("censhare:asset.type", "module.availability-calendar.*");

Advantages and disadvantages

+

Easy way to get assets data
The live Query allows to get updates
Asset behaviors are delivered as a part of the asset
The result items are compatible with the item-renderer

-

A big amount of Live Queries kill the performance
It takes some time when a big amount of data is being queried
All the logic is on the Front-End when some specific representation is required

Page tree