Querying on Managed Metadata Field Values in SharePoint Server 2010 (ECM)

Applies to: SharePoint Server 2010

In this article
CAML Queries
Search Queries
Examples

In Microsoft SharePoint Server 2010, you must be careful when constructing queries that are designed to return results that represent items that were tagged with values in a managed metadata column. SharePoint Server 2010 supports returning scoped metadata values or unscoped metadata values from the TermStore database, regardless of whether you are writing a Collaborative Application Markup Language (CAML) query and using an API (such as the SPQuery object) to get items from a specific list, or using an API (such as Query) to execute search queries.

CAML Queries

When writing a Collaborative Application Markup Language (CAML) query to return items from an SPList object that are tagged with a specific value in a managed metadata column, you must specify the lookup ID of the term that you want to match. Lookup IDs are site collection–specific; a specified term has a different lookup ID for every site collection where that term is used. To get the lookup ID for a term, you can use the GetWssIdsOfKeywordTerm() method. Or, you can use the GetWssIdsOfKeywordTerm() method if the term is a keyword (if the term’s IsKeyword property is set to true). In certain scenarios, a single term may have multiple lookup IDs for the same site collecton; for example, a merged term has one lookup ID for each term that was used in the site collection and later merged into the single term. After you find the lookup IDs for a term, you can combine the IDs in an IN clause in a Collaborative Application Markup Language (CAML) query to query for items tagged with that term. Below is a Collaborative Application Markup Language (CAML) query that queries for items in a list that have lookup ID 14 and lookup ID 15 in the field ItemType.

<Query><Where><In><FieldRef LookupId="TRUE" Name="ItemType" /><Values><Value Type="Integer">14</Value><Value Type="Integer">15</Value></Where></Query>

You can build queries that include lookup IDs for multiple terms. A common task is to build a query that gets items that are tagged with a specified term or any of that term’s descendent terms. By passing true to the bool includeDescendants parameter to TaxonomyField.GetWssIdsOfKeywordTerm, you get the lookup IDs for the term with the specified GUID, and you get the IDs for all its child terms.

Search Queries

Search automatically creates indexed properties that correspond to managed metadata fields that facilitate querying search for items that are tagged with specific managed metadata values, as detailed in Table 1.

Table 1. Search query properties

Examples

The examples listed in Table 2 show search query strings that search for items that contain the keyword turtle and that are also tagged with a specific field/value combination.

Table 2. Example search query strings

The following code example demonstrates how to query on metadata field values.

using System;
using System.IO;
using System.Globalization;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Taxonomy;

namespace Microsoft.SDK.SharePointServer.Samples
{
// We are trying to get all the Wss IDs of this term when used as a keyword.
            int[] wssIds = TaxonomyField.GetWssIdsOfKeywordTerm(site, term.Id, 500);
            Console.Write("The wss ID's of your term are");
            if (wssIds.Length == 0)
            {
                Console.Write(" empty");
            }
            else
            {
                foreach (int wssId in wssIds)
                {
                    Console.WriteLine(" " + wssId.ToString());
                }
            }

            Console.WriteLine(".");
        }

        /// <summary>
        /// This method writes to the console the Wss ID values of the managed metadata term
        /// on the specified SPSite.
        /// </summary>
        private void TestGetWssIdsOfTerm(SPSite site, Term term)
        {
            if (term == null)
            {
                throw new ArgumentException("Parameter term cannot be null");
            }
            if (site == null)
            {
                throw new ArgumentException("Parameter site cannot be null");
            }

            // We are trying to get all the Wss IDs of this term without its children.
            int[] wssIds = TaxonomyField.GetWssIdsOfTerm(site, term.TermStore.Id, term.TermSet.Id, term.Id, false /*includeDescendants*/, 500);
            Console.Write("The wss ID's of your term are");
            if (wssIds.Length == 0)
            {
                Console.Write(" empty");
            }
            else
            {
                foreach (int wssId in wssIds)
                {
                    Console.Write(" " + wssId.ToString());
                }
            }

            Console.WriteLine(".");
        }
    }
}

See Also

Concepts

Managing Enterprise Metadata in SharePoint Server 2010 (ECM)

Metadata and Taxonomy Programming Model in SharePoint Server 2010 (ECM)