2.2.3.1 QueryPacket
A QueryPacket is the content of the protocol client's QuerySoapIn, QueryExSoapIn and GetQuerySuggestionsSoapIn SOAP messages. It defines the search query in the necessary detail for the protocol server to run it and return search results in the QuerySoapOut, QueryExSoapOut or GetQuerySuggestionsSoapOut SOAP messages.
If the protocol server fails to interpret the search query, it MUST respond with an ERROR_BAD_QUERY error code, defined in section 2.2.5.5, in the case of the Query operation, or an equivalent SOAP fault, in the case of the QueryEx and GetQuerySuggestions (section 3.1.4.2) operations.
-
<s:element name="QueryPacket"> <s:complexType> <s:all> <s:element name="Query"> <s:complexType> <s:all> <s:element name="QueryId" type="t:GUIDType" minOccurs="0"/> <s:element name="OriginatorId" type="t:GUIDType" minOccurs="0"/> <s:element name="SupportedFormats"> <s:complexType> <s:sequence> <s:any processContents="skip" minOccurs="0" maxOccurs="unbounded"/> </s:sequence> </s:complexType> </s:element> <s:element name="Context"> <s:complexType> <s:sequence> <s:element name="QueryText"> <s:complexType> <s:simpleContent> <s:extension base="s:string"> <s:attribute name="language" type="s:language" use="optional"/> <s:attribute name="type" type="q:QueryType" use="optional" default="STRING"/> </s:extension> </s:simpleContent> </s:complexType> </s:element> <s:element name="LanguagePreference" type="s:language" minOccurs="0"/> <s:element name="Requery" minOccurs="0"> <s:complexType> <s:sequence> <s:any processContents="skip" minOccurs="0" maxOccurs="unbounded"/> </s:sequence> </s:complexType> </s:element> <s:element name="OriginatorContext" minOccurs="0"> <s:complexType> <s:sequence> <s:any processContents="skip" minOccurs="0" maxOccurs="unbounded"/> </s:sequence> </s:complexType> </s:element> </s:sequence> </s:complexType> </s:element> <s:element name="Range" minOccurs="0"> <s:complexType> <s:sequence> <s:element name="StartAt" type="t:StartAtType" default="1" minOccurs="0"/> <s:element name="Count" type="s:unsignedInt" minOccurs="0"/> </s:sequence> <s:attribute name="id" type="s:string" use="optional"/> </s:complexType> </s:element> <s:element name="Keywords" minOccurs="0"> <s:complexType> <s:sequence> <s:any minOccurs="0" maxOccurs="unbounded" processContents="skip"/> </s:sequence> <s:anyAttribute processContents="skip"/> </s:complexType> </s:element> <s:element name="OfficeContext" minOccurs="0"> <s:complexType> <s:sequence> <s:any minOccurs="0" maxOccurs="unbounded" processContents="skip"/> </s:sequence> <s:anyAttribute processContents="skip"/> </s:complexType> </s:element> <s:element name="Properties" minOccurs="0"> <s:complexType> <s:sequence> <s:element name="Property" minOccurs="0" maxOccurs="unbounded"> <s:complexType> <s:attribute name="name" type="s:string"/> </s:complexType> </s:element> </s:sequence> </s:complexType> </s:element> <s:element name="SortByProperties" minOccurs="0"> <s:complexType> <s:sequence> <s:element name="SortByProperty" minOccurs="0" maxOccurs="unbounded"> <s:complexType> <s:attribute name="name" type="s:string"/> <s:attribute name="direction" type="q:DirectionType" use="optional"/> </s:complexType> </s:element> </s:sequence> </s:complexType> </s:element> <s:element name="ImplicitAndBehavior" type="s:boolean" minOccurs="0"/> <s:element name="RelevanceModel" type="t:GUIDType" minOccurs="0"/> <s:element name="EnableStemming" type="s:boolean" minOccurs="0"/> <s:element name="EnableNicknames" type="s:boolean" minOccurs="0"/> <s:element name="EnablePhonetic" type="s:boolean" minOccurs="0"/> <s:element name="TrimDuplicates" minOccurs="0"> <s:complexType> <s:simpleContent> <s:extension base="s:boolean"> <s:attribute name="onproperty" type="s:string"/> <s:attribute name="keepcount" type="s:unsignedInt"/> <s:attribute name="includeid" type="s:unsignedInt"/> </s:extension> </s:simpleContent> </s:complexType> </s:element> <s:element name="IncludeSpecialTermResults" type="s:boolean" minOccurs="0"/> <s:element name="PreQuerySuggestions" type="s:boolean" minOccurs="0"/> <s:element name="HighlightQuerySuggestions" type="s:boolean" minOccurs="0"/> <s:element name="CapitalizeFirstLetters" type="s:boolean" minOccurs="0"/> <s:element name="ResultProvider" type="s:string" minOccurs="0" /> <s:element name="ResubmitFlags" minOccurs="0"> <s:complexType> <s:sequence> <s:element name="ResubmitFlag" minOccurs="0" maxOccurs="unbounded"> <s:complexType> <s:attribute name="value" type="s:string"/> </s:complexType> </s:element> </s:sequence> </s:complexType> </s:element> <s:element name="EnableSpellcheck" type="s:string" minOccurs="0" /> <s:element name="UserContext" minOccurs="0"> <s:complexType> <s:attribute name="includeuserprofile" type="s:boolean" use="optional"/> <s:sequence> <s:element name="UserContextData" type="s:string" minOccurs="0" /> </s:sequence> </s:complexType> </s:element> <s:element name="FindSimilar" minOccurs="0"> <s:complexType> <s:sequence> <s:element name="SimilarType" type="s:string" minOccurs="0"/> <s:element name="SimilarTo" type="t:SimilarToType" minOccurs="0"/> <s:element name="SortSimilar" type="s:boolean" minOccurs="0"/> </s:sequence> </s:complexType> </s:element> <s:element name="IncludeRefinementResults" minOccurs="0"> <s:complexType> <s:sequence> <s:element name="Refiners" minOccurs="0"> <s:complexType> <s:sequence> <s:element name="Refiner" type="s:string" minOccurs="0" /> </s:sequence> </s:complexType> </s:element> <s:element name="MaxShallowRefinementHits" type="s:int" minOccurs="0"/> </s:sequence> </s:complexType> </s:element> <s:element name="RefinementFilters" minOccurs="0"> <s:complexType> <s:sequence> <s:element name="RefinementFilter" type="s:string" minOccurs="0" maxOccurs="unbounded"> </s:element> </s:sequence> </s:complexType> </s:element> <s:element name="IgnoreAllNoiseQuery" type="s:boolean" minOccurs="0"/> <s:element name="IncludeRelevantResults" type="s:boolean" minOccurs="0"/> <s:element name="IncludeHighConfidenceResults" type="s:boolean" minOccurs="0"/> </s:all> <s:attribute name="domain" type="t:String255" use="optional"/> </s:complexType> </s:element> </s:all> <s:attribute name="revision" type="s:unsignedInt" use="optional"/> <s:attribute name="build" type="t:String255" use="optional"/> </s:complexType> </s:element>
revision:<2> The revision of the protocol client. The Search Protocol does not limit the format or meaning of this attribute in any way beyond the limitations of its WSDL definition.
build:<3> The build number of the protocol client, a String255 Simple Type (see section 2.2.5.8). The Search Protocol does not limit the format or meaning of this attribute in any way beyond the limitations of its WSDL definition.
Query: The parent element for the child elements that define the query.
Query.domain: The domain of the query, a String255 Simple Type (see section 2.2.5.8). If present in the case of the Query operation, MUST be returned to the protocol client in the response unchanged. In all other ways, the domain attribute MUST be ignored by the protocol server.
Query.QueryId: A GUID that uniquely identifies a search query request to the Query Web service. A GUIDType Simple Type (see section 2.2.5.2).
Query.OriginatorId: A GUID that uniquely identifies the protocol client. A GUIDType Simple Type (see section 2.2.5.2).
Query.SupportedFormats: Specifies the result formats supported by the protocol client. It is currently unused and its contents MUST be ignored by the protocol server.
Query.Context: The parent element for the search query issued to the Query web service.
Query.Context.QueryText: The query text. The format of the query text depends on the presence and value of the type attribute. If the type attribute is not present, or its value is "STRING", the search query is specified as a SharePoint Search keyword query. If the type attribute is present, and its value is "MSSQLFT", the search query is specified as a SharePoint Search SQL query. If the type attribute is present, and its value is "FQL", the search query is specified as a FAST Query Language (FQL) query (described in [MS-FQL2]).
Query.Context.QueryText.language: The language for the query text. The protocol server SHOULD use this information to influence its interpretation of the query text. If this attribute is not present, the protocol server SHOULD revert to a default value, such as the language of the underlying operating system. The format of this field is the standard format for language fields in XML. An example would be "en-us" for US English.
Query.Context.QueryText.type: The type of query, a QueryType Simple Type (see section 2.2.5.3). If present, the value MUST be "STRING" if the query text is specified as a SharePoint Search keyword query (described in sections 2.2.10 and 2.2.11) or "MSSQLFT" if it is specified as a SharePoint Search SQL query (described in sections 2.2.12 and 2.2.13), or "FQL" if it is specified as a FAST Query Language (FQL) query (described in [MS-FQL2]). If this attribute is not present, the protocol server MUST behave as if "STRING" had been specified. If present for the GetQuerySuggestions (section 3.1.4.2) operation, the value MUST be "STRING".
Query.Context.LanguagePreference: The language for the context. The format of this field is the standard format for language fields in XML. For example, "en-us" represents US English.
Query.Context.Requery: Additional information about the search query in case this search query is a retry of a previous search query. It is unused and MUST be ignored by the protocol server.
Query.Context.OriginatorContext: Additional information about the protocol client. It is unused and MUST be ignored by the protocol server.
Query.Range: The range of the search results. Before sending the results of the search query to the protocol client, the protocol server MUST behave as if all search results are generated and ordered into a list. The Range element allows the protocol client to choose a subset of the search results from this list to be returned by the protocol server. If the Range element is not present, the defaults for Query.Range.StartAt and Query.Range.Count MUST apply.
Query.Range.id: The range identifier. This optional attribute is currently unused and, if present, MUST be ignored by the protocol server.
Query.Range.StartAt: The starting point of a range of search results, a StartAtType Simple Type (see section 2.2.5.4). Specifies the index of a search result in the list of all search results the protocol server returns as the first search result. The protocol server MUST use 1 as the index of the first search result. If this element is not present, the protocol server MUST use 1 as the default. If the total number of search results for a search query is less than the value of the StartAt element, the protocol server MUST return the status code ERROR_NO_RESULTS_FOUND in the case of the Query operation. The protocol server MUST ignore this element for the GetQuerySuggestions (section 3.1.4.2) operation.
Query.Range.Count: The number of search results the protocol client wants to receive, starting at the index specified in the StartAt element. The protocol server returns at most this many consecutive search results from the list of all search results, beginning at the index specified in the StartAt element. If this element is not present, the protocol server MUST use 10 as a default. If the total number of search results for a search query is greater than or equal to the value of the StartAt element, but less than the value of the StartAt element and the Count element combined, the protocol server MUST return as many search results as it can. Otherwise, the protocol server MUST return Count search results. For the GetQuerySuggestions (section 3.1.4.2) operation, this element is the number of query suggestions that the protocol client wants to receive.
Query.Keywords: Specifies more information about the tokens in the query text. It is currently unused and MUST be ignored by the protocol server.
Query.OfficeContext: Specifies more information about the protocol client. It is currently unused and MUST be ignored by the protocol server.
Query.Properties: The names of properties that the protocol server returns for each search result if the item in the search result has a value for that property. It only applies to search queries of type "STRING" and "FQL". If the type attribute of the QueryText element is "MSSQLFT", the contents of this element MUST be ignored.
In the case of the QueryEx operation, if this element has no child elements, and ResultProvider is "SharepointSearch", the protocol server MUST return the following default properties, if available:
WorkId
Rank
Title
Author
Size
Path
Description
Write
SiteName
CollapsingStatus
HitHighlightedSummary
HitHighlightedProperties
ContentClass
IsDocument
PictureThumbnailURL
In the case of the QueryEx operation, if this element has no child elements, and ResultProvider is "FASTSearch", the protocol server MUST return the following default properties, if available:
WorkId
Rank
Title
Author
Size
Path
Description
Write
SiteName
CollapsingStatus
HitHighlightedSummary
HitHighlightedProperties
ContentClass
IsDocument
PictureThumbnailURL
Url
ServerRedirectedUrl
FileExtension
SpSiteUrl
docvector
fcocount
fcoid
PictureWidth
PictureHeight
For a description of these properties, see section 3.1.1.1.
All properties specified here MUST be retrievable properties. If not all specified properties are retrievable properties, the protocol server MUST return the error code "ERROR_SERVER" in the case of the Query operation, or an equivalent SOAP fault in the case of the QueryEx operation.
If the HitHighlightedSummary property is not specified, the protocol server SHOULD return an empty value for the HitHighlightedProperties property, even if it is specified.<4>
If this element is used in the Query operation, the following additional restrictions apply:
If the protocol client specifies at least one property, it MUST also specify the Path property.
If it does not, the protocol server MUST return the status code "ERROR_BAD_QUERY".
For a discussion of properties, see the abstract data model in section 3.1.1.1. If the same property is listed more than once, the protocol server MUST return the status code "ERROR_BAD_QUERY"<5> in the case of the Query operation, or an equivalent SOAP fault in the case of the QueryEx operation.
If this element is used in the Query operation, the presence or absence of this element determines the output format that the protocol server uses in the Document element in the search results. See section 3.1.4.4.2.1 for details.
The protocol server MUST ignore this element for the GetQuerySuggestions (section 3.1.4.2) operation.
Query.Properties.Property: The property to return in the search results.
Query.Properties.Property.name: The property name.
Query.SortByProperties: The properties by which to sort the search results. It only applies to search queries where the type attribute of the QueryText element is "STRING" or "FQL". If the type attribute of the QueryText element is "MSSQLFT", this element MUST be ignored. If this element is not present, the protocol server MUST sort the search results in order of relevance to the search query, with the first search result being the most relevant. This element can contain more than one child element. In that case, the search results MUST be sorted as defined by the first SortByProperty element, with ties broken by the second SortByProperty element, and so on. If the same property is listed more than once, the protocol server MUST return the status code "ERROR_BAD_QUERY" in the case of the Query operation, or an equivalent SOAP fault in the case of the QueryEx operation.
The protocol server MUST ignore this element for the GetQuerySuggestions (section 3.1.4.2) operation.
Query.SortByProperties.SortByProperty: The property to sort the search results on, and how to sort on it. All actual information is contained in its attributes.
Query.SortByProperties.SortByProperty.name: The name of the property by which to sort the search results. If ResultsProvider is "FASTSearch", and the direction attribute is "FQLFormula", the value in this property MUST be according to a valid formula expression according to the following.
The evaluation MUST occur left-to-right and use standard mathematical-operator precedence. That is, functions and parenthetical groups MUST be evaluated first, multiplication and division operations MUST be performed next, and addition and subtraction operations MUST be performed last.
The expression element MUST NOT contain spaces.
The expression element supports the functions that are listed in the following table.
|
Function |
Description |
|---|---|
|
sqrt(n) |
The square root of n. |
|
exp(n) |
The exponential function that is equivalent to pow(2.71828182846,n). |
|
log(n) |
The natural logarithm of n. |
|
abs(n) |
The absolute value of n. |
|
ceil(n) |
The ceiling of n. That is, if n is not a whole number, round up to the next whole number. If n is a whole number, use n. |
|
floor(n) |
The floor of n. That is, if n is not a whole number, round down to the next whole number. If n is a whole number, use n. |
|
round(n) |
The rounding of n to the nearest whole number. |
|
sin(n) |
The sine of n radians. |
|
cos(n) |
The cosine of n radians. |
|
tan(n) |
The tangent of n radians. |
|
asin(n) |
The arcsine, in radians, of n. |
|
acos(n) |
The arccosine, in radians, of n. |
|
atan(n) |
The arctangent, in radians, of n. |
|
pow(x,y) |
The value of x raised to the power of y. |
|
atan2(y,x) |
A two-argument arctangent—the angle in radians between the positive x axis and the specified Cartesian coordinate (x,y). |
|
bucket(b,n1,…) |
An arbitrary number of refinement bins for the expression element b. Values that follow b (that is, n1, n2, n3, and so forth) are numbers that specify refinement bin names and limits. The lowest bin value (n1 if bins are specified in ascending order) MUST contain all the items for which b evaluates to a number that is less than n1. Subsequent refinement bins follow the same rule but MUST exclude the items that were included in previous bins. Values greater than the highest specified bin limit MUST be included in the highest bin. |
Query.SortByProperties.SortByProperty.direction: The direction in which to sort the property specified in the name attribute. The options are "Ascending" and "Descending" (see section 2.2.5.1). If ResultProvider is FASTSearch, "FQLFormula" MUST also be a valid option. If value is "FQLFormula", the sorting MUST be according to formula specified in the name attribute, Query.SortByProperties.SortByProperty.name. If the direction attribute is not given, the sort MUST be performed as if "Ascending" had been specified.
Query.ImplicitAndBehavior: Specifies whether all the tokens in the query are required. If "true", the protocol server MUST find all tokens in the search query in the crawled item for it to be part of the search results. If this element is set to "false", the protocol server MUST simply find any of the tokens in the crawled item for it to be part of the search result. If this element is not present, the protocol server MUST behave the same way as if "true" had been specified. Note that the protocol makes no guarantees about which items MUST be in the search results; this is configured in the implementation of the protocol server. The protocol server MUST ignore this element for the GetQuerySuggestions (section 3.1.4.2) operation, or if QueryText.type is "FQL".
Query.RelevanceModel:<6> Specifies the unique identifier of the ranking model that is used for this search query. MUST be a GUID as specified in section 2.2.5.2. If this element is not present, the protocol server MUST consistently use the same ranking model for every invocation, denoted a "default ranking model". If ResultProvider is "FASTSearch", the protocol server MUST ignore the value. The protocol server MUST ignore this element for the GetQuerySuggestions (section 3.1.4.2) operation.
Query.EnableStemming: Specifies whether inflectional forms of the given tokens are used to locate crawled items or not. If this element is set to "true", the protocol server SHOULD use inflectional forms to locate crawled items. If this element is set to "false", the protocol server MUST NOT use inflectional forms to locate crawled items. For example, search queries with query text of "car" will return crawled items containing the token "car" or the token "cars" if such items exist. If this element is not present, it depends on the language of the query, specified in the Query.Contest.QueryText.language attribute, whether the protocol server behaves as if this element had been set to "true" or to "false". Which language has which effect is an implementation detail. If the type attribute of the QueryText element is "STRING" or "FQL", this element applies to the whole query text. If the type attribute of the QueryText element is "MSSQLFT", this element applies to the FREETEXT predicate described in section 2.2.13.3.1.2. The protocol server MUST ignore this element for the GetQuerySuggestions (section 3.1.4.2) operation.
Query.EnableNicknames:<7> Specifies whether nickname forms of the given tokens are used to locate crawled items or not. If this element is set to "true", the protocol server SHOULD use nickname forms to locate crawled items. If this element is set to "false", the protocol server MUST NOT use nickname forms to locate crawled items. For example, search queries with query text of "steve" will return crawled items containing the token "steve" or the token "steven" if such items exist. These extra tokens MUST only be matched on managed properties that were created with the Nickname flag set. If this element is not present, the protocol server MUST behave as if "false" had been specified. If the type attribute of the QueryText element is "STRING", this element applies to the whole query text. If the type attribute of the QueryText element is "MSSQLFT", this element applies to the FREETEXT predicate described in section 2.2.13.3.1.2. The protocol server MUST ignore this element for the GetQuerySuggestions (section 3.1.4.2) operation, or if ResultProvider is "FASTSearch".
Query.EnablePhonetic:<8> Specifies whether phonetic representations of the given tokens are used to locate crawled items or not. If this element is set to "true", the protocol server SHOULD include crawled items that pronounce similar to the tokens entered. If this element is set to "false", the protocol server MUST NOT include crawled items that pronounce similar to the tokens entered. For example, search queries with query text of "steve" will return crawled items containing the token "steve", and also crawled items that contain tokens that pronounce similar to "steve", if such items exist. This phonetic matching MUST only be performed on managed properties that were created with the Pronunciation flag set. If this element is not present, the protocol server MUST behave as if "false" had been specified. If the type attribute of the QueryText element is "STRING", this element applies to the whole query text. If the type attribute of the QueryText element is "MSSQLFT", this element applies to the FREETEXT predicate described in section 2.2.13.3.1.2. The protocol server MUST ignore this element for the GetQuerySuggestions (section 3.1.4.2) operation, or if ResultProvider is "FASTSearch".
Query.TrimDuplicates: Specifies whether duplicates are removed before sorting, selecting, and sending the search results. If it is set to "true", the protocol server SHOULD perform duplicate result removal, if it is set to "false", the protocol server MUST NOT attempt to perform duplicate result removal. If this element is not present, the protocol server MUST behave as if "true" had been specified. If ResultProvider is "SharepointSearch", the protocol server MUST ignore any attributes when performing duplicate result removal. The protocol server MUST ignore this element for the GetQuerySuggestions (section 3.1.4.2) operation.
Query.TrimDuplicates.onproperty: Specifies the name of a managed property to use for duplicate result removal. The managed property MUST be of type integer. If this attribute is not present, the protocol server MUST behave as if "documentsignature" had been specified. The protocol server MUST list all available managed properties in the FASTSearchProperties table (section 3.1.4.3.2.2.2).
Query.TrimDuplicates.keepcount: Specifies the number of duplicates to return in the search results. If neither this attribute nor the TrimDuplicates.includeid attribute are present, the protocol server MUST behave as if a value of "1" had been specified for TrimDuplicates.keepcount.
Query.TrimDuplicates.includeid: Specifies a common value for a group of duplicates. This value corresponds to the value of the managed property fcoid that is returned in query results, and the protocol server MUST only return search results that have fcoid equal to this value. If both TrimDuplicates.keepcount and TrimDuplicates.includeid attributes are present, the protocol server MUST behave as if only the TrimDuplicates.includeid has been specified.
Query.IgnoreAllNoiseQuery: Specifies how to respond to queries where one, or more, of the full-text predicates contains only noise words. This element only applies to search queries where the type attribute of the QueryText element is "MSSQLFT". If this element is set to "true", those predicates MUST be ignored and the query MUST run as if those predicates evaluated to "true". If this element is set to "false", the search query MUST fail with a status code of "ERROR_ALL_NOISE" in the case of the Query operation, or an equivalent SOAP fault in the case of the QueryEx operation. This element MUST be ignored if the type attribute of the QueryText element is "STRING". If this element is absent, the protocol server MUST behave as if "true" had been specified. If ResultProvider is "FASTSearch", the protocol server MUST ignore the value. The protocol server MUST ignore this element for the GetQuerySuggestions (section 3.1.4.2) operation.
Query.IncludeRelevantResults: Specifies whether the RelevantResults Table is returned or not (see 3.1.4.5.2.2.1). If "true", the protocol server MUST include the RelevantResults Table in the response. Otherwise, the protocol server MUST NOT include the RelevantResults Table in the response. If this element is absent, the protocol server MUST behave as if "true" had been specified. This element is only valid for the QueryEx operation; it MUST be ignored for the Query operation. The Query operation MUST return the most relevant crawled items regardless of the presence and state of this element. The protocol server MUST ignore this element for the GetQuerySuggestions (section 3.1.4.2) operation.
Query.IncludeHighConfidenceResults: Specifies whether the HighConfidenceResults Table is returned or not (see 3.1.4.5.2.2.3). If "true", the protocol server SHOULD include the HighConfidenceResults Table in the response. If the value is set to "false", the protocol server MUST NOT include high confidence results in the response. If it is absent, the protocol server MUST behave as if the value is set to "false". This element is only valid for the QueryEx operation; It MUST be ignored for the Query operation. The Query operation MUST NOT return high confidence results regardless of the presence and state of this element. If ResultProvider is "FASTSearch", the protocol server MUST ignore the value. The protocol server MUST ignore this element for the GetQuerySuggestions (section 3.1.4.2) operation.
Query.IncludeSpecialTermResults: Specifies whether the SpecialTermResults Table is returned or not (see 3.1.4.5.2.2.2). If the value is set to "true", the response MUST include the SpecialTermResults Table. Otherwise, the response MUST NOT contain the SpecialTermResults Table. If the element is absent, the protocol server MUST behave as if "false" had been specified. This element is only valid for the QueryEx operation; It MUST be ignored for the Query operation. The Query operation MUST NOT return best bets regardless of the presence and state of this element. The protocol server MUST ignore this element for the GetQuerySuggestions (section 3.1.4.2) operation.
Query.PreQuerySuggestions: Specifies whether to get pre-query suggestions. If the value is "true", the protocol server MUST return pre-query suggestions; if the value is "false", the protocol server MUST return post-query suggestions. If this element is not present, the protocol server MUST behave as if "false" had been specified. This element is only valid for the GetQuerySuggestions (section 3.1.4.2) operation; it MUST be ignored for the Query and QueryEx operations.
Query.HighlightQuerySuggestions: Specifies whether to highlight emphasized parts of the suggestion. If the value is "true", the protocol server MUST enclose parts of the suggestions that it wants to emphasize in an open and closed (<b>) tag, such as <b>word</b>; if the value is "false" the protocol server MUST NOT emphasize suggestions with <b> tags. If this element is not present, the protocol server MUST behave as if "false" had been specified. This element is only valid for the GetQuerySuggestions (section 3.1.4.2) operation; it MUST be ignored for the Query and QueryEx operations.
Query.CapitalizeFirstLetters: Specifies whether to capitalize a token in query suggestions when a token is present in the query text. If value is "true", the protocol server MUST capitalize the token; if the value is "false", the protocol server MUST NOT capitalize the token. The exact way of capitalizing tokens is an implementation detail. If this element is not present, the protocol server MUST behave as if "false" had been specified. This element is only valid for the GetQuerySuggestions (section 3.1.4.2) operation; it MUST be ignored for the Query and QueryEx operations.
Query.ResultProvider:<9> This element determines which result provider is used by the protocol server. Valid values are "SharepointSearch" or "FASTSearch"<10>. If the element is not present, or a different value is specified, the protocol server MUST behave as if "SharepointSearch" had been specified. This value MUST NOT be case-sensitive.
Query.EnableSpellcheck: Specifies how the protocol server suggests a different spelling of the search query. If the EnableSpellcheck element is present and the value is "Off", the protocol server MUST NOT suggest a different spelling of the search query. If the element is present and the value is "Suggest", the protocol server MUST suggest a different spelling if there is a good chance that the spelling suggestion will increase the quality of the search results. If there is a spelling suggestion, the protocol server MUST set it in the extended property SpellingSuggestion (see section 3.1.4.5.2.2). If the element is present and the value is "On", the protocol server MUST automatically modify the query terms before evaluating the query and returning results if there is a good chance that the modified query will increase the quality of the search results. If the query was modified, the protocol server MUST set the modified query in the extended property QueryModification (see section 3.1.4.5.2.2). If the element is present and the value is other than "Off", "Suggest", or "On", the protocol server MUST return a SOAP fault. If not present, the protocol server MUST behave as if the protocol client specified the value "Off". If ResultProvider is "SharepointSearch", the protocol server MUST ignore the value. This element is only valid for the QueryEx operation; it MUST be ignored for the Query and GetQuerySuggestions operations.
Query.ResubmitFlags: The parent element for one or more ResubmitFlag elements. This element and its sub-elements are only valid for the QueryEx operation; they MUST be ignored for the Query and GetQuerySuggestions operations.
Query.ResubmitFlags.ResubmitFlag: Specifies how the protocol server behaves if the protocol server returns no results from the original query. If not present or an attribute with ResubmitFlag.value is set to "NoResubmit", the protocol server MUST return with no results. If present and no element with ResubmitFlag.value is set to "NoResubmit", the protocol server MUST re-evaluate the query before returning with no search results to the client. If search query is re-evaluated, the protocol server MUST set the new search query in the extended property QueryModification. If ResultProvider is "SharepointSearch", the protocol server MUST ignore the value.
Query.ResubmitFlags.ResubmitFlag.value: MUST be one of the following values:
|
Value |
Meaning |
|---|---|
|
NoResubmit |
The protocol server MUST return with zero results. Protocol server MUST ignore other ResubmitFlag elements. |
|
EnableSpellcheckOnResubmit |
The protocol server MUST behave as if EnableSpellCheck is set with a value of "On" when re-evaluating the query. |
|
EnableSpellcheckSuggestOnResubmit |
The protocol server MUST behave as if EnableSpellCheck is set with a value of "Suggest" when re-evaluating the query. |
|
EnableStemmingOnResubmit |
The protocol server MUST behave as if EnableStemming is set to "true" when re-evaluating the query. |
|
AddSynonymsAutomatically |
The protocol server MUST automatically add synonyms to query terms when re-evaluating the query. |
Query.UserContext: The parent element for user context data. If ResultProvider is "SharepointSearch", this element and all sub-elements MUST be ignored by the protocol server.
Query.UserContext.includeuserprofile: Specifies that protocol server appends user specific context data to query before evaluating and returning search results. If present and value is "true", the protocol server MUST append user context to query. If this attribute is absent, the protocol server MUST behave as if "true" had been specified.
Query.UserContext.UserContextData: Specifies the query context. If present, and best bets and visual best bets are requested with IncludeSpecialTermResults and a search setting context is associated with best bets and visual best bets on the protocol server, the protocol server MUST only return best bets and visual best bets where all key-value pairs in the query context match all key-value pairs in the defined search setting context. How to match these key-value pairs is specific to the implementation of the protocol server. If present, and best bets and visual best bets are requested but have no search setting context associated with them, the value in query context MUST be ignored, and best bets and visual best bets with no associated search setting context MUST be returned.
The following is an ABNF description of the UserContextData syntax. ABNF is specified in [RFC5234].
-
usercontextdata = contextgroup *("|" contextgroup ) ["|"] contextgroup = key ":" [valuesplitter] ":" value key = escaped-string valuesplitter = escaped-string value = escaped-string *(valuesplitter escaped-string) escape-sequence = "\" (":" / "\" / "|") escaped-string = *(escape-sequence / NONESCAPED) NONESCAPED = %x20-39 / %x3B-5B / %x5C-7B / %x7D-7E
"usercontextdata" MUST consist of one to more "contextgroup"s separated by a "|" character. Each "contextgroup" MUST consist of a "key", an optional "valuesplitter", and a "value", separated by a ":" character. "key" and "valuesplitter" MUST be "escaped-string" which is any string of ASCII characters with the limitation that the characters ":","|" and "\" MUST be escaped as follows: "\:", "\|" and "\\". The "key" MUST contain the name of a search setting context. The "value" can be a single "escaped-string", or multiple strings separated by "valuesplitter".
Example: UserContextData = SPS-Location::Redmond|SPS-Responsibility:;:value1;value2
In this example UserContextData value contains two context groups;
Context group 1:
Key is "SPS-Location"
Single value is "Redmond"
Context group 2:
Key is "SPS-Responsibility"
Value splitter is ";"
Multiple values are "value1" and "value2" which are separated by the value splitter string
If ResultProvider is "SharepointSearch", the protocol server MUST ignore the value.
Query.FindSimilar: The parent element for searching for results that are similar to already retrieved results. If present, the FindSimilar.SimilarTo element MUST be specified. If ResultProvider is "SharepointSearch", the protocol server MUST ignore the value.
Query.FindSimilar.SimilarTo: Specifies the document vector used for similarity comparison. The document vector indicates the most important terms in a search result, and the corresponding weight. The weight is a float value between 0 and 1, where 1 indicates highest relevance. Format of the document vector is specified in SimilarToType (see 2.2.5.6), and the document vector of a search result is found in the property docvector. If ResultProvider is "SharepointSearch", the protocol server MUST ignore the value.
Query.FindSimilar.SimilarType: Specifies how the protocol server transforms the query when SimilarTo is set. The protocol server MUST append the terms in SimilarTo to the QueryText based on SimilarType. If value is "Find", the protocol server MUST add terms in SimilarTo using the OR operator. If value is "Refine", the protocol server MUST add terms in SimilarTo using the AND operator. If value is "Exclude", the protocol server MUST add terms in SimilarTo using the AND NOT operator. See section 2.2.11.2 for a specification of Keyword Query operators. If value is "None", the protocol server MUST NOT transform the query text. If the value is any other string, the protocol server MUST return a SOAP fault with the Code element set to "soap:Receiver" and the Reason element set to "System.ArgumentException", as specified in [SOAP1.1] section 4.4 or [SOAP1.2-1/2007] section 5.4. If not set, but SimilarTo is set, the protocol server MUST behave as if "Find" was specified. If set, but SimilarTo is not set, the protocol server MUST ignore this value and MUST NOT transform the query text. If ResultProvider is "SharepointSearch", the protocol server MUST ignore the value.
Query.FindSimilar.SortSimilar: Specifies sorting of search results based on similarity of the results. If present and value is "true", the protocol server SHOULD sort according to similarity. How to sort according to similarity is specific to the implementation of the protocol server. If present, and value is "false" and SortByProperties is specified, sorting MUST be by SortByProperties. If SortByProperties is not specified, sorting MUST be by rank. If not present, but SimilarTo is specified, sorting MUST be by similarity. If ResultProvider is "SharepointSearch", the protocol server MUST ignore the value.
Query.IncludeRefinementResults: The parent element for refinement results. This element and its sub-elements are only valid for the QueryEx operation; they MUST be ignored for the Query and GetQuerySuggestions operations.
Query.IncludeRefinementResults.Refiners: The parent element for list of refiners the protocol server SHOULD return based on query results. If the Refiners element is absent or empty, the protocol server MUST NOT return refinement results. If ResultProvider is "SharepointSearch", the protocol server MUST ignore the value.
Query.IncludeRefinementResults.Refiners.Refiner: Specifies a refiner the protocol server returns based on query results. The following is an ABNF description of the Refiner syntax. ABNF is specified in [RFC5234].
-
refiner = property-name ["(" refiner-settings ")"] refiner-settings = 1(refiner-setting) *("," refiner-setting) refiner-setting = discretize / sort / cutoff discretize = "discretize=manual" 2*["/" discretize-bucket] discretize-bucket = date-date [date-time] / 1*digit year = 4digit month = 2digit day = 2digit hour = 2digit minute = 2digit second = 2digit / 2digit "Z" date-date = year "-" month "-" day date-time = hour ":" minute ":" second sort = "sort=" sort-algorithm "/" sort-direction sort-algorithm = "frequency" / "name" / "number" sort-direction = "descending" / "ascending" cutoff = "cutoff=" cutoff-frequency "/" cutoff-minbuckets "/" cutoff-maxbuckets cutoff-frequency = 1*digit cutoff-minbuckets = 1*digit cutoff-maxbuckets = 1*digit property-name = 1*alpha ; MUST be name of refinable property
Refiner MUST be specified by using the name of a managed property that has an associated refiner, and each refiner can be specified with additional refiner parameters.
The "discretize" parameter specifies the custom buckets the protocol server returns for a refinable property that is numeric or of type datetime. All buckets MUST be of same type, that is either datetime or numeric.
The "cutoff" parameter specifies that the protocol server limits the amount of refiner results it returns:
"cutoff-frequency" specifies that the protocol server does not return a refinement value if the number of occurrences of the refinement value in a result set is less than or equal to this value.
"cutoff-minbuckets" specifies the minimum value for frequency cutoff. If the number of unique refinement values for the query is less than this value, there is no frequency cutoff, and the protocol server MUST return all refinement values. When cutoff-frequency is used, this parameter specifies a minimum number of unique refinement values that the protocol server MUST return regardless of the number of occurrences.
"cutoff-maxbuckets" specifies the maximum number of unique refinement values (buckets) that the protocol server returns for a navigator.
The "sort" parameter defines how the buckets within a refiner of type string are sorted;
"sort-algorithm" specifies how the protocol server orders the refinement buckets.
"frequency" specifies that the order MUST be by occurrence within the refinement bucket.
"name" specifies that the order MUST be by label name.
"number" specifies that the protocol server treats the strings as numeric and use numeric sorting.
"sort-direction" specifies the sorting direction to be descending or ascending.
If ResultProvider is "SharepointSearch", the protocol server MUST ignore the value.
Query.IncludeRefinementResults.MaxShallowRefinementHits: Specifies the number of results to be used to calculate refinement results. The protocol server MUST apply this only to refiners that are specified to have shallow refinement. If not set, a default value of 100 MUST be used by protocol server. If ResultProvider is "SharepointSearch", the protocol server MUST ignore the value.
Query.RefinementFilters: The parent element for refinement filters. If provided, RefinementFilter elements specify a drill down into a search result. If ResultProvider is "SharepointSearch", the protocol server MUST ignore this element and all sub-elements. This element and its sub-elements are only valid for the QueryEx operation; they MUST be ignored for the Query and GetQuerySuggestions operations.
Query.RefinementFilters.RefinementFilter: Specifies a refinement token representing a query refinement. Refinement tokens are returned as part of the RefinementResults table (see 3.1.4.5.2.2.4) for the previous query.