Return to doc.sitecore.com

Valid for Sitecore 6.0.0, 5.3.2
3.  Sitecore Query Syntax
Prev

This article describes the Sitecore Query syntax.

Sitecore Query uses a path notation, similar to XPath expressions, for addressing Items of a Sitecore content tree. The expression is evaluated to yield an Item set. In addition, a query expression may have predicates (filter expressions). For example, the expression Entry[@Title = 'Welcome to Sitecore'] refers to the Entry Items whose Title field is set to "Welcome to Sitecore".

Below are some common query expressions:  

Notes :

    Item names in the path expression are not case sensitive (/sitecore/content/Home/Products has the same result as /sitecore/content/home/products). 

    You can use escaped double quotes instead of single quotes. This is especially useful in case a search criterion contains single quotes. For example:
    "/sitecore/content//*[@title=\"Simple'value\"]"

    Items with dashes in names (“-”) should be included in “#” symbols. Please use such syntax: /sitecore/content/Home/#About-us#. Otherwise you may get the following error: Invalid lookup source "/sitecore/content/TestSiteB/Home/About-us": End of string expected at position 38. Also, an item name should be included in “#” symbols if it contains “and” or “or” word and is used before “//*” symbols. For example: "/sitecore/content/Home/#news and events#//*". Item names that start with one or more digits should also be included in “#” symbols. For example: "/sitecore/content/Home/News/#2012#/January".

We will use a sample package to illustrate the explanations below.

Download the sample package . Note: we recommend that you install the package on a clean Sitecore installation.

The package contains a content tree shown in the picture below:

  

The package also includes the following templates: Product, Shape and Query Test.

The Query Test Item is based on the Query Test template which contains a multilist field. This field is used to test the queries given in the present article.

3.1.  Basic Query Expressions

Below is a list of basic expressions used in the query paths:

Expression Description
/ Selects from the root Item
// Selects Items from all descendants of the context Item that match the selection
.. Selects the parent of the current Item
@ Selects fields (please refer to the Attributes section for details)
@@ Selects attributes (please refer to the Attributes section for details)

 

Examples:   

The pipe (“|”) separator is used to select several paths in one expression. For instance:

query:/sitecore/content/Home/Products|/sitecore/content/Home//Circle/..|/sitecore/content/Home//Circle

Output:

Predicates are used to find a specific Item or an Item that contains a specific value.

Predicates are always embedded in square brackets. Below is the description of two groups of predicates available in Sitecore – Attributes and Functions.

3.2.  Attributes

Attribute: [@fileldname]

Description: Item field name.

