Documentation Home

Description

The Search API is used to query data from Globus Search.

It has two forms. Simple queries (for example, those not defining facets) may be accessed using the GET form for ease. More complicated queries will use the POST form to specify richer requirements. In either case, the result format is the same.

Simple GET Query

URL

/v1/index/<index_name>/search

Method

GET

HTTP Headers

(optional) Authorization: Bearer <Globus Auth token with scope urn:globus:scopes:search.api.globus.org:all>

If no Authorization is provided, only public metadata will be queried

Query Parameters

See the Query Parameters table below

Request Body

None

Response Body

A GSearchResult

Error Responses

HTTP Code 404: The specified index_name does not exist HTTP Code 502: Timeout. Query execution time is capped at 30 seconds. If query processing takes longer than this time, the API will terminate it.

The body will contain a GError document
Table 1. Query Parameters
Parameter Name Required? Description

q

True

A string representation of the query to be executed

offset

False

Zero based offset into the result set, used for paging Default 0, Maximum 10,000

limit

False

Maximum number of results to return. Default 10, max 10,000

query_template

False

The name of a pre-defined GSearchRequest to be included in the search criteria.

advanced

False

For expert users only. When "true" use the advanced form of the query syntax. Default "false"

Complex POST Query

URL

/v1/index/<index_name>/search

Method

POST

HTTP Headers

Authorization: Bearer <Globus Auth token with scope urn:globus:scopes:search.api.globus.org:all> Content-Type: must be "application/json"

Query Parameters

None

Request Body

a GSearchRequest document

Response Body

a GSearchResult document

Error Responses

HTTP Code 404: The specified index_name does not exist HTTP Code 502: Timeout. Query execution time is capped at 30 seconds. If query processing takes longer than this time, the API will terminate it.

The body will contain a GError document

Query Syntax

Two separate syntaxes for specifying the query are supported in both GET and POST queries: standard and advanced.

The standard query allows only for basic text matching. All queries will be processed, and results which best match the input will be provided. This is appropriate for environments where end-users will be providing the content of the query string, e.g. a searchbox in a web UI.

The advanced syntax is more powerful and supports ranges, regular expressions, matching on particular fields and other more sophisticated capabilities. The advanced syntax is subject to errors in parsing such as badly formed ranges or mis-named fields. As such, it requires expertise in the search language and should not be directly exposed to users without care and forethought. The syntax is based on the ElasticSearch query string syntax with the following exceptions:

  • Wildcards in field names are not allowed. So, for example, the query “book.\*:(quick brown)” is not permitted

  • The missing and exists query terms are not permitted

Elasticsearch Syntax is documented here: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax