XML query language description

In this article, we will describe some of the most basic elements and their combinations when working with the XML query language in censhare.

Constructing and Testing

XML Queries can be easily constructed in the “Expert” tab which exists in the Search window on the Java Client. By setting the Java client into the “Admin mode” and enabling XML logging, you can easily see all the constructed query in XML form.
Queries can additionally be constructed and evaluated within the “XML Query Test” window, which is available on the Admin menu of the Java client, after enabling the client in Admin mode.

Query node

A query begins with the ‘query’ node, where the atrribute type defines the main table from which we will query the desired data:

Query operators

A query can have many conditions which are being separated by different operators (and, or, not).
The and operator is used as default operator when a query contains multiple conditions and without having another operator specified (or/not).

• Example: Using the default and operator:

  < query type = "asset" >    < and >      < condition name = "censhare:asset.name" op = "like" value = "1st*" />      < condition name = "censhare:asset.modified_date" op = "&gt;" value = "23/04/2016" />    </ and > </ query >

• Example: Using operators or and not:

  < query type = "asset" >    < or >      < and >          < condition name = "censhare:asset.name" op = "like" value = "ab*" />          < condition name = "censhare:asset.lastmodified" op = "&gt;" value = "23/04/2016" />      </ and >      < and >          < condition name = "censhare:asset.name" op = "like" value = "bc*" />          < condition name = "censhare:asset.lastmodified" op = "&gt;" value = "23/04/2016" />      </ and >    </ or >    < not >      < condition name = "censhare:asset.name" op = "like" value = "ab" />    </ not > </ query >

Operators in conditions

Conditions are consisted by the following attributes:

• name: The id of the feature to which the condition is referring to
• op: The operator that is applied to the condition.
  • < : Less than, translated to < in xml
  • <= : Less than or equal to, translated to <= in xml
  • > : Greater than, translated to > in xml
  • >= : Greater than or equal to, translated to >= in xml
  • != : Not equal to
  • = : Equal to
  • LIKE
  • IN : Uses implicit OR between different given values
  • ALL : Behaves like operator IN, with an implicit AND instead
  • ISNULL
  • NOTNULL
• value: The value of the feature that our condition is based on. This attribute is not required for operators ISNULL and NOTNULL.
• sepchar: (optional) This attribute is used to define a separator character, when the attribute value contains multiple values which are separated by a particular character, and it is only applicable for the IN and ALL operators.

The asterisk * character can be used as a wildcard in the value criteria. Please note that when an operator is not given, operator = is considered as the default one. However, if a value contains wildcards, the operator LIKE will be assumed as default instead.

• Example: Operator LIKE and with wildcard value

  < condition name = "censhare:asset.name" op = "LIKE" value = "ab*" /> <!-- Starts with 'ab'--> < condition name = "censhare:asset.name" op = "LIKE" value = "*ab*" /> <!-- Contains the letters 'ab'--> < condition name = "censhare:asset.name" op = "LIKE" value = "*ab" /> <!-- Ends with 'ab'-->

• Example: Operators ALL & IN:

  < condition name = "censhare:keyword" op = "ALL" value = "keyword1,keyword2" sepchar = "," /> <!-- assets must have keyword1 AND keyword2 --> < condition name = "censhare:keyword" op = "IN" value = "keyword1,keyword2" sepchar = "," /> <!-- assets must have any of the keywords (implicit OR) -->

• Example: Operator ISNULL and NOTNULL

  < condition name = "censhare:asset.module" op = "isnull" /> <!-- not a module --> < condition name = "censhare:approved-date" op = "notnull" /> <!-- approved date not null -->

• Example: Operators >, >= , < and <=

  < condition name = "censhare:asset.modified_date" op = "<" value = "2017-05-26T09:26:00Z" name2 = "censhare:asset.modified_date" op2=">" value2="2017-04-26T09:26:00Z"/> < condition name = "censhare:function.radius.coord" op=">" value="100" value2="52.401" value3="9.722"/>  <!-- range of 100km around location -->

  Note! censhare:function.radius.coord is a special query that searches for area of value in metres around the coordinates. This query can work with the following two search patterns:

  1. Searching with 3 parameters: value is the radius, value2 and value3 are latitude and longitude
  2. Searching with 4 parameters: value, value2, value3, value4 are latitude1, latitude2, longitude1, longitude2 of the corners of the area

• Example: Nested features condition

  < condition name = "tracker.type" value = "internal" >        <!-- nested features -->    < condition name = "tracker.text.comment" value = "bla" />    < condition name = "tracker.timestamp" value = "2011.01.01" value2 = "2011.03.31" />     < or >        < condition name = "tracker.party" value = "170" />        < condition name = "tracker.party" value = "180" />    </ or > </ condition >

Sorting and grouping

• Results can be sorted by setting the order as ascending or descending. It is possible to have multiple order elements as primary, secondary sorting.

  < sortorders >     < order by = "censhare:asset.name" descending = "false" />     < order by = "censhare:asset.modified-at" ascending = "true" /> </ sortorders >

• Results can be additionally grouped, based on a particular feature

  < group-by >    < column name = "censhare:asset.type" />    < having > <!-- SQL only -->        < condition name = "" >    </ having > </ group-by >

Relations

Relations can be specified by their target and type:

• target : Options - any, parent, child, feature and feature-reverse
• type: These are some of the main type options (a full list of all type options can be found in the “Expert” tab of the search window)
  • Assignment - user.*
  • Placement - actual.*
  • Planning - target.*
  • Variant - variant.*

  In relation queries, the outer enclosing <and> conditions are equivalent to <source> conditions, which describe the return values. <target> conditions describe values which are reached by the relations.

  < relation target = "child" type = "user.*" >      < source >        < condition />      </ source >      < target >        < condition />      </ target > </ relation >

• Example: Parent relation

  < relation target = "parent" type = "user.*" >    < target >      < limit start = "0" end = "100" >   <!-- limit to the newest 100 targets -->          < condition name = "censhare:asset.type" value = "group.*" />          < condition name = "censhare:output-channel" value = "root.web.*" />          < sortorders >              < order by = "censhare:asset.modified-at" ascending = "false" />          </ sortorders >      </ limit >    </ target > </ relation >

• Example: Asset reference feature relation

  < relation target = "feature" type = "censhare:keyword.external.ref" >    < target >        < condition name = "censhare:asset.type" value = "module.keyword." />        < condition name = "censhare:keyword.external" value = "ab" />        < condition name = "censhare:keyword.external.key" value = "0236535838632" />    </ target > </ relation >

Full text search

Full text searchable features can also be added in xml an query inside a <term> element: