The Search API provides powerful functions for searching and organizing medical content. The search method supports the OpenSearch protocol, plus extensions that add power and flexibility.
Common Arguments
There are several arguments that are common to all the search functions.
- corpus
Identifies the documents that will be searched. Each corpus is defined and named in a server-side configuration.
- query
- A plain-text query string, suitable for passing a question entered by a user.
- fields[]
When a query consists of multiple fields, the fields[] argument may be used instead of or in addition to the query argument. Data type is TextField.
- refinements[]
This argument is used to add structured refinements to the query.
- startIndex
- The 1-based index into the hit list of the first hit that will be returned. The default is 1.
- hitsPerPage
- The maximum number of hits that will be returned. The default is 20.
- selectivity
- For complex and naturally posed questions, the selectivity argument is used to specify a statistical cutoff. Documents which score below the cutoff will not be included in the hit list. The selectivity argument specifies the number of standard deviations of the hit score above or below the mean.
- boostRecent
- This factor controls how much the hit scores are influenced by the document publication date. The default value should give reasonable behavior, but in some cases it is desirable to increase this factor, or turn it off by setting it to 0.
The search functions have two modes of operation:
- hitsPerPage
- The top hitsPerPage are returned. This is the default search mechanism.
- selectivity
- The documents which are most relevant to the input on a statistical basis are returned. The selectivity parameter indicates the minimum relevance threshold in terms of the number of standard deviations above or below the mean relevance.
Search
Searches for documents matching a query and optional refinements. The search covers the content collections identified by the corpus section of the URL path. If the requested response format is XML or JSON, the result is a SearchResults. If the requested response format is Atom, the response is in the OpenSearch Atom format
URL
/search/search/[corpus]
Parameters
Common arguments, plus:
- summary
If present, the DocSummary.summary field will be populated.
- content
If present, the DocSummary.content field will be populated.
- snippet
If present, the HitSummary.snippets field will be populated.
- snippetCount
- If snippets are enabled, determines how many snippets will be found for each document. Default is 3.
- snippetSeparator
- If snippets are enabled, specifies a text string that will be rendered in between snippets. Default is ... (3 dots).
- render
If present, search terms that are present in the summary or content will be marked up, surrounded by the the openDelim and closeDelim. The marked-up result will populate the DocSummary.content field.
- openDelim
Opening delimiter for a search term in the document. Default is <strong>
- closeDelim
Closing delimiter for a search term in the document. Default is </strong>
Examples
- Search the dailyapple/research corpus for the top 20 results about diabetes
/search/search/dailyapple/research?query=diabetes&hitsPerPage=20
- Search the dailyapple/research corpus, with the response in OpenSearch Atom format.
- Search the dailyapple/news corpus, marking up occurrances of the search terms. Note that the summary field contains the plain text summary, and content contains the rendered summary.
/search/search/dailyapple/news.atom?query=diabetes&summary&render
- Search the dailyapple/news corpus, finding 3 snippets and marking up occurrances of the search terms.
/search/search/dailyapple/news.atom?query=diabetes&snippet&render
Rank
Determines a ranked list of the most significant concepts within a hit list. This function may be used to dynamically create a filter list or topic cloud for a set of search results.
Frequently occurring concepts which share a common parent may be "rolled up" to their parent. For example, if the search results contain many different types of anti-hypertensive agent, the ranking will show Anti-Hypertensive Agent as a top-ranking concept even if none of the synonyms of anti-hypertensive agent are explicitly used in the documents.
URL
/search/rank/[corpus]
Parameters
Common arguments, plus:
- subset
- Identifies a named subset. Only concepts that belong to this subset will be included in the result.
- conceptIds[]
- As an alternative to specifying a subset, a specific list of concept ids may be provided. Only these concepts and their descendents will be included in the result.
- excludeConceptIds[]
- An optional list of concepts that will not be included in the result.
- considerHitScore
- Whether concepts that occur in higher-scoring hits should have more influence over the ranking. Default is true.
Examples
- Rank the DrugsByFunction concepts for the top 200 diabetes hits in the dailyapple/research corpus. Concept 14259 is Insulin.
/search/rank/dailyapple/research?query=diabetes&subset=DrugsByFunction&hitsPerPage=200
- Rank the DrugsByFunction concepts, except insulin, for the top 200 diabetes hits in the dailyapple/research corpus.
Count
Returns the number of hits available for a search.
Bin
Given an input collection of bins and the standard search arguments, this method returns the number of documents that belong to each bin.