Related Posts...
WSS Field Names for Lists & Document Libraries, Test your SPSiteDataQuery parameters using Snippet Compiler, Problems with WSS columns & internal field names, Specifying the Internal Name for WSS Columns, XML results using SPSiteDataQuery in SharePoint
I have been playing with the SPSiteDataQuery a fair bit recently and thought it would be interesting to post some of the results.
When using the SPSiteDataQuery to perform a search there are four main properties you are going to set which determine the results you will get. If you have seen my previous post (XML results using SPSiteDataQuery in SharePoint) you will have seen that they are Lists, Query, Webs and ViewFields.
If you read nothing else then remember this...If you make a mistake in the Webs or Lists properties, invalid XML or invalid attributes, the SPSiteDataQuery will fall back to it's default behavior and will not throw an error!! Knowing this can save a lot of time...ensure your properties are correctly formatted.
So, assuming the basic setup is
SPSiteDataQuery q = new SPSiteDataQuery();
q.Lists = "<Lists BaseType='1'/>";
q.Query = "<Where><Gt><FieldRef Name='ID' /><Value Type='Number'>0</Value></Gt></Where>";
q.Webs = "<Webs Scope='SiteCollection' />";
q.ViewFields = "<FieldRef Name='Title' /><FieldRef Name='ID' />"';
q.RowLimit = 10;
Here are the changes you can make to achieve different result sets and tips as to why the query could be failing.
The Webs Property
There are basically three different values for this...
"<Webs Scope='SiteCollection' />" This will search the entire site collection no matter which web you use to execute the query.
"<Webs Scope='Recursive' />" This will search the web on which you execute the query and recurse through any child webs.
"" If you leave it blank then it will only search the web on which you execute the query. No child webs will be queried. This is important as I have read on several other sites that this is not possible with SPSiteDataQuery, but it is!!
I would also point out that that if you get anything wrong with this property SharePoint will not throw an error, it will just default to the blank behavior...It will only search the web on which you executed the query. This is an important point as "<Webs scope='Recursive' />" or "<Webs Scope='recursive' />" (small 's' in Scope and small 'r' in recursive) look OK but are actually invalid and the query will default to only the current web.
The Lists Property
This defines what type of document libraries and lists WSS will search for your items. You can specify the exact type of list, the base type or even specific lists. Examples of the Lists property are...
"<Lists BaseType='1'/>" As above, this will search all lists which are based on a 'Document Library. This is useful if you only want to find documents. Other values for BaseType include...
0 - Generic list - This will search all lists and not document libraries.
1 - Document Library
3 - Discussion Forum
4 - Vote or Survey
5 - Issues list
(no, I don't know what happened to number 2!!)
I should also point out that the default is to search BaseType = '0' , and so if you do not set or make a mistake in the XML only lists will be searched.
"<Lists ServerTemplate='850'/>" This will limit the search to only a particular list template (850 is the Pages template in a publishing site). The number is fairly random and is defined in the list definition. I haven't needed to look at them as yet so I don't know a better way than looking in the definitions in the FEATURES folder for SharePoint. If you make a mistake with this property it will revert to the default.
Another options is Hidden, which determines if hidden lists or document libraries are searched. This an additional attribute and would be used like this...
"<Lists ServerTemplate='850' Hidden='TRUE'/>"
The MaxListLimit attribute specifies the total number of lists to search. You will receive an exception if the query exceeds the MaxListLimit. The default amount is 1000 and by setting this to 0 you can search everything. So the following would only search the first 50 lists...
"<Lists BaseType='1' MaxListsLimit='50'/>"
Another thing you can do with the Lists property is to query specific lists. This can be done by specifying the Guid of the list you want to search. An example would be...
"<Lists><List ID="129AB4CAE-12EF-9871-DE45-F34A180D3EAB5"/></Lists>"
You would obviously need to know the Guid of the lists you wish to query before creating this property.
The ViewFields property
The ViewFields property specifies the fields (columns), that will be returned in the query. This is very similar to SQL and you should ensure that you specify any fields that you may wish to use in you Where or OrderBy part of the query.
Things to point out here is that that you can specify the ID(Guid) of the property or the name of the property...this is the Internal Name, not the name you may see in the UI. For example the standard publishing field "Image Caption" would become "PublishingImageCaption" as that is it's internal name.
So, to add the "Image Caption" filed to the results we would need...
"<FieldRef Name='Title' /><FieldRef Name='ID' /><FieldRef Name='PublishingImageCaption' />"
Another thing to remember is that not all lists or documents libraries contain the same fields. If you are not worried about a particular field and want the item returned whether the field (column) exists or not the you can set Nullable to true. So if we have some items which may not have an 'Image Caption' column then we could use...
"<FieldRef Name='Title' /><FieldRef Name='ID' /><FieldRef Name='PublishingImageCaption' Nullable='TRUE'/>"
and this would still find those items without an 'Image Caption' column (field).
The Query Property
This property will allow you to bot limit and order you results. You can do both or just one, but it is similar to SQL in what you can do. There is a lot to this, but I will give a couple of samples...
Querying by date...
string sLastWeek = SPUtility.CreateISO8601DateTimeFromSystemDateTime(DateTime.Today.AddDays(-1));
q.Query = "<Where><Gt><FieldRef Name='Created'><Value Type='DateTime'>" + sLastWeek + "</Value></Gt></Where>";
This will find items created within the last week. The <Gt> denotes 'Greater Than', you could also use <Gte>, <Lt> or <Eq>. These can be combined to create more complex queries.
q.Query = "<OrderBy><FieldRef Name='Title' Ascending='FALSE'></OrderBy>";
This will order the items descending by the title (Z-A).
q.Query = "<Where><Gt><FieldRef Name='Created'><Value Type='DateTime'>" + sLastWeek + "</Value></Gt></Where><OrderBy><FieldRef Name='Title' Ascending='FALSE'></OrderBy>";
This is a combination of the above...items created in the last week ordered Z-A.
Finally, make sure you set the RowLimit property...you may not get any results otherwise!!
More information can be found on MSDN.