IBM Cloud Docs
Query reference

Query reference

The full list of Discovery query parameters, operators, and aggregations. You can refer to this information for help when you write queries with the Discovery Query Language.

In the Discovery user interface, you can write and test natural language queries on the Improve and customize page.

Parameters descriptions

Use query parameters to search your collection, identify a result set, and analyze result sets.

Search parameters
Parameter Description Example
aggregation A statistical query of the results set aggregation=term(enriched_text.entities.type)
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"
query A ranked query language search for matching documents. query=bees
Structure parameters
Parameter Description Example
count The number of result documents to return. count=15
highlight Highlight query matches highlight=true
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
spelling suggestions Spelling suggestions returned for natural language queries spelling_suggestions=true

Query limitations

You cannot query on field names that contain the following characters:

  • Numbers (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. The following table lists the available operators.

Query 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 groups 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. The following table lists the available aggregations.

Query aggregations
Aggregation Description Example
average Mean value for the specified field in the results set. average(product.price)
filter Filter results based on the specified pattern filter(enriched_text.concepts.text:cloud computing)
histogram Interval-based distribution histogram(product.price,interval:1)
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)
nested Restrict aggregation nested(enriched_text.entities)
sum Sum of all fields in the results set. sum(product.price)
term Count of identical values term(enriched_text.concepts.text,count:10)
timeslice Time-based distribution timeslice(last_modified,2day,America/New York)
top_hits Top-ranked result 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)