Globus Search

class globus_sdk.SearchClient(authorizer=None, **kwargs)

Bases: globus_sdk.base.BaseClient

Client for the Globus Search API

This class provides helper methods for most common resources in the API, and basic get, put, post, and delete methods from the base client that can be used to access any API resource.

Parameters:

authorizer (GlobusAuthorizer ) – An authorizer instance used for all calls to Globus Search

Methods

Methods

• create_entry()

• delete_by_query()

• delete_entry()

• delete_subject()

• get_entry()

• get_index()

• get_query_template()

• get_query_template_list()

• get_subject()

• get_task()

• get_task_list()

• ingest()

• post_search()

• search()

• update_entry()

get_index(index_id, **params)

GET /v1/index/<index_id>

Examples

>>> sc = globus_sdk.SearchClient(...)
>>> index = sc.get_index(index_id)
>>> assert index['index_id'] == index_id
>>> print(index["display_name"],
>>>       "(" + index_id + "):",
>>>       index["description"])

External Documentation

See Get Index Metadata in the API documentation for details.

search(index_id, q, offset=0, limit=10, query_template=None, advanced=False, **params)

GET /v1/index/<index_id>/search

Examples

>>> sc = globus_sdk.SearchClient(...)
>>> result = sc.search(index_id, 'query string')
>>> advanced_result = sc.search(index_id, 'author: "Ada Lovelace"',
>>>                             advanced=True)

External Documentation

See GET Search Query in the API documentation for details.

post_search(index_id, data)

POST /v1/index/<index_id>/search

Examples

>>> sc = globus_sdk.SearchClient(...)
>>> query_data = {
>>>   "@datatype": "GSearchRequest",
>>>   "q": "user query",
>>>   "filters": [
>>>     {
>>>       "type": "range",
>>>       "field_name": "path.to.date",
>>>       "values": [
>>>         {"from": "*",
>>>          "to": "2014-11-07"}
>>>       ]
>>>     }
>>>   ],
>>>   "facets": [
>>>     {"name": "Publication Date",
>>>      "field_name": "path.to.date",
>>>      "type": "date_histogram",
>>>      "date_interval": "year"}
>>>   ],
>>>   "sort": [
>>>     {"field_name": "path.to.date",
>>>      "order": "asc"}
>>>   ]
>>> }
>>> search_result = sc.post_search(index_id, query_data)

External Documentation

See POST Search Query in the API documentation for details.

ingest(index_id, data)

POST /v1/index/<index_id>/ingest

Examples

>>> sc = globus_sdk.SearchClient(...)
>>> ingest_data = {
>>>   "ingest_type": "GMetaEntry",
>>>   "ingest_data": {
>>>     "subject": "https://example.com/foo/bar",
>>>     "visible_to": ["public"],
>>>     "content": {
>>>       "foo/bar": "some val"
>>>     }
>>>   }
>>> }
>>> sc.ingest(index_id, ingest_data)

or with multiple entries at once via a GMetaList:

>>> sc = globus_sdk.SearchClient(...)
>>> ingest_data = {
>>>   "ingest_type": "GMetaList",
>>>   "ingest_data": {
>>>     "gmeta": [
>>>       {
>>>         "subject": "https://example.com/foo/bar",
>>>         "visible_to": ["public"],
>>>         "content": {
>>>           "foo/bar": "some val"
>>>         }
>>>       },
>>>       {
>>>         "subject": "https://example.com/foo/bar",
>>>         "id": "otherentry",
>>>         "visible_to": ["public"],
>>>         "content": {
>>>           "foo/bar": "some otherval"
>>>         }
>>>       }
>>>     ]
>>>   }
>>> }
>>> sc.ingest(index_id, ingest_data)

External Documentation

See Ingest in the API documentation for details.

delete_by_query(index_id, data)

POST /v1/index/<index_id>/delete_by_query

Examples

>>> sc = globus_sdk.SearchClient(...)
>>> query_data = {
>>>   "q": "user query",
>>>   "filters": [
>>>     {
>>>       "type": "range",
>>>       "field_name": "path.to.date",
>>>       "values": [
>>>         {"from": "*",
>>>          "to": "2014-11-07"}
>>>       ]
>>>     }
>>>   ]
>>> }
>>> sc.delete_by_query(index_id, query_data)

External Documentation

See Delete By Query in the API documentation for details.

get_subject(index_id, subject, **params)

GET /v1/index/<index_id>/subject

Examples

Fetch the data for subject http://example.com/abc from index index_id:

>>> sc = globus_sdk.SearchClient(...)
>>> subject_data = sc.get_subject(index_id, 'http://example.com/abc')

External Documentation

See Get Subject in the API documentation for details.

delete_subject(index_id, subject, **params)

DELETE /v1/index/<index_id>/subject

