Overview of the SharePoint CAML language

CAML stands for Collaborative Application Markup Language. It's an XML based query language that you can use to filter, sort and group by list items in a SharePoint list to quickly find back the correct items based on your given criteria.

You could compare it with writing SQL queries. You can define which columns need to be compared in which way with a certain value. You can combine with AND or OR. You can have as many as this combinations as you want.

The complete schema definition you can find here.

Some handy examples

One single filter

   1: <where>

   2:     <and>

   3:           <contains>

   4:                    <FieldRef name="InternalColumnName" />

   5:                    <Value Type="Text">ValueToFind</Value>

   6:           </contains>

   7:     </and>

   8: </where>

Combination of two filters

   1: <Where>

   2:   <Or>

   3:      <Geq>

   4:          <FieldRef Name="Field1"/>

   5:          <Value Type="Number">1500</Value>

   6:      </Geq>

   7:      <Leq>

   8:         <FieldRef Name="Field2"/>

   9:         <Value Type="Number">500</Value>

  10:      </Leq>

  11:    </Or>

  12: </Where>

Combining more than two filters (you can only have two filters on the same level!):

   1: <Where>

   2:     <And>

   3:       <Or>

   4:          <Geq>

   5:              <FieldRef Name="Field1"/>

   6:              <Value Type="Number">1500</Value>

   7:          </Geq>

   8:          <Leq>

   9:             <FieldRef Name="Field2"/><Value Type="Number">500</Value>

  10:          </Leq>

  11:        </Or>

  12:        <Eq>

  13:           <FieldRef Name="Field3"/><Value Type="Text">Value</Value>

  14:        </Eq>

  15:     </And>

  16: </Where>

Ordering

   1: <OrderBy> 

   2:        <FieldRef Name="Modified" Ascending="FALSE"></FieldRef> 

   3: </OrderBy> 

   4: <Where> 

   5:   <Or> 

   6:     <Neq> 

   7:       <FieldRef Name="Status"></FieldRef> 

   8:       <Value Type="Text">Completed</Value> 

   9:     </Neq> 

  10:     <IsNull> 

  11:       <FieldRef Name="Status"></FieldRef> 

  12:     </IsNull> 

  13:   </Or> 

  14: </Where>

Filtering on lookup field (first example is when querying the list item’s ID, second example is querying on the lookup value itself)

   1: <Where>

   2:     <Eq>

   3:       <FieldRef Name="LookupFieldInternalName" LookupId="TRUE" />

   4:       <Value Type="Lookup">15</Value>

   5:     </Eq>

   6: </Where>

   1: <Where>

   2:     <Eq>

   3:       <FieldRef Name="LookupFieldInternalName" />

   4:       <Value Type="Lookup">LookupValue</Value>

   5:     </Eq>

   6: </Where>

Using it within your code

The following example will show you how you can actually use these queries in your code. You will create a SPQuery object, assign the query and use it on a list. What you get back is a list of items that are the result of your query.

   1: SPWeb oWebsiteRoot = SPContext.Current.Site.RootWeb

   2: SPList oList = oWebsiteRoot.Lists["Tasks"];

   3:  

   4: SPQuery oQuery = new SPQuery();

   5: oQuery.Query = "<Where><Eq><FieldRef Name='Status'/>" +

   6:     "<Value Type='Text'>Completed</Value></Eq></Where>";

   7: SPListItemCollection collListItems = oList.GetItems(oQuery);

   8:  

   9: foreach (SPListItem oListItem in collListItems)

  10: {

  11:     Response.Write(SPEncode.HtmlEncode(oListItem["Title"].ToString()) + 

  12:         "<BR>");

  13: }