Sitecre CMS 6 Using Sitecre Fast Query Rev: 2010-03-10 Sitecre CMS 6 Using Sitecre Fast Query
Table f Cntents Chapter 1 Intrductin... 3 Chapter 2 Applicatin... 5 2.1 Executing Queries... 6 2.2 Specifying the Surce... 7 2.3 Using API in the custm.net cde... 8 Chapter 3 Sitecre Fast Query Limitatins... 9 Chapter 4 Sitecre Fast Query Syntax... 11 4.1 Basic Query Expressin... 13 4.2 Attributes... 14 4.3 Axes... 19 Page 2 f 20
Chapter 1 Intrductin The techniques described in this dcument apply t Sitecre CMS 6. Sitecre Fast Query is designed fr retrieving and filtering items frm the Sitecre database. Sitecre Fast Query uses the database engine t execute queries. Sitecre Fast Query has the fllwing benefits cmpared t the standard Sitecre Query: Imprved perfrmance queries are executed by the SQL engine and as a result the scalability and perfrmance f the SQL engine is nt limited by.net r by Sitecre. Cnsumes less memry Sitecre Query lads every item that it tuches int memry (cache) and this can fill the cache with unnecessary infrmatin. Sitecre Fast Query nly lads the items frm the result set and this minimizes the pressure n the cache. Sitecre Fast Query is similar t XPath and Sitecre Query statements in many ways. The mst ntable difference in using Fast Query is that yu use the fast: keywrd. Imprtant The perfrmance f Fast Query decreases significantly fr statements that query many fields in a single cnditin statement. We therefre recmmend that yu include n mre than 10 fields in each cnditin statement. Sitecre Fast Query can be used: In the Cntent Editr as a surce fr List Types fields. In the Develper Center, in the XPath Builder tab. In custm.net cde by using the SelectSingleItem() methd and the SelectItems() methds f the Sitecre.Data.Database class. Sitecre Fast Query is prcessed n the server in the same way as XPath and Sitecre Query. Imprtant There are sme limitatins when using Sitecre Fast Query in the latest versin f Sitecre CMS 6. Fr mre infrmatin abut these limitatins, see the Errr! Reference surce nt fund. chapter. This dcument cntains the fllwing chapters: Applicatin In the Develper Center, in the XPath Builder tab, Sitecre Fast Queries are used t execute Page 3 f 20
queries and ppulate the lists in Sitecre lkup fields and fr retrieving items in the custm.net cde. Sitecre Fast Query Limitatins This sectin describes the limitatins f Sitecre Fast Query. Sitecre Fast Query Syntax Sitecre Fast Query uses a path ntatin, similar t XPath expressins and Sitecre Query, fr addressing Items in a Sitecre cntent tree. Errr! Reference surce nt fund. This sectin describes the knwn issues assciated with Sitecre Fast Query in the release f Sitecre CMS 6 till versin 6.2.0 rev. 091012. Page 4 f 20
Chapter 2 Applicatin In the Develper Center, in the XPath Builder tab, Sitecre Fast Queries are used t execute queries and ppulate the lists in Sitecre lkup fields and fr retrieving items in custm.net cde. The XPath Builder is used t test XPath expressins, Sitecre Query, and Sitecre Fast Query. The Surce field is used t ppulate the lkup fields. Page 5 f 20
2.1 Executing Queries 1. In the Develper Center, click Tls, XPath Builder t pen the XPath Builder. 2. In the XPath Builder, click Sitecre Query Ntatin and fill in the XPath Expressin field with a query expressin, fr example, fast:/sitecre/cntent/hme/shapes/* The main difference between Sitecre Query and Sitecre Fast Query is the fast: keywrd. Yu use Sitecre Fast Query in the XPath Builder just like Sitecre Query, except the expressin shuld be preceded by the fast: keywrd. Fr mre infrmatin abut the syntax, refer t the Sitecre Fast Query Syntax chapter. Page 6 f 20
2.2 Specifying the Surce In items that cntain a Surce field, in the Surce field, enter a query expressin: Fr example, this surce defines the set f shapes that ppulate the list field. The main benefit f the query expressins is that it retrieves a plain list f the items regardless f the cntent tree hierarchy. The query: keywrd shuld nly be used with Surce fields. It specifies that yu use Sitecre Query. Yu can use three different query types in Surce fields: Path t the rt item: /sitecre/cntent/hme/shapes This expressin returns all the items that are children f the Shapes item. Sitecre Query: query:/sitecre/cntent/hme/shapes This expressin uses Sitecre Query t return the Shapes item. query:/sitecre/cntent/hme/shapes/* This expressin uses Sitecre Query t return all the items that are children f the Shapes item. Sitecre Fast Query: query:fast:/sitecre/cntent/hme/shapes This expressin uses Sitecre Fast Query t return the Shapes item. query:fast:/sitecre/cntent/hme/shapes/* This expressin uses Sitecre Fast Query t returns all the items that are children f the Shapes item. Page 7 f 20
2.3 Using API in the custm.net cde Sitecre Fast Queries can be executed using the API with the same query methds that yu can use with Sitecre query. The SelectItems() and SelectSingleItem() methds bth accept Fast Query statements t perfrm SQL-based searches. T retrieve the cntent items that are stred under the Shapes item: Sitecre.Data.Database database = Sitecre.Data.Database.GetDatabase("master"); Sitecre.Data.Items.Item[] items = database.selectitems("fast:/sitecre/cntent/hme/shapes/*"); T retrieve the Shapes item: Sitecre.Data.Items.Item item = database.selectsingleitem("fast:/sitecre/cntent/hme/shapes"); Retrieve the Hme item: Sitecre.Data.Items.Item[] items = database.selectitems("fast:/sitecre/cntent/hme"); T retrieve the first item that is stred under the Shapes item: Sitecre.Data.Items.Item item = database.selectsingleitem("fast:/sitecre/cntent/hme/shapes/*"); If yu remve the fast: keywrd frm these query strings and call them, yu use Sitecre Query t return the same results. Page 8 f 20
Chapter 3 Sitecre Fast Query Limitatins Sitecre Fast Query is translated t SQL queries that be executed by the database engine. Sitecre Fast Query cnverts all the query cnditins int SQL statements, and this places certain limitatins n the use f queries: Sitecre Fast Query nly supprts the fllwing axes: parent:: child:: ancestr:: (when the FastQueryDescendantsDisabled setting is set t false ) descendant:: (when the FastQueryDescendantsDisabled setting is set t false ) Sitecre Fast Query nly supprts the fllwing special attributes: @@id @@name @@key @@templateid @@templatename @@templatekey @@masterid @@parentid Standard values are nt supprted. Functins are nt supprted. Hwever the cntains() functin can be replaced by a string equality peratr that cntains SQL wildcards. Fr example: //*[cntains(@title, 'Sitecre')] is equivalent t fast://*[@title = '%Sitecre%']" Operatrs are nt supprted. Subqueries are nt supprted: fast://*[../@title = 'Sitecre'] will nt wrk prperly. Page 9 f 20
Sitecre Fast Query des nt return virtual items in the result set. Sitecre Fast Query nly wrks n data prviders that inherit frm the SqlDataPrvider class and that supprt the SQL query that is generated by the QueryTSqlTranslatr class. Sitecre Fast Query des nt supprt the use f the pipe ( ) separatr t select several paths in ne expressin: fast:/sitecre/cntent /sitecre/cntent/hme will nt wrk. Page 10 f 20
Chapter 4 Sitecre Fast Query Syntax Sitecre Fast Query uses a path ntatin t retrieve items frm the Sitecre cntent tree. This is similar t XPath expressins and Sitecre Query. The expressin is evaluated t yield an item set. In additin, a query expressin can have predicates (filter expressins). Fr example, the expressin Entry[@Title = '%Welcme t Sitecre%'] refers t the entry items whse Title field cntains the wrds "Welcme t Sitecre". Here are sme cmmn query expressins: fast:/sitecre/cntent/hme This expressin returns the Hme item. fast:/sitecre/cntent/hme/* This expressin returns all the children f the Hme item. fast:/sitecre/cntent/hme//*[@@templatename='sample Item'] This expressin returns all the items that have hme as their ancestr and are based n the Sample Item template. Nte Item names in the path expressin are nt case sensitive. Fr example, /sitecre/cntent/hme gives the same result as /sitecre/cntent/hme. All f the examples in this sectin are based n the fllwing cntent tree: Page 11 f 20
The items in the cntent tree are based n the fllwing templates: Prduct, Shape, and Query Test. The Query Test Item is based n the Query Test template and this template cntains a multilist field. This field is used t test the queries used in this sectin. Nte If the FastQueryDescendantsDisabled setting, in the web.cnfig file, is set t true and then changed back t false, yu must rebuild the Descendents table. T rebuild the Descendents table, click Sitecre, Cntrl Panel, Databases, Clean Up Database and run the Clean Up Database wizard. Page 12 f 20
4.1 Basic Query Expressin This is a list f the basic expressins used in the query paths: / Selects frm the rt item // Selects items frm all the descendants f the specified item.. Selects the parent f the specified item @ @@ Fast Query Examples: Selects fields (please refer t the Attributes sectin fr details) Selects attributes (please refer t the Attributes sectin fr details) fast:/sitecre/cntent/hme/prducts Result: returns the Prducts item. fast:/sitecre/cntent/hme/prducts/* Result: returns all the descendants f the Prducts item. fast:/sitecre/cntent/hme//circle Result: returns the Circle item that is stred under the Hme item. fast:/sitecre/cntent/hme//circle/.. Result: returns the parent f the Circle item that is stred under the Hme item. Predicates are used t find a specific Item r an Item that cntains a specific value. Page 13 f 20
4.2 Attributes This sectin describes the predicates that are available in Sitecre Fast Query. Predicates are always embedded in square brackets. Fast Query Examples: Attribute: [@fieldname] Descriptin: Item field name. fast:/sitecre/cntent/hme/*[@title = 'Welcme t Sitecre'] Result: returns the items that have the value f the 'Title' field set t 'Welcme t Sitecre'. The search is perfrmed in the children f the Hme Item. Nte: When yu use fields in yur query expressins, use the database field values. T read mre abut hw field values are stred in the database, refer t the Accessing Field Values article. fast:/sitecre/cntent/hme/prducts/hammer[@available = '1'] Result: returns all the items named Hammer which have the value f the Available check bx set t '1'. Attribute: [@@id] Descriptin: Item ID. fast://*[@@id = '{787EE6C5-0885-495D-855E-1D129C643E55}'] Result: searches thrugh the entire cntent tree and returns the item with the specified ID. Nte: Searches based n item IDs perfrm faster than searches based in item names. Yu shuld therefre use item IDs when yu need t search fr a specific item. Attribute: [@@name] Descriptin: Item name. Case sensitive. fast:/sitecre/cntent/hme/prducts/*[@@name = 'Hammer'] Page 14 f 20
Result: the search is perfrmed in the children f the Prducts Item. Attribute: [@@key] Descriptin: Item name lwer cased. Fr example: [@@key = 'item'] will match item and Item. Nte: The key must be in lwercase. fast:/sitecre/cntent/hme/prducts/*[@@key = 'hammer'] Result: the search is perfrmed in the children f the Prducts item. Attribute: [@@templateid] Descriptin: Item template ID. fast:/sitecre/cntent/hme//*[@@templateid = '{F348C2A0-73B8-4AF4- BD9E-2C5901908369}'] Result: returns all the descendants f the Hme item that are based n the template with the specified ID. Attribute: [@@templatename] Descriptin: Item Template name. The value is case sensitive. fast:/sitecre/cntent/hme//*[@@templatename = 'Shape'] Result: returns all the descendants f the Hme item that are based n the Shape template. Attribute: [@@templatekey] Descriptin: The template name in lwercase. fast:/sitecre/cntent/hme//*[@@templatekey = 'prduct'] Page 15 f 20
Result: returns all the descendants f the Hme item that are based n the Prduct template. Attribute: [@@masterid] Descriptin: The master ID. fast:/sitecre/cntent/hme//*[@@masterid='{47d22b69-aadc-4a79-9347- E0AD225F84FB}'] Result: returns all the descendants f the Hme item that were created by using master (branch) with the specified ID. Attribute: [@@parentid] Descriptin: The parent item ID. fast:/sitecre/cntent/hme//*[@@parentid='{8f906bee-ba50-429f-9dcc- 3EC4794FA182}'] Result: returns all the descendants f the Hme item whse parent item has the specified ID. Mre Fast Query Examples: Querying a linear list f items with a cmplex expressin. fast:/sitecre/cntent/hme//*[@@id='{d394cca7-c88b-418c-8b2b- AA97AA52EE14}' r @@key = 'stylish bag' r @@name = 'Hammer'] Result: returns all the descendants f the Hme item with the specified ID r whse key is stylish bag r whse name is Hammer. fast:/sitecre/cntent/hme//*[@text='bargain Price' and @Available='1'] Result: returns all the descendants f the Hme item where the Text field says Bargain Price and Page 16 f 20
where the Available field is set t true. Querying several levels f items (a tree with regular structure). fast://hme/*[@@name='shapes']/*[@title='%le%'] Result: returns the descendants f the Hme item that cntain the le substring in the Title field and are stred under the Shapes item. Querying a subtree f items with an irregular structure. fast:/sitecre/cntent/hme//*[@ Updated >= '20090101' and @@templatename = 'Shape'] Result: fast:/sitecre/cntent/hme//*[@title = 'Dcuments' and @@templatename = 'Sample Item']//*[@Title = '%New%' and @@templatename = 'Prduct'] Result: Querying items by template acrss the whle database. //*[@@templatename = 'Shape' and @Title = 'Circle'] Result: fast://*[@title = '%le%' and @Text = '' and @@templatename = 'Shape'] Page 17 f 20
Result: Page 18 f 20
4.3 Axes The axis cmpnent f a query determines the directin f the nde selectin in relatin t the cntext nde. Think f an axis as a directinal query. T read mre abut axes in Sitecre, refer t the Axes article. ancestr parent child descendant Returns all the ancestrs f the specified item (same as XPath) (..) Returns the parent Item f the specified item (same as XPath) (/*) Returns all the children f the specified item (same as XPath) (//*) Returns all the descendants f the specified item; a descendant is a child r a child f a child and s n (same as XPath) Fast Query Examples: fast:/sitecre/cntent/hme//*[@@name='jacket']/ancestr::* Result: returns all the ancestrs f the Jacket Item and the Jacket Item itself. fast:/sitecre/cntent/hme/prducts/dcuments/parent::*/child::* Nte: Shrthand ntatin. fast:/sitecre/cntent/hme/prducts/dcuments/../* Result: returns all the children f the parent Item f the Dcuments Item. fast:/sitecre/cntent/hme/*[@@name='shapes']/child::* Nte: Shrthand ntatin. fast:/sitecre/cntent/hme/*[@@name='shapes']/* fast:/sitecre/cntent/hme/shapes/* Page 19 f 20
Result: returns the children f the Prducts Item. fast:/sitecre/cntent/hme/descendant::*[@@name='dcuments' r @@name = 'Shapes'] Nte: Shrthand ntatin. fast:/sitecre/cntent/hme//*[@@name='dcuments' r @@name = 'Shapes'] Result: returns the Dcuments and Shapes Items if they are amng the descendants f the Hme Item. This axis expressin wrks the same as that f the //* expressin. Page 20 f 20