Globus Search¶

class globus_sdk.SearchClient(*, environment: Optional[str] = None, base_url: Optional[str] = None, authorizer: Optional[globus_sdk.authorizers.base.GlobusAuthorizer] = None, app_name: Optional[str] = None, transport_params: Optional[Dict[str, Any]] = None)[source]¶

Bases: globus_sdk.client.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

create_entry()
delete_by_query()
delete_entry()
delete_subject()
get_entry()
get_index()
get_subject()
get_task()
get_task_list()
ingest()
post_search()
search(), paginated.search()
update_entry()

get_index(index_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) → globus_sdk.response.GlobusHTTPResponse[source]¶

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: Union[uuid.UUID, str], q: str, *, offset: int = 0, limit: int = 10, advanced: bool = False, query_params: Optional[Dict[str, Any]] = None) → globus_sdk.response.GlobusHTTPResponse[source]¶

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)

Paginated Usage

This method supports paginated access. To use the paginated variant, give the same arguments as normal, but prefix the method name with paginated, as in

>>> client.paginated.search(...)

For more information, see how to make paginated calls.

External Documentation

See GET Search Query in the API documentation for details.

post_search(index_id: Union[uuid.UUID, str], data: Union[Dict[str, Any], globus_sdk.services.search.data.SearchQuery]) → globus_sdk.response.GlobusHTTPResponse[source]¶

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: Union[uuid.UUID, str], data: Dict[str, Any]) → globus_sdk.response.GlobusHTTPResponse[source]¶

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: Union[uuid.UUID, str], data: Dict[str, Any]) → globus_sdk.response.GlobusHTTPResponse[source]¶

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: Union[uuid.UUID, str], subject: str, *, query_params: Optional[Dict[str, Any]] = None) → globus_sdk.response.GlobusHTTPResponse[source]¶

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: Union[uuid.UUID, str], subject: str, *, query_params: Optional[Dict[str, Any]] = None) → globus_sdk.response.GlobusHTTPResponse[source]¶

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: Union[uuid.UUID, str], subject: str, *, entry_id: Optional[str] = None, query_params: Optional[Dict[str, Any]] = None) → globus_sdk.response.GlobusHTTPResponse[source]¶

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: Union[uuid.UUID, str], data: Dict[str, Any]) → globus_sdk.response.GlobusHTTPResponse[source]¶

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: Union[uuid.UUID, str], data: Dict[str, Any]) → globus_sdk.response.GlobusHTTPResponse[source]¶

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: Union[uuid.UUID, str], subject: str, *, entry_id: Optional[str] = None, query_params: Optional[Dict[str, Any]] = None) → globus_sdk.response.GlobusHTTPResponse[source]¶

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_task(task_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) → globus_sdk.response.GlobusHTTPResponse[source]¶

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'])

External Documentation

See Get Task in the API documentation for details.

get_task_list(index_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) → globus_sdk.response.GlobusHTTPResponse[source]¶

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'])

External Documentation

See Task List in the API documentation for details.

Helper Objects¶

class globus_sdk.SearchQuery(q: Optional[str] = None, *, limit: Optional[int] = None, offset: Optional[int] = None, advanced: Optional[bool] = None, additional_fields: Optional[Dict[str, Any]] = None)[source]¶

Bases: globus_sdk.utils.PayloadWrapper

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.SearchAPIError(r: requests.models.Response)[source]¶

Bases: globus_sdk.exc.api.GlobusAPIError

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

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