Query Examples - Concept Suggestion Request Service
Query Examples - Concept Suggestion Request Service
The following call shows the default using just the "searchString" parameter with a search for the text 'aspirin':
<server>/extractor/api/suggest?projectId=<ID>&language=en&numberOfConcepts=25&searchString=aspirin
This example shows the same thing but uses the extended notation.
Although there is just one parameter you have to use an index value for the array of parameters. We use '0' here but you can use any integer value.
<server>/extractor/api/suggest?projectId=<ID>&language=en&numberOfConcepts=25&searchParameters[0].searchString=aspirin
The last example in this section applies boosting to the labels and returns similar results to the previous examples.
Three search parameters are used for preferred label, alternative label and hidden label respectively. The search string is the same in all cases, but the boost factors are different. This simulates the SKOS boost scoring which is used by default. The SKOS boosting itself thus is switched of so the boosts can take effect.
<server>/extractor/api/suggest?projectId=<ID>&language=en&searchParameters[0].labelType=PREF_LABEL&searchParameters[0].boost=3&searchParameters[0].searchString=aspirin&searchParameters[1].labelType=ALT_LABEL&searchParameters[1].boost=2&searchParameters[1].searchString=aspirin&searchParameters[2].labelType=HIDDEN_LABEL&searchParameters[2].boost=1&searchParameters[2].searchString=aspirin&useSkosBoost=false
As shown in the last example of the previous section multiple search strings can be used. When they are different, then concepts will be returned that contain any of the search strings. The scoring will take into account how much the query matches the retrieved concepts, which means, if you search for two terms then concepts that contain both of them, will be returned at higher positions. The parameters are combined using a logical OR, so also concepts containing only one of the search strings will be returned (but with lower scores).
<server>/extractor/api/suggest?projectId=<ID>&language=en&numberOfConcepts=100&searchParameters[0].searchString=Alzheimer&searchParameters[1].searchString=Vaccines
With boosting the order of the returned results can be further influenced, here 'Alzheimer' gets a higher boost than 'Vaccines'. Thus concepts that contain this search string will appear at higher positions:
<server>/extractor/api/suggest?projectId=<ID>&language=en&numberOfConcepts=100&searchParameters[0].searchString=Alzheimer&searchParameters[0].boost=5&searchParameters[1].searchString=Vaccines&searchParameters[1].boost=1&useSkosBoost=false
The interpretation of the search string can be influenced with the parameter "matchingStrategy".
The option "REGEX" lets you use regular expressions.
The following will search all concepts with labels that contain "alpha" + "-" + "at least two numbers". Internally the Solr regex functionality is used, see for example the following page of the Solr documentation for further information.
<server>/extractor/api/suggest?projectId=<ID>&language=en&searchParameters[0].matchingStrategy=REGEX&searchParameters[0].searchString=.*%5BaA%5D%5BlL%5D%5BpP%5D%5BhH%5D%5BaA%5D%5C-%5B0-9%5D%5B0-9%5D.*
Note
Parameters have to be URL encoded. In many cases this is not relevant, but for regular expressions this is essential for the query to work. The actual regular expression is ".*[aA][lL][pP][hH][aA]\-[0-9][0-9].*".
Expressions are interpreted case sensitive. In order to obtain a case insensitive search you can use the notation shown here while providing upper and lower case characters.
Using the "SENSITIVE" strategy, characters will be used in the search that are usually ignored, for example "-".
The following example will search concepts that contain the string 'aci-':
<server>/extractor/api/suggest?projectId=<ID>&language=en&searchParameters[0].matchingStrategy=SENSITIVE&searchParameters[0].searchString=aci-
The default behaviour will also return concepts that contain for example 'acid', because "-" is ignored:
<server>/extractor/api/suggest?projectId=<ID>&language=en&searchParameters[0].searchString=aci-
The "EXACT" strategy only matches concepts that contain a label that is exactly the same as the search string (no sub-string search).
This will only retrieve concepts that contain a label 'Aspirin' yet combinations with 'Aspirin' inside the label are ignored:
<server>/extractor/api/suggest?projectId=<ID>&language=en&searchParameters[0].matchingStrategy=EXACT&searchParameters[0].searchString=Aspirin
You can use the "labelType" and "customLabel" parameters to search over custom labels.
The call below returns concepts that contain
'chlor' in the altLabel
'methyl' in the custom label with URI <http://id.nlm.nih.gov/mesh/vocab#casn1_label>
'insects' in the custom label with URI <http://id.nlm.nih.gov/mesh/vocab#annotation>
<server>/extractor/api/suggest?projectId=<ID>0&language=en&numberOfConcepts=100&searchParameters[0].labelType=CUSTOM_LABEL&searchParameters[0].customLabel=http://id.nlm.nih.gov/mesh/vocab%23casn1_label&searchParameters[0].searchString=methyl&searchParameters[1].labelType=ALT_LABEL&searchParameters[1].searchString=chlor&searchParameters[2].labelType=CUSTOM_LABEL&searchParameters[2].customLabel=http://id.nlm.nih.gov/mesh/vocab%23annotation&searchParameters[2].searchString=insects&useSkosBoost=false
Note
Parameters need to be URL encoded which also affects the character "#" in the URIs.
It is also possible to only search in custom labels, the parameter "searchString" is optional.
<server>/extractor/api/suggest?projectId=<ID>&language=en&searchParameters[0].labelType=CUSTOM_LABEL&searchParameters[0].customLabel=http://id.nlm.nih.gov/mesh/vocab%23casn1_label&searchParameters[0].searchString=methyl
You can also combine this with different matching strategies, for example regular expressions:
<server>/extractor/api/suggest?projectId=<ID>&language=en&searchParameters[0].labelType=CUSTOM_LABEL&searchParameters[0].customLabel=http://id.nlm.nih.gov/mesh/vocab%23relatedRegistryNumber&searchParameters[0].matchingStrategy=REGEX&searchParameters[0].searchString=.*50-.*-2.*
You can retrieve any concepts from a project: just specify the project ID and the language. This way no restrictions are applied and all concepts (up to what is set in "numberOfConcepts") are returned:
<server>/extractor/api/suggest?projectId=<ID>&language=en