Query Example:
query:/sitecore/content/Home/*[@Title = 'Welcome to Sitecore']

Returns Items which have the value of the field 'Title' set to 'Welcome to Sitecore'. The search is performed among the children of the Home Item.

 

Note : Use the database field values when using fields in your query expressions. Read more about how field values are stored in the database.

query:/sitecore/content/Home/Products/Hammer[@Available = '1']

Returns all Hammer named Items which have the value of the checkbox field 'Available' set to '1'.

 

Attribute: [@@name]

Description: Item name. Case sensitive.

Query Example:
query:/sitecore/content/Home/Products/*[@@name = 'Hammer']

The search is performed among the children of the Products Item.

 

Attribute: [@@key]

Description: Item name lowercased. For example: [@@key = 'item'] will match iTEm and Item. Note: the key must be in lowercase.

Query Example:
query:/sitecore/content/Home/Products/*[@@key = 'hammer']

The search is performed among the children of the Products Item.

 

Attribute: [@@templateid]

Description: Item Template ID.

Query Example:

query:/sitecore/content/Home//*[@@templateid = '{F348C2A0-73B8-4AF4-BD9E-2C5901908369}']

Returns all descendants of the Home Item based on the template with the mentioned ID.


  

Attribute: [@@templatename]

Description: Item Template name. The value is case sensitive.

Query Example:

query:/sitecore/content/Home//*[@@templatename = 'Shape']

Returns all descendants of the Home Item based on the Shape template.


  

Attribute: [@@templatekey]

Description: The template name in lowercase.

Query Example:

query:/sitecore/content/Home//*[@@templatekey = 'product']

Returns all descendants of the Home Item based on the Product template.

 
 

Attribute: [@@id]

Description: Item ID.

Query Example:

query://*[@@id = '{787EE6C5-0885-495D-855E-1D129C643E55}']

Searches through the entire content tree and returns an Item with the mentioned ID.

 

Other Examples:

Query expressions may be quite complex:

query:/sitecore/content/Home//*[@@id='{D394CCA7-C88B-418C-8B2B-AA97AA52EE14}' or @@key = 'stylish bag' or @@name = 'Hammer']

Result:

 

query:/sitecore/content/Home//*[@Text='Bargain Price' and @Available='1']

Result:

3.3.  Functions

Sitecore query functions make it possible to perform Boolean operations with Items in query expressions and apply extra conditions to the query.

Function: contains(s1:string, s2:string):bool

Description: Indicates whether s1 contains substring s2. The comparison is case sensitive.

Query Example:

query:/sitecore/content/Home/Products/*[contains(@Text, 'Bargain')]

Returns child Items of the Products Item which contain 'Bargain' fragment in the Text field.

Function: startswith(s1:string,s2:string):bool

Description: Indicates whether s1 starts with substring s2. The comparison is case sensitive.

Query Example:

query:/sitecore/content/home//*[startswith(@@name, 'S')]

Returns child Items of the Home Item whose name starts with S.

Function: endswith(s1:string,s2:string):bool

Description: Indicates whether s1 ends with substring s2. The comparison is case sensitive.

Query Example:

query:/sitecore/content/home//*[endswith(@@name, 's')]

Returns child Items of the Home Item whose name ends with s.

Function: last():int

Description: Returns the index of the last Item in the list of children.

Query Example:

query:/sitecore/content/home/Products/*[last()]

Returns the index of the last child Item under the Products Item.

 

Function: not(condition:bool):bool

Description: Returns the parameter’s opposite value.

Query Example:

query:/sitecore/content/Home/Products/*[not(contains(@Text, 'Bargain'))]

Returns child Items of the Products Item whose text field doesn’t contain the string Bargain.

Function: position():int

Description: Returns the position of the context Item.

 

Query Example:

query:/sitecore/content/Home/Products/*[position() >= 2]

Returns child Items of the Products Item whose index is more than or equal to 2.

3.4.  Axes

The axis component of a query determines the direction of the node selection in relation to the context node. An axis can be thought of as a directional query.

Please follow the link below for more information about Axes in Sitecore:

http://sdn.sitecore.net/Developer/Sitecore%20and%20XSL/Axes.html

 

ancestor Returns all the ancestors of the context Item (same as XPath)
ancestor-or-self Returns the context Item and all the ancestors of the context Item (same as XPath)
child (/*) Returns all the children of the context Item (same as XPath)
descendant (//*) Returns all the descendants of the context Item; a descendant is a child or a child of a child and so on (same as XPath)
descendant-or-self Returns the context Item and all the descendants of the context Item (same as XPath)
following Returns all the following siblings of the context node (same as following-sibling in XPath)
parent (..) Returns the parent Item of the context Item (same as XPath)
preceding Returns all the preceding siblings of the context Item (same as preceding-sibling in XPath)
self (.) returns the context Item (same as XPath)
[int index] Returns the child Item with the mentioned index

 

Examples:

1) query:/sitecore/content/Home/Products/Documents/parent::*/child::*

Result : returns all children of the parent Item of the Documents Item.
  

query:/sitecore/content/Home//*[@@name='Jacket']/ancestor-or-self::*

Result : returns all ancestors of the Jacket Item and the Jacket Item itself.
  

2) query:/sitecore/content/Home/*[@@name='Products']/child::*

Result : returns children of the Products Item.
 

3) query:/sitecore/content/Home/descendant::*[@@name='Documents' or @@name = 'Shapes']

Result : returns Documents and Shapes Items if they are present among the descendants of the Home Item (the functionality of the Axis expression here is the same as that of the //* expression).

 

4) query:/sitecore/content/Home//*[@@name='Stylish Bag' or @@name = 'Shapes']/following::*

Result : returns all Items that follow the Stylish Bag Item and Shapes Item.
 

5) query:self::

Result : returns the Query Test Item, which appears to be the context Item.
 

6) query:/sitecore/content/Home/*[3]

Result : returns the Item under the Home Item whose index is equal to 3.

3.5.  Operators

Below is a list of operators that can be used in Sitecore Query expressions:

Operator Description Example Return value
| Contracts two Item-sets //*/Products|//*/Shapes Returns children of Products and Shapes Items
+ Addition 6 + 4 10
- Subtraction 6 - 4 2
* Multiplication 6 * 4 24
div Division 8 div 4 2
= Equal position()=3 true if position() is 3,
false otherwise
!= Not equal position()!=3 False if position() is 3,
true otherwise
Less than position()<4 true if position() is less than 4
<= Less than or equal to position()<=4 true if position() is less than or equal to 4
Greater than position()>4 true if position() is greater than 4
>= Greater than or equal to position()>=4 true if position() is greater than or equal to 4
or or position()=3 or position()=4 true if position() is 3 or 4, false otherwise
and and position()>3 and position()<7 true if position() is between 3 and 7, false otherwise
mod Modulus (division remainder) 5 mod 2 1

 

Examples:

query:/sitecore/content/home/*[(2+3) div 2 - 1]

query:/sitecore/content/Home/*[3 * 2 - 6 div 2]

query:/sitecore/content/home/*[(@@name='Item1' or @@name='Item2') and position()>= 1 and position() < 5 and position() != 3]

query:/sitecore/content/Home/Products/Documents/Old Document/ancestor-or-self::*|self::


Prev