IBM Cloud Docs
Query reference

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 example extracted-content2).
  • The characters _, +, and - in the prefix of the field_name (for example +extracted-content).
  • The characters ., ,, and : in the field_name (for example new: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)