ARCHIVED: KB web services: Searching the KB

You may search KB documents via web services. You may use this to seamlessly integrate Knowledge Base search functionality into your own site, if you wish. If you have a dedicated domain class for your documents, you may also use this to provide search functionality for just your documents.

• Common values returned when searching the KB
• Searching the KB with SOAP
• Searching the KB with REST
• Errors

Common values returned when searching the KB

Both the SOAP and REST interfaces for searching the KB return some specialized pieces of information:

Parsed query

The parsed query is a human-readable string which should indicate to a user how the search engine handled the request. For example, if you search for windows vista, the parsed query may come back as 'windows', and 'vista', illustrating for a user that the search was parsed as two separate words.

Nonexistent terms

This is a list of words or phrases that do not exist in any KB documents. Individual terms will be separated by spaces. Display these terms to users to help refine searches.

Ignored terms

This is a list of words that were in the provided search query, but that the search engine ignored. These are most often common words like "a," "an," and "the." The words in the list will be separated by spaces.

Score

Internally, the KB search engine generates a floating-point number to indicate how well a document matches a given query. The documents are sorted and returned in order of their relative scores, with higher scoring documents returned earlier in the search results. The numbers have no inherent meaning, and may not be consistent between different versions of the search engine; as such, you should not use them in any meaningful way.

docid, domain, visibility

These pieces of document metadata are explained in the ARCHIVED: Web Services glossary.

Searching the KB with SOAP

doSearchResults doSearch(string authKey, string whichKB, string query, string advanced, array domains, string audience, string archived, integer start, integer size)

Performs a search for query. whichKB is the domain class to use. advanced is a flag for a deprecated feature; you should provide an empty string. Documents contained in the domains listed in domains will be included in your search. audience specifies the intended audience for the search results; this may affect which titles are returned. archived should be "1" if you want archived documents to appear in your search, or the empty string otherwise.

start and size let you control which search results, out of all those available, are actually returned by the server. start specifies where the search results should start being returned, and size indicates how many results should be returned. For example, when start is 1 and size is 10, you'll receive the first ten results. Then, you can get the next ten results by performing the same search with start set to 11 and size to 10. By limiting the number of results returned, you can get a response back from the server faster.

The doSearchResults structure which is returned has a number of fields which provide information about search results. query provides the parsed query. numResults is an integer indicating how many results are available for this search query. Note that this number is not affected by the start and size values provided in the search call. version specifies the version of the search engine that performed this search. advanced is deprecated and should be ignored. noExist lists nonexistent terms. ignored lists ignored terms. start indicates where these search results begin; this may be different from the start value you provided if that was too small or too large. There are then five fields that return ordered arrays:

documents

An array of strings, listing docids for documents that match this search.

titles

An array of strings, providing the titles for the documents listed in documents.

domains

An array containing other arrays. Each array, in turn, contains strings, listing domains for the documents listed in documents.

visibility

This array contains strings, naming the visibilities of the documents listed in documents.

scores

An array of scores for the documents listed in documents.

The arrays are all associative. So, the second string in titles is the title for the second document listed in document. The fourth document in documents is in the domains listed in the fourth array of domains, and so on.

Searching the KB with REST

GET /REST/v0.2/whichKB/search/audience?query=query[&domain=domain][&archived=true]

The above URL provides a base for returning search results. whichKB is the domain class to use. audience specifies the intended audience for the search results; this may affect which titles are returned.

The search string and related information are passed via query parameters. query provides the search text itself. Documents from the domain given in domain will be included in your search; you may specify this value more than once to search from multiple domains. If archived is specified and not 0, your search will include archived documents. start and size let you control which search results, out of all those available, are actually returned by the server. start specifies where the search results should start being returned, and size indicates how many results should be returned. For example, when start is 1 and size is 10, you'll receive the first ten results. Then, you can get the next ten results by performing the same search with start set to 11 and size to 10. By limiting the number of results returned, you can get a response back from the server faster.

This method returns a specialized XML document that represents your search results. None of the tags in this document have any attributes. The root node is kbsearch. Its children, and their respective content, are as follows:

query

The parsed search query.

noexist

The list of nonexistent terms.

version

The version of the search engine that generated these results.

ignored

The list of ignored terms.

advanced

This tag is deprecated and should be ignored.

start

The location where these search results begin, relative to all the possible search results for this query. This may be different from the start value you provided if that was too small or too large.

numResults

An integer indicating how many results are available for this search query. Note that this number is not affected by the start and size values provided in the search call.

results

This tag may contain any number of result tags. Each result tag represents a search result. The tags will be ordered, from the highest-ranked result to the lowest. The children of the result tag, and their respective content, are as follows:

docid

The docid for this document.

title

This document's title.

score

The score for this document in this search.

visibility

This document's visibility.

domains

domains contains one or more domain tags. Each of those names a domain to which this document belongs.

Errors

The following errors may occur when trying to perform a search: