query-reference.md

copyright	lastupdated	subcollection
years 2019, 2020	2019-05-13	discovery-data

{:shortdesc: .shortdesc} {:external: target="_blank" .external} {:tip: .tip} {:note: .note} {:pre: .pre} {:important: .important} {:deprecated: .deprecated} {:codeblock: .codeblock} {:screen: .screen} {:download: .download} {:hide-dashboard: .hide-dashboard} {:apikey: data-credential-placeholder='apikey'} {:url: data-credential-placeholder='url'} {:curl: .ph data-hd-programlang='curl'} {:javascript: .ph data-hd-programlang='javascript'} {:java: .ph data-hd-programlang='java'} {:python: .ph data-hd-programlang='python'} {:ruby: .ph data-hd-programlang='ruby'} {:swift: .ph data-hd-programlang='swift'} {:go: .ph data-hd-programlang='go'}

Query reference

{: #query-reference}

The full list of {{site.data.keyword.discoveryshort}} query parameters, operators, and aggregations. These are used when writing queries with the {{site.data.keyword.discoveryshort}} Query Language. For more information, see the {{site.data.keyword.discoveryshort}} API reference{: external}. For an overview of query concepts, see the Query overview. {: shortdesc}

In the {{site.data.keyword.discoveryshort}} tooling, you can write and test natural language queries on the Improve and customize page. {: tip}

Parameters descriptions

{: #parameter-descriptions}

Query parameters enable you to search your collection, identify a result set, and perform analysis on result sets.

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
highlight	Highlight query matches	highlight=true
spelling suggestions	Spelling suggestions returned for natural language queries	spelling_suggestions=true

Query limitations

{: #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}

Operators are the separators between different parts of a query. 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}

Aggregations return a set of data values. 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)