XML Queries

From Sense/Net 6.0 Wiki

Jump to: navigation, search

Queries can be created either via the API or - the simpler way - wrapped in XML. The XML form is the format the ContentQuery portlet uses as well.

Contents

[edit] Syntax

When creating an XML query the structure of the query has to be the following: 

<?xml version="1.0" encoding="utf-16"?>
<SearchExpression xmlns="http://schemas.sensenet.hu/SenseNet/ContentRepository/SearchExpression">
  <And>
  {Query expressions}
  </And>
  {Paging and ordering expressions}
</SearchExpression>

[edit] Expression Types

[edit] Query Expressions

Within an XML Query the following expressions can be used:

  • Type expressions specifying the type of a node
  • String expressions specifying criteria for fields that have String RepositoryDataType (e.g. ShortText and LongText fields)
  • Int expressions specifying a criteria for fields which are mapped to Int RepositoryDataType (e.g. Boolean and [[Integer fields)
  • DateTime expressions specifying a criteria for fields which are mapped to Int DateTime (e.g. DateTime field)
  • Reference expressions specifying a criteria for fields which are mapped to Reference RepositoryDataTypes (e.g. Reference field)
  • Currency expressions specifying a criteria for fields which are mapped to Currency RepositoryDataTypes (e.g. Number field)

[edit] Logical Expressions

Within an XML Query three logical operators can be used on expressions. These are:

  • And operator (<And>...</And>)
  • Or operator (<Or>...</Or>)
  • Not operator (<Not>...</Not>)

Operators can be nested within one another. Top level operator is always And.

[edit] Paging and Ordering Expressions

After the <And>...</And> surrounded query expressions additional expressions can be defined. These are the following:

  • Orders - custom ordering can be defined for the query
  • Top - the query can be instructed to only return the first few elements
  • Page - paging can be defined

[edit] Query Expressions

[edit] Type Expressions

A type expression defines a criteria for a node to be matched.

Type expressions have 2 attributes:

  • nodeType="{NodeTypeName}" - required, specifies the type of the node that search will be narrowed to. All content types registered in the system can be used.
  • exactMatch="{yes|no}" - not required

Examples

An expression narrowing to the Page type: 

<Type nodeType="Page" />

An expression narrowing to the Folder types and all descendants of a folder (note that setting exactMatch="yes" would result in narrowing only to folders) 

<Type nodeType="Folder" exactMatch="no" />

[edit] String Expressions

String expressions specifying criteria for fields that have String RepositoryDataType.

String expressions have 2 attributes (and a value parameter):

  • op - the operation to be performed on the string, e.g. exact match, not equal
  • property - the name of the field on which the operation should be executed

Possible values of the op parameter

  • Contains
  • EndsWith
  • Equal
  • GreaterThan
  • GreaterThanOrEqual
  • LessThan
  • LessThanOrEqual
  • NotEqual
  • StartsWith

Built-in string fields The following fields can be used by default in string expressions:

  • Path
  • Name

Examples

  • Find items within the /Root/IMS path 
<String op="StartsWith" property="Path" >/Root/IMS</String>
  • Find items having the name "George": 
<String op="Equal" property="Name" >George</String>
  • Find items within the /Root/IMS path which do not have the Administrator name: 
<And>
   <String op="StartsWith" property="Path">/Root/IMS</String>
   <String op="NotEqual" property="Name">Administrator</String>
</And>

[edit] Int Expressions

Int expressions have two attributes (and a value parameter):

  • op - the operation to be performed on the value
  • property - the name of the field on which the operation should be executed
  • value of the expression has to be an integer to be valid

Possible values of the op parameter

  • Equal
  • GreaterThan
  • GreaterThanOrEqual
  • LessThan
  • LessThanOrEqual
  • NotEqual

Built-in Int fields The following fields can be used by default in int expressions:

  • Id
  • Locked
  • IsDeleted
  • ParentId
  • MajorVersion
  • MinorVersion
  • CreatedById
  • ModifiedById
  • LockedById

Examples

Contents that are locked: 

<Int op="Equal" property="Locked">1</Int>

[edit] Currency Expressions

Currency expressions behave the same way as Int expressions. The only difference is that the value of the expression has to be a float number.

Built-in Currency fields There are no built-in curency fields in the system. You can only use this expression on fields that you have added.

Examples

Assuming some contents has a Price field with the Number data type the following expression would collect the ones with the price lower than 100: 

<Currency op="LessThan" property="Price">100</Currency>

[edit] DateTime Expressions

DateTime expressions have two attributes (and a value parameter):

  • op - the operation to be performed on the value
  • property - the name of the field on which the operation should be executed
  • value of the expression has to be a date to be valid. The date is accepted only in XML standard formats (yyyy-MM-dd, yyyy-MM-ddTHH:mm:ss).

Possible values of the op parameter are the same as in the case of the Int expression:

  • Equal
  • GreaterThan
  • GreaterThanOrEqual
  • LessThan
  • LessThanOrEqual
  • NotEqual

Built-in DateTime fields The following fields can be used by default in int expressions:

  • CreationDate
  • ModificationDate
  • LastLockUpdate
  • LockDate
[edit] Dynamic DateTime Values

Dynamic date values (compared to the current date and time) can be specified with the following values:

  • <now/> - Current date and time
  • <thisyear/> - 1st January of current year, 00:00:00am.
  • <thismonth/> - First day of current month, 00:00:00am.
  • <thisweek/> - First day of current week, 00:00:00am.
  • <thisday/> - Today, 00:00:00am.
  • <thishour/> - This hour, 0 minutes, 0 seconds
  • <thisminute/> - This minute, 0 seconds
  • <yesterday/> - Yesterday, 00:00:00am.
  • <tomorrow/> - Tomorrow, 00:00:00am.

Note that dynamic date values can also be assigned via JScript expressions within queries as well, however this method is deprecated.

Examples

Contents with ValidTill property greater than current date and time 

<DateTime op="GreaterThanOrEqual" property="ValidTill"><now/></DateTime>

Contents that have been modified this month 

<DateTime op="GreaterThanOrEqual" property="ModificationDate"><thismonth/></DateTime>

Contents that have been created after 1st January, 2008 

<DateTime op="GreaterThanOrEqual" property="CreationDate">2008-01-01</DateTime>

Contents that have been created after 12.05pm, 1st January, 2008 

<DateTime op="GreaterThanOrEqual" property="CreationDate">2008-01-01T12:05:00</DateTime>

Contents that have been created after 6.05pm, 1st January, 2008 

<DateTime op="GreaterThanOrEqual" property="CreationDate">2008-01-01T18:05:00</DateTime>

Contents that have been modified within the last two days (see using JScript expressions within queries for explanation) 

<DateTime op="GreaterThanOrEqual" property="ModificationDate">[jScript]DateTime.Now.AddDays(-1).ToString("yyyy-MM-dd")[/jScript]</DateTime>

[edit] Reference Expressions

Reference expressions define a match criteria for a reference property.

Reference expressions have two attributes:

  • property - the name of the field on which the operation should be executed
  • referenceNodeId - optional, the ID of the node to be matched. A nested expression can be used instead of this attribute.

Expressions can be nested into Reference expressions defining the referenced nodes.

Note that usage of referenceNodeId should be aboided as it makes administration difficult. Nested Path expressions are recommended to use instead.

Also note that performance of these expressions are slower than all other expressions therefore should only be used when really necessary.

Built-in reference fields The following fields can be used by default in reference expressions:

  • Parent
  • CreatedBy
  • ModifiedBy
  • LockedBy

Examples

Contents created by Administrator: 3 different examples (NodeId of Administrator is 0) 

<Reference property="CreatedBy">
   <String op="Equal" property="Path">/Root/IMS/SNPE/Portal/Administrator</String>
</Reference>
<Reference property="CreatedBy" referencedNodeId="0" />
<Reference property="CreatedBy">
   <Int op="Equal" property="Id">0</Int>
</Reference>

Contents directly under /Root 

<Reference property="CreatedBy">
   <String op="Equal" property="Parent">/Root</String>
</Reference>

[edit] Logical Expressions

[edit] And Expressions

And expressions represent logical and relation within the members.

Examples

Retreiving contents with Page type within the /Root/YourIntranet path. 

<And>
    <String op="StartsWith" property="Path">/Root/YourIntranet</String>
    <Type nodeType="Page"/>
</And>

[edit] Or Expressions

Or expressions represent logical or relation within the members.

Examples Retreiving contents with Page or File type within the /Root/YourIntranet path. Note that this is an example of nesting as well. 

<And>
    <String op="StartsWith" property="Path">/Root/YourIntranet</String>
    <Or>
       <Type nodeType="Page"/>
       <Type nodeType="Files"/>
    </Or>
</And>

[edit] Not Expressions

Or expressions represent logical negation relation within the members.

Examples Retreiving contents with /Root/YourIntranet path that are neither pages nor files. Note that this is an example of nesting as well. 

<And>
    <String op="StartsWith" property="Path">/Root/YourIntranet</String>
    <Not>
       <Type nodeType="Page"/>
    </Not>
    <Not>
       <Type nodeType="Files"/>
    </Not>
</And>

[edit] Paging and Ordering Expressions

[edit] Order Expressions

Nested within an <Orders>...</Orders> parent tag various Order expressions can be defined. Orders will be evaluated one after another.

An Order expression has only two attributes:

  • property - specifies the field on which ordering will be made
  • direction - can be asc or desc. Specifies ordering direction. If the attribute is not passed the default value is asc.

Examples Order the results by ascending name: 

<Orders>
   <Order property="Name" />
</Orders>

Order the results by whether they are locked or not (have the ones locked first, so ordering will be done descending) and within these two groups order them by descending last modification date: 

<Orders>
   <Order property="Locked" direction="desc" />
   <Order property="ModificationDate" direction="desc" />
</Orders>


[edit] Top Expression

By adding the <Top>{number}</Top> expression after the <And>...</And> surrounded query expressions the first {number} results are returned only.

Examples

To return the first 10 results: 

<Top>10</Top>

[edit] Paging Expression

Paging can be defined within a query with the Page expression. The Page expression has two attributes:

  • startIndex - from which result the query will return elements. Starts from 1 (not 0!).
  • pageSize - how many elements should be returned

Note that unlike its name suggesting within the paging expression not page numbers are defined but a only a start index where to start returning the results.

Examples Return the first 10 elements of the query (same as <Top>10</Top> would be): 

<Page startIndex="1" pageSize="10">

Return the second page of the results where a page size is 10 (that means returning elements 11-20): 

<Page startIndex="11" pageSize="10">

Return 10 elements but not the first (that is return 10 elements starting from the second): 

<Page startIndex="2" pageSize="10">

[edit] Examples

Retreiving the latest created WebContentDemo located within the /Root/YourIntranet folder: 

<?xml version="1.0" encoding="utf-8"?>
<SearchExpression xmlns="http://schemas.sensenet.hu/SenseNet/ContentRepository/SearchExpression">
  <And>
    <String op="StartsWith" property="Path">/Root/YourContents</String>
    <Type nodeType="WebContentDemo" />
  </And>
  <Orders>
      <Order property="CreationDate" direction="asc"/>
   </Orders>
   <Top>1</Top>
</SearchExpression>

Retreiving all WebContentDemos that are valid at the moment located within the /Root/YourIntranet folder. Note that when specifying the relation to the current date the context is inverse of usual because we are specifying criteria from the view of the content itself. 

<?xml version="1.0" encoding="utf-8"?>
<SearchExpression xmlns="http://schemas.sensenet.hu/SenseNet/ContentRepository/SearchExpression">
  <And>
    <String op="StartsWith" property="Path">/Root/YourContents</String>
    <Type nodeType="WebContentDemo" />
    <DateTime op="LessThanOrEqual" property="ValidFrom"><now/></DateTime>
    <DateTime op="GreaterThanOrEqual" property="ValidTill"><now/></DateTime>
  </And>
  <Orders>
      <Order property="Name" direction="asc"/>
   </Orders>
</SearchExpression>

Retrieving all WebContentDemos that are valid on 1st May 2005 4pm: 

<?xml version="1.0" encoding="utf-8"?>
<SearchExpression xmlns="http://schemas.sensenet.hu/SenseNet/ContentRepository/SearchExpression">
  <And>
    <String op="StartsWith" property="Path">/Root/YourContents</String>
    <Type nodeType="WebContentDemo" />
    <DateTime op="LessThanOrEqual" property="ValidFrom">2009-05-01T16:00:00</DateTime>
    <DateTime op="GreaterThanOrEqual" property="ValidTill">2009-05-01T16:00:00</DateTime>
  </And>
  <Orders>
      <Order property="Name" direction="asc"/>
   </Orders>
</SearchExpression>

Retreiving first 20 Pages locked within the /Root/YourIntranet folder, ordered by ascending name (this query can be used within a SmartFolder) 

<?xml version="1.0" encoding="utf-8"?>
<SearchExpression xmlns="http://schemas.sensenet.hu/SenseNet/ContentRepository/SearchExpression">
   <And>
      <String op="StartsWith" property="Path">/Root/YourIntranet</String>
      <Int op="Equal" property="Locked">1</Int>
      <Type nodeType="Page"/>
   </And>
   <Orders>
      <Order property="Name" direction="asc"/>
   </Orders>
   <Top>20</Top>
</SearchExpression>

[edit] Related Articles

Retrieved from "http://wiki.sensenet.com/index.php?title=XML_Queries"
Personal tools