Examples

Delete all data for subject http://example.com/abc from index index_id, even data which is not visible to the current user:

>>> sc = globus_sdk.SearchClient(...)
>>> subject_data = sc.get_subject(index_id, 'http://example.com/abc')

External Documentation

See Delete Subject in the API documentation for details.

get_entry(index_id, subject, entry_id=None, **params)

GET /v1/index/<index_id>/entry

Examples

Lookup the entry with a subject of https://example.com/foo/bar and a null entry_id:

>>> sc = globus_sdk.SearchClient(...)
>>> entry_data = sc.get_entry(index_id, 'http://example.com/foo/bar')

Lookup the entry with a subject of https://example.com/foo/bar and an entry_id of foo/bar:

>>> sc = globus_sdk.SearchClient(...)
>>> entry_data = sc.get_entry(index_id, 'http://example.com/foo/bar',
>>>                           entry_id='foo/bar')

External Documentation

See Get Entry in the API documentation for details.

create_entry(index_id, data)

POST /v1/index/<index_id>/entry

Examples

Create an entry with a subject of https://example.com/foo/bar and a null entry_id:

>>> sc = globus_sdk.SearchClient(...)
>>> sc.create_entry(index_id, {
>>>     "subject": "https://example.com/foo/bar",
>>>     "visible_to": ["public"],
>>>     "content": {
>>>         "foo/bar": "some val"
>>>     }
>>> })

Create an entry with a subject of https://example.com/foo/bar and an entry_id of foo/bar:

>>> sc = globus_sdk.SearchClient(...)
>>> sc.create_entry(index_id, {
>>>     "subject": "https://example.com/foo/bar",
>>>     "visible_to": ["public"],
>>>     "id": "foo/bar",
>>>     "content": {
>>>         "foo/bar": "some val"
>>>     }
>>> })

External Documentation

See Create Entry in the API documentation for details.

update_entry(index_id, data)

PUT /v1/index/<index_id>/entry

Examples

Update an entry with a subject of https://example.com/foo/bar and a null entry_id:

>>> sc = globus_sdk.SearchClient(...)
>>> sc.update_entry(index_id, {
>>>     "subject": "https://example.com/foo/bar",
>>>     "visible_to": ["public"],
>>>     "content": {
>>>         "foo/bar": "some val"
>>>     }
>>> })

External Documentation

See Update Entry in the API documentation for details.

delete_entry(index_id, subject, entry_id=None, **params)

DELETE  /v1/index/<index_id>/entry

Examples

Delete an entry with a subject of https://example.com/foo/bar and a null entry_id:

>>> sc = globus_sdk.SearchClient(...)
>>> sc.delete_entry(index_id, "https://example.com/foo/bar")

Delete an entry with a subject of https://example.com/foo/bar and an entry_id of “foo/bar”:

>>> sc = globus_sdk.SearchClient(...)
>>> sc.delete_entry(index_id, "https://example.com/foo/bar",
>>>                 entry_id="foo/bar")

External Documentation

See Delete Entry in the API documentation for details.

get_query_template(index_id, template_name)

GET /v1/index/<index_id>/query_template/<template_name>

External Documentation

See Get Query Template in the API documentation for details.

get_query_template_list(index_id)

GET /v1/index/<index_id>/query_template

External Documentation

See Get Query Template List in the API documentation for details.

get_task(task_id, **params)

GET /v1/task/<task_id>

Examples

>>> sc = globus_sdk.SearchClient(...)
>>> task = sc.get_task(task_id)
>>> assert task['index_id'] == known_index_id
>>> print(task["task_id"] + " | " + task['state'])

get_task_list(index_id, **params)

GET /v1/task_list/<index_id>

Examples

>>> sc = globus_sdk.SearchClient(...)
>>> task_list = sc.get_task_list(index_id)
>>> for task in task_list['tasks']:
>>>     print(task["task_id"] + " | " + task['state'])

Helper Objects

class globus_sdk.SearchQuery

Bases: dict

A specialized dict which has helpers for creating and modifying a Search Query document.

Example usage:

>>> from globus_sdk import SearchClient, SearchQuery
>>> sc = SearchClient(...)
>>> index_id = ...
>>> query = (SearchQuery(q='example query')
>>>          .set_limit(100).set_offset(10)
>>>          .add_filter('path.to.field1', ['foo', 'bar']))
>>> result = sc.post_search(index_id, query)

Client Errors

When an error occurs, a SearchClient will raise this specialized type of error, rather than a generic GlobusAPIError.

class globus_sdk.exc.SearchAPIError(r)

Bases: globus_sdk.exc.GlobusAPIError

Error class for the Search API client. In addition to the inherited code and message instance variables, provides:

Variables:

error_data – Additional object returned in the error response. May be a dict, list, or None.