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

Property	Description
ows_tax_idFieldName	Indexes the ID(s) of the term(s) in the FieldName field, for each crawled item. It is mapped to the managed property owsTaxIdFieldName, which enables you to query for crawled items that are tagged in that field with a term with the specified term ID.
ows_FieldName	Indexes the label of the term(s) in the FieldName field, for each crawled item. Only the label of the term that was used to tag the item is included here; alternate labels are not indexed.
ows_taxid_MetadataAllTagsInfo	Indexes the ID(s) of all terms, for each crawled item, across all their metadata fields.This property is mapped to the managed property owsTaxIdMetadataAllTagsInfo, which enables you to query for crawled items that are tagged in any field with a term with a specified term ID.
owsMetadataFacetInfo	This retrievable property maintains a data structure that contains information about all terms on an item across all metadata fields. Following is the format of this data structure: ColmunInternalName|ColumnDisplayName|CompressedGuid(StoreId)|CompressedGuid(TermSetId)|CompressedGuid(TermId)|CurrentLabel;#

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

Example	Query String	Notes
A single term, reference materials, in the field ItemType:	http://contoso/searchcenter/pages/results.aspx?k=turtle&r="owstaxIdItemType"=#052263385-1fc3-4323-8d6b-50c8f6c3c45d:"reference materials”	#0 in the query string before the term ID means query for only the specified term ID.
The term reference materials or any of its descendants in the field ItemType:	http://contoso/searchcenter/pages/results.aspx?k= turtle &r="owstaxIdItemType"=#52263385-1fc3-4323-8d6b-50c8f6c3c45d:"reference materials"	# before the term ID means query for the specified term ID or the ID of any of that term’s child terms.
A single term across any of its fields:	http://contoso/searchcenter/pages/results.aspx?k= turtle &r=owstaxIdMetadataAllTagsInfo=#052263385-1fc3-4323-8d6b-50c8f6c3c45d:"reference materials"

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)