query-reference.md

copyright	lastupdated	subcollection
years 2015, 2020	2020-02-05	discovery

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

{{site.data.keyword.discoveryfull}} offers powerful content search capabilities through queries. After your content is uploaded and enriched by {{site.data.keyword.discoveryshort}}, you can build queries, integrate {{site.data.keyword.discoveryshort}} into your own projects, or create a custom application by using the {{site.data.keyword.watson}} Explorer Application Builder. {: shortdesc}

For more information about writing queries, see:

• Getting started with querying
• Query concepts

Parameters descriptions

{: #parameter-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 {{site.data.keyword.discoverynewsfull}} 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

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

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)