GET Query

Method	GET
URL	/v1/index/<index_id>/search
Authentication required?	Only for non-public data
Required Roles	None
Response Body	A GSearchResult

Authentication & Authorization

Tokens for this call must have one of these scopes.

urn:globus:scopes:search.api.globus.org:all
urn:globus:scopes:search.api.globus.org:search

Parameters

Parameter Name	Required?	Description
q	Yes	A string representation of the query to be executed
offset	No	Zero based offset into the result set, used for paging Default 0, Maximum 10,000
limit	No	Maximum number of results to return. Default 10, max 10,000
advanced	No	For expert users only. When "true" use the advanced form of the query syntax. Default "false"
bypass_visible_to	No	Boolean, defaults to False. Allowed for Index Admins only. When true, visible_to restrictions will be ignored for this search query.
result_format_version	No	One of {"2019-08-27", "2017-09-01"}. Defaults to 2019-08-27. When given as 2017-09-01, results will be returned in the legacy format.
filter_principal_sets	No	A comma-delimited list of strings. The caller’s identity set will be matched against any `principal_sets` assigned to entry documents, and filtered to matches for any of these strings. If this parameter is provided, at least one match must be present.

Examples

Searching

in the index 4de0e89e-a395-11e7-bc54-8c705ad34f60
with a simple query of globus documentation
getting the first page of results

curl -XGET 'https://search.api.globus.org/v1/index/4de0e89e-a395-11e7-bc54-8c705ad34f60/search?q=globus%20documentation'

Searching

in the index 4de0e89e-a395-11e7-bc54-8c705ad34f60
with an advanced query of type:html content:"globus documentation"
getting the second page of results, with a page size of 20

curl -XGET 'https://search.api.globus.org/v1/index/4de0e89e-a395-11e7-bc54-8c705ad34f60/search?q=type%3Ahtml%20content%3A%22globus%20documentation%22&advanced=true&limit=20&offset=20'

Response Schemas

GSearchResult

This is the document type for all results from Search queries.

Field Name	Type	Description
gmeta	Array	An array of GMetaResult documents, the main body of the result
facet_result	Array	Optional. An array of GFacetResult documents with counts for all facets requested on the search request
offset	Integer	The offset provided on the input search request
count	Integer	The number of results returned; i.e. the size of the gmeta array. May be 0
total	Integer	The total number of matches for the search. May be 0 if no matches are found
has_next_page	Boolean	True if there’s another page of results available, False otherwise

Examples

This result is in the 2019-08-27 format for GMetaResult documents.

{
  "@datatype": "GSearchResult",
  "@version": "2017-09-01",
  "count": 1,
  "gmeta": [
    {
      "@datatype": "GMetaResult",
      "@version": "2019-08-27",
      "entries": [
        {
          "content": {
            "cuisine": [
              "mexican"
            ],
            "handle": "salsa-verde",
            "ingredients": [
              {
                "amount": {
                  "number": 10
                },
                "default": "tomatillo",
                "preparation": "simmer 20 minutes",
                "type": "fruit"
              },
              {
                "amount": {
                  "number": 2
                },
                "default": "serrano pepper",
                "preparation": "seeded",
                "substitutes": [
                  "jalapeno",
                  "thai bird chili"
                ],
                "type": "fruit"
              },
              {
                "amount": {
                  "number": 2,
                  "unit": "clove"
                },
                "default": "garlic",
                "type": "vegetable"
              },
              {
                "amount": {
                  "number": 0.5
                },
                "default": "yellow onion",
                "type": "vegetable"
              },
              {
                "amount": {
                  "number": 2,
                  "unit": "tsp"
                },
                "default": "salt",
                "type": "spice"
              },
              {
                "amount": {
                  "number": 2,
                  "unit": "tbsp"
                },
                "default": "coriander",
                "preparation": "ground",
                "substitutes": [
                  "cumin"
                ],
                "type": "spice"
              }
            ],
            "keywords": [
              "salsa",
              "tomatillo",
              "coriander",
              "serrano pepper"
            ],
            "origin": {
              "author": "Diana Kennedy",
              "title": "Regional Mexican Cooking",
              "type": "book"
            }
          },
          "entry_id": null
        }
      ],
      "subject": "https://en.wikipedia.org/wiki/Salsa_verde"
    }
  ],
  "offset": 0,
  "total": 1
}

This result is in the 2017-09-01 format for GMetaResult documents.

{
  "count": 1,
  "offset": 0,
  "total": 1,
  "gmeta": [
    {
      "content": [
        {
          "alpha": {
            "beta": "gamma"
          }
        }
      ],
      "entry_ids": [
        null
      ],
      "subject": "http://example.com"
    }
  ]
}

GMetaResult

These are components in a search result.

A GMetaResult is a structure similar to a GMetaEntry from the Ingest API, with the following significant differences:

visibility information is not exposed; i.e. visible_to is not included
metadata for any subject may be an aggregate of multiple documents with different visibility rules or sources. Thus, the result is always returned as an array in which each element represents data provided by a different source or with different visibility

GMetaResult version 2019-08-27

Field Name Type Description

subject

String

the resource described by this metadata, often a URI

entries

Array

An array of objects containing the data pertaining to the subject.

Each object has the fields content, entry_id, and matched_principal_sets. The content is an object with the entry data which was sent to Search, and the entry_id is its ID. If there are any assigned principal_sets for the entry which match the current caller, they will be returned as an array of strings in matched_principal_sets.

{
  "entries": [
    {
      "content": {
        "alpha": {
          "beta": "gamma"
        }
      },
      "matched_principal_sets": [],
      "entry_id": null
    },
    {
      "content": {
        "alpha": {
          "beta": "delta"
        }
      },
      "matched_principal_sets": [],
      "entry_id": "with_delta"
    }
  ],
  "subject": "http://example.com"
}

GMetaResult version 2017-09-01 (legacy format)

Field Name	Type	Description
subject	String	the resource described by this metadata, often a URI
content	Array	an array of objects containing the metadata pertaining to the subject
entry_ids	Array	an array of Entry IDs matching the content such that the entry ID at index i has content found in content[i]. See note below

Note

entry_ids and content are kept separate to maintain backwards compatibility. They can easily be unified with a zip operation in many programming languages.

{
  "entries": [
    {
      "content": {
        "alpha": {
          "beta": "gamma"
        }
      },
      "matched_principal_sets": [],
      "entry_id": null
    }
  ],
  "subject": "http://example.com"
}

Note how, in the example below, the new format makes it easier to associate entry_id values with content blobs. Additionally, this new format is more extensible — if new fields are needed in the new format, they can be added as siblings of the content and entry_id fields.

New Format (2019-08-27) Old Format (2017-09-01)

Table 1. Format Comparison
New Format (2019-08-27)	Old Format (2017-09-01)
`{ "entries": [ { "content": { "alpha": { "beta": "gamma" } }, "matched_principal_sets": [], "entry_id": null }, { "content": { "alpha": { "beta": "delta" } }, "matched_principal_sets": [], "entry_id": "with_delta" } ], "subject": "http://example.com" }`	`{ "content": [ { "alpha": { "beta": "gamma" } }, { "alpha": { "beta": "delta" } } ], "entry_ids": [ null, "with_delta" ], "subject": "http://example.com" }`
each entry is a complete, standalone subdocument	entry_ids needs to be zipped with content to make sense of the structure

{
  "entries": [
    {
      "content": {
        "alpha": {
          "beta": "gamma"
        }
      },
      "matched_principal_sets": [],
      "entry_id": null
    },
    {
      "content": {
        "alpha": {
          "beta": "delta"
        }
      },
      "matched_principal_sets": [],
      "entry_id": "with_delta"
    }
  ],
  "subject": "http://example.com"
}

{
  "content": [
    {
      "alpha": {
        "beta": "gamma"
      }
    },
    {
      "alpha": {
        "beta": "delta"
      }
    }
  ],
  "entry_ids": [
    null,
    "with_delta"
  ],
  "subject": "http://example.com"
}

each entry is a complete, standalone subdocument

entry_ids needs to be zipped with content to make sense of the structure

GBucket

Field Name	Type	Description
value	String or Object	If the bucket represents a single value (e.g. in a "terms" [GFacet]), the value is provided. If the bucket represents a range of values, then this is an object with "from" and "to" as in a [GFilter] document This range is assumed to be closed for the "from" value and open on the "to" value as in [from, to)
count	Integer	The number of results in this bucket

{
  "value": ".docx",
  "count": 1234
}

{
  "value": {
    "from": "0",
    "to": "10"
  },
  "count": 0
}

{
  "value": {
    "from": "2011-01-01",
    "to": "2012-01-01"
  },
  "count": 17
}

GFacetResult

Field Name	Type	Description
name	String	Name of the [GFacet] in the search request
value	Float	Result of the [GFacet] if it was a sum or avg facet
buckets	Array	An array of GBucket documents if it was a terms, numeric_histogram or date_histgram facet

{
  "name": "extensions",
  "buckets": [
    {
      "@version": "2017-09-01",
      "value": ".docx",
      "count": 1234
    },
    {
      "@version": "2017-09-01",
      "value": ".png",
      "count": 12
    }
  ]
}

{
  "name": "calculations",
  "value": 24.5
}