Using the Search Engine
To perform a simple search in InterSystems documentation, enter search terms in the Search: field near the top right of the page and then press Enter.
For advanced search facilities, click the Search: label itself, which displays the Key Word Search page and the Recent searches list. This page includes the following elements:
Search words — Enter search terms here. Previous search terms with the same spelling will appear in a drop-down list as you type, so you also may select one from the list if you would like to search for it again.Note:
This is also referred to as the “content field.”
Find topics with menu: choose all words or any word.
Search type — use the menu to choose Free-text, Exact match (except for case), or Exact match (including case).
The Search button — Click to search.
The Reset button — Click to empty the content field and return to default search rules. Selecting this button will also display the Recent searches list.
The Search the Web button — Click to use the terms specified in the content field for a Google search of the Web.
In addition to the above elements, there are three optional menus with which you can restrict your search further. They include:
Products — Select a product or product line from the list, or keep the default all products. If you are searching an instance of Ensemble or of a HealthShare product, this menu allows you to search only within the documentation of one product or product line. This option is helpful if you want to search, for example, for information about an Ensemble setting. Many topics about Ensemble might not actually contain the word “Ensemble,” so simply searching for Ensemble setting may not return the result you want. Instead, choose to search only Ensemble documentation for the word setting, and then the search only displays results related to Ensemble that include the string setting.Note:
If you only have Caché documentation installed, this menu does not appear.
Books and articles — Select the title of a book, or keep the default all books and articles. If you know which book contains the information you are seeking, use this to restrict the search to results within that book only. If you have selected a product from the previous menu, this list will contain books and articles from that product only.
Tags — Select a tag from the list, or keep the default all tags. Tags are a useful way to narrow your search if you are looking for a topic that spans multiple books but also might return an unwieldy number of hits. For example, if you search for just SQL, the search will return hundreds of results. If you instead select the SQL tag and enter a related search term in the content field, the search returns only topics that are relevant to SQL, rather than any reference to it.
If you are having difficulties using documentation search, you may have insufficient privileges. You can read and navigate the online documentation with any level of database access, but in order to use the online documentation Search: feature, your account must have Write privileges in the DOCBOOK database. Most accounts do have this access, but if you run into trouble with searches, you should adjust your privilege level, use a different account that does have the privilege, or contact the administrator in your organization for this instance of your product.
Default Search Rules
The following are the default rules for searches:
A search can include one or more terms.
The search engine returns results that contain all terms.
The default search is not case-sensitive. For example, searches for SET, Set, and set yield the same results.
If the search string exactly matches the title of a section or an entry in a definition list, this hit appears at the beginning of the results and is highlighted.
All other results are grouped by topic, and display up to nine hits for the search term within that topic. A topic could be a chapter, an appendix, or an entry in a reference, such as this entry on $PIECE. If there are additional hits within that topic, the page will display “Topic has more results.” Each finding is displayed below its closest parent heading to help you determine which result will be the most useful for your search.
The order of search results is primarily determined by the topic (see previous bullet) in which they are found. Each topic has an overall ranking, such that topics of more general interest appear before those that have a narrower scope. To a lesser degree, the number of matches in a given topic also affects the ranking of search results.
Finding Topics with All or Any Words
Use the first menu to the right of the content field to choose between searching either for text that includes all or text that includes any of the specified search terms. The default setting is to find results that include all terms; if you do not know the exact term you are seeking, enter several synonyms and select Find topics with any word to determine which term the documentation uses. For example, if you are not sure whether to search for the word transform or the word translate, enter both into the content field and select the option Find topics with any word.
Choose a search type from the second menu. The default search type is Exact match (except for case), which searches for an exact string but ignores the case of the search term.
If you do not know the case of a search term, use Exact match (except for case). If you know the exact capitalization of a term, select Exact match (including case) to further restrict results.
The search engine also supports the Caché Free-text search (sometimes called a “stemmed search”). This kind of search is based on an extensive list of related forms of words. For any word appearing in the list, the search engine takes the stem of each word provided and finds all matches associated with that stem. For example, save, saving, and saved all yield the same results. The order of the results is the same for all variants of a particular stem (for example, regardless of whether a search is for save or saving). Note that words which contain the same string are not necessarily stemmed variations of each other. For example, a stemmed search for the word “user” does not return results including username.
The search engine supports stemmed search for most words. For words with forms that are relevant to InterSystems products, search may not support all forms of stemming. For example, include and including return different sets of results, since “include” is a reserved word with a specific meaning in some programming languages.
For details on free-text search, see the section “Using Free-text Search” in the chapter “Querying the Database” of Using Caché SQL.
When using free-text search, the results may begin with one or more featured links that have been flagged as notable results for the search term. Exact search disables this feature. Also note that free-text search does not currently return results with the matches highlighted.
Searching for Symbols and Special Characters
The free-text search will ignore non-alphanumeric symbols, with the exception of the special characters “$” and “%,” which have special meaning in Caché commands and keywords. If your search text includes non-alphanumeric symbols such as a caret (^), use exact search to make sure they are included in the search query. For example, if you are searching for the routine ^DATABASE, but you do not want to do a general search for the word database, use exact search to narrow your results.
The search engine indexes words that include é as if they contained e; it also indexes words that include ñ as if they contained n. Hence, to search for the word “Caché”, simply enter Cache for the search; to search for the word “cache,” use cache. Similarly, use Espanol instead of Español.
If you are using exact match, do not put quotation marks (“”) around the search term unless they are, themselves, part of the search item.
Searching for Common Terms
The various search rules, taken together, offer a powerful means of locating information in InterSystems documentation. They can also sometimes cause unexpected search results. If you search for a common word, such as and or the, the search may return fewer results than you expected. This is because the search returns only the first 10,000 results, some of which are too short to be useful, so you will have only the topics that include those. If you are having difficulty finding a common word, try using other related terms that will return more specific results.
To repeat a previous search, select a link from the Recent searches list. These links appear if you click the Search label at the top-right corner of a documentation page, or if you select the Reset button.
This list displays a link for each past search, follower by the number of results for that search, a specific description of the search (see “URL Parameters,” later in this chapter).
To help you create searches programmatically, the search page DocBook.UI.SearchPageZen.cls supports the URL Parameters, which are as follows:
Specifies the search term or terms.
Corresponds to the first menu. For this parameter, the value AND corresponds to Find topics with all words. The value OR corresponds to Find topics with any word.
Corresponds to the Search Type menu. For this parameter, 1 corresponds to Free-text search, 2 corresponds to Exact match (except for case), and 3 corresponds to the Exact match (including case).
Corresponds to the product menu.
If you also select a book or article, the product becomes redundant, and therefore is no longer included in the URL parameters.
Corresponds to the books and articles menu. For this parameter, the allowed values are the internal identifiers of the books and articles. Note that the list includes these identifiers in parentheses for your convenience.
Corresponds to the tags menu.
For the Product, Book, and Tags parameters, the allowed values depend upon what is present in the DOCBOOK database. Currently each of these parameters accepts only a single value.