Query reference
IBM Watson™ Discovery offers powerful content search capabilities through queries. After your content is uploaded and enriched by Discovery, you can build queries, integrate Discovery into your own projects, or create a custom application by using the Watson Explorer Application Builder.
For more information about writing queries, see:
Parameters descriptions
Query parameters enable you to search your collection, identify a result set, and perform analysis on the result set.
Parameter | Description | Example |
---|---|---|
Search parameters | ||
query | A ranked query language search for matching documents. | query=bees |
filter | An unranked query language search for matching documents. | filter=bees |
natural_language_query | A ranked natural language search for matching documents | natural_language_query="How do bees fly" |
aggregation | A statistical query of the results set | aggregation=term(enriched_text.entities.type) |
Structure parameters | ||
count | The number of result documents to return. |
count=15 |
offset | The number of results to ignore before returning result documents from the results set |
offset=100 |
return | List of fields to return | return=title,url |
sort | Field to sort results set by | sort=enriched_text.sentiment.document.score |
bias | Field to bias results set by | bias=publication_date |
passages.fields | Fields to extract passages from | passages=true&passages.fields=text,abstract,conclusion |
passages.count | Number of passages to return | passages=true&passages.count=6 |
passages.characters | Length of passages | passages=true&passages.characters=144 |
highlight | Highlight query matches | highlight=true |
deduplicate | Deduplicate IBM Watson™ Discovery News returned results | deduplicate=true |
deduplicate.field | Deduplicate returned results based on field | deduplicate.field=title |
collection_ids | Query multiple collections | collection_ids={1},{2},{3} |
similar | Enables the similar document finding | similar=true |
similar.document_ids | Which documents to find similar documents to | similar.document_ids={id1},{id2} |
similar.fields | Which fields to compare when finding similar documents | similar.fields=text,title |
Query limitations
You cannot query on field names that contain the following:
- Numerical characters (
0 - 9
) in the suffix of the field name (for exampleextracted-content2
). - The characters
_
,+
, and-
in the prefix of thefield_name
(for example+extracted-content
). - The characters
.
,,
, and:
in thefield_name
(for examplenew:extracted-content
)
Operators
Operators are the separators between different parts of a query. These are the available operators:
Operator | Description | Example |
---|---|---|
. | JSON delimiter | enriched_text.concepts.text |
: | Includes | text:computer |
:: | Exact match | title::"Query building" |
:! | Does not include | text:!computer |
::! | Not an exact match | text::!winter |
\ | Escape character | title::"Dorothy said: \"There's no place like home\"" |
"" | Phrase query | enriched_text.concepts.text:"IBM Watson" |
(), [] | Nested grouping | filter-entities:(text:Turkey,type:Location) |
| |
or | query-enriched.entities.text:Google|IBM |
, | and | query-enriched.entities.text:Google,IBM |
<=, >=, >, < | Numerical comparisons | enriched_text.sentiment.document.score>0.679 |
[^x] | Score multiplier | text:IBM^3 |
* | Wildcard | query-enriched_text.concepts.text:pre* |
~n | String variation | query-enriched_text.entities.text:cat~1 |
:* | Exists | title:* |
!* | Does not exist | title:!* |
Aggregations
Aggregations return a set of data values. These are the available aggregations:
Aggregation | Description | Example |
---|---|---|
term | Count of identical values | term(enriched_text.concepts.text,count:10) |
filter | Filter results set to defined pattern | filter(enriched_text.concepts.text:cloud computing) |
nested | Restrict aggregation | nested(enriched_text.entities) |
histogram | Interval based distribution | histogram(product.price,interval:1) |
timeslice | Time base distribution | timeslice(last_modified,2day,America/New York) |
top_hits | Top ranked results documents for the current aggregation | term(enriched_text.concepts.text).top_hits(10) |
unique_count | Count of unique values for a field within an aggregation | unique_count(enriched_text.entities.type) |
max | Maximum value for the specified field in the results set. | max(product.price) |
min | Minimum value for the specified field in the results set. | min(product.price) |
average | Mean value for the specified field in the results set. | average(product.price) |
sum | Sum of all fields in the results set. | sum(product.price) |