Contents Menu Expand Light mode Dark mode Auto light/dark mode
globus-sdk v3
Logo
globus-sdk v3

Getting Started

  • Installation
  • Tutorial

Full Reference

  • Service Clients
    • Globus Auth
    • Globus Flows
    • Globus Groups
    • Globus Search
    • Globus Timer
    • Globus Transfer
    • Globus Connect Server API
  • Scopes and ScopeBuilders
  • Local Endpoints
  • API Authorization
  • TokenStorage
  • Globus SDK Configuration
  • Globus SDK Core
    • BaseClient
    • Transport Layer
    • Responses
    • Paging and Paginators
    • Exceptions
    • Utilities

Additional Info

  • Versioning Policy
  • License
  • CHANGELOG
  • Upgrading

Examples

  • Globus SDK Examples
    • File Transfer Scripts
    • Group Listing Script
    • Group Listing With Token Storage
    • API Authorization
    • Native App Login
    • Client Credentials Authentication
    • Three Legged OAuth with Flask
    • Transfer Relative Task Deadlines
    • Recursive ls via TransferClient
    • Transfer Endpoint Type Enum
    • Timer Operations Script
    • Guest Collection Creation Script

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

Methods

  • create_entry()

  • create_role()

  • delete_by_query()

  • delete_entry()

  • delete_role()

  • delete_subject()

  • get_entry()

  • get_index()

  • get_role_list()

  • get_subject()

  • get_task()

  • get_task_list()

  • ingest()

  • post_search(), paginated.post_search()

  • scroll(), paginated.scroll()

  • 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['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], *, offset: Optional[int] = None, limit: Optional[int] = None) → globus_sdk.response.GlobusHTTPResponse[source]¶

POST /v1/index/<index_id>/search

Parameters
  • index_id (str or UUID) – The index on which to search

  • data (dict or SearchQuery) – A Search Query document containing the query and any other fields

  • offset (int, optional) – offset used in paging (overwrites any offset in data)

  • limit (int, optional) – limit the number of results (overwrites any limit in data)

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)

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.post_search(...)

For more information, see how to make paginated calls.

External Documentation

See POST Search Query in the API documentation for details.

scroll(index_id: Union[uuid.UUID, str], data: Union[Dict[str, Any], globus_sdk.services.search.data.SearchScrollQuery], *, marker: Optional[str] = None) → globus_sdk.response.GlobusHTTPResponse[source]¶

POST /v1/index/<index_id>/scroll

Parameters
  • index_id (str or UUID) – The index on which to search

  • data (dict or SearchScrollQuery) – A Search Scroll Query document

  • marker (str, optional) – marker used in paging (overwrites any marker in data)

Examples

>>> sc = globus_sdk.SearchClient(...)
>>> scroll_result = sc.scroll(index_id, {"q": "*"})

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.scroll(...)

For more information, see how to make paginated calls.

External Documentation

See Scroll 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.delete_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.

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

POST /v1/index/<index_id>/role

Create a new role on an index. You must already have the owner or admin role on an index to create additional roles.

Roles are specified as a role name (one of "owner", "admin", or "writer") and a Principal URN.

Parameters
  • index_id (uuid or str) – The index on which to create the role

  • data (dict) – The partial role document to use for creation

  • query_params (dict, optional) – Any additional query params to pass

Examples

>>> identity_id = "46bd0f56-e24f-11e5-a510-131bef46955c"
>>> sc = globus_sdk.SearchClient(...)
>>> sc.create_role(
>>>     index_id,
>>>     {
>>>         "role_name": "writer",
>>>         "principal": f"urn:globus:auth:identity:{identity_id}"
>>>     }
>>> )

External Documentation

See Create Role in the API documentation for details.

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

GET /v1/index/<index_id>/role_list

List all roles on an index. You must have the owner or admin role on an index to list roles.

Parameters
  • index_id (uuid or str) – The index on which to list roles

  • query_params (dict, optional) – Any additional query params to pass

External Documentation

See Get Role List in the API documentation for details.

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

DELETE /v1/index/<index_id>/role/<role_id>

Delete a role from an index. You must have the owner or admin role on an index to delete roles. You cannot remove the last owner from an index.

Parameters
  • index_id (uuid or str) – The index from which to delete a role

  • role_id (str) – The role to delete

  • query_params (dict, optional) – Any additional query params to pass

External Documentation

See Role Delete in the API documentation for details.

Helper Objects¶

Note that you should not use SearchQueryBase directly, and it is not importable from the top level of the SDK. It is included in documentation only to document the methods it provides to its subclasses.

class globus_sdk.services.search.data.SearchQueryBase(dict=None, /, **kwargs)[source]¶

Bases: globus_sdk.utils.PayloadWrapper

The base class for all Search query helpers.

Search has multiple types of query documents. Not all of their supported attributes are shared, and they therefore do not inherit from one another. This class implements common methods to all of them.

Query objects have a chainable API, in which methods return the query object after modification. This allows usage like

>>> query = ...
>>> query = query.set_limit(10).set_advanced(False)
add_filter(field_name: str, values: List[str], *, type: str = 'match_all', additional_fields: Optional[Dict[str, Any]] = None) → globus_sdk.services.search.data.SearchQueryT[source]¶

Add a filter subdocument to the query.

Parameters
  • field_name (str) – the field on which to filter

  • values (list of str) – the values to use in the filter

  • type (str) – the type of filter to apply, defaults to “match_all”

  • additional_fields (dict, optional) – additional data to include in the filter document

set_advanced(advanced: bool) → globus_sdk.services.search.data.SearchQueryT[source]¶

Enable or disable advanced query string processing.

Parameters

advanced (bool) – whether to enable (True) or not (False)

set_limit(limit: int) → globus_sdk.services.search.data.SearchQueryT[source]¶

Set the limit for the query document.

Parameters

limit (int) – a limit on the number of results returned in a single page

set_query(query: str) → globus_sdk.services.search.data.SearchQueryT[source]¶

Set the query string for the query document.

Parameters

query (str) – the new query string

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.services.search.data.SearchQueryBase

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

Parameters
  • q (str, optional) – The query string. Required unless filters are used.

  • limit (int) – A limit on the number of results returned in a single page

  • offset (int) – An offset into the set of all results for the query

  • advanced (bool, optional) – Whether to enable (True) or not to enable (False) advanced parsing of query strings. The default of False is robust and guarantees that the query will not error with “bad query string” errors

  • additional_fields (dict, optional) – additional data to include in the 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)
add_boost(field_name: str, factor: Union[str, int, float], *, additional_fields: Optional[Dict[str, Any]] = None) → globus_sdk.services.search.data.SearchQuery[source]¶

Add a boost subdocument to the query.

Parameters
  • field_name (str) – the field to boost in result weighting

  • factor (str, int, or float) – the factor by which to adjust the field weight (where 1.0 is the default weight)

  • additional_fields (dict, optional) – additional data to include in the boost document

add_facet(name: str, field_name: str, *, type: str = 'terms', size: Optional[int] = None, date_interval: Optional[str] = None, histogram_range: Optional[Tuple[Any, Any]] = None, additional_fields: Optional[Dict[str, Any]] = None) → globus_sdk.services.search.data.SearchQuery[source]¶

Add a facet subdocument to the query.

Parameters
  • name (str) – the name for the facet in the result

  • field_name (str) – the field on which to build the facet

  • type (str) – the type of facet to apply, defaults to “terms”

  • size (int, optional) – the size parameter for the facet

  • date_interval (str, optional) – the date interval for a date histogram facet

  • histogram_range (tuple, optional) – a low and high bound for a numeric histogram facet

  • additional_fields (dict, optional) – additional data to include in the facet document

add_sort(field_name: str, *, order: Optional[str] = None, additional_fields: Optional[Dict[str, Any]] = None) → globus_sdk.services.search.data.SearchQuery[source]¶

Add a sort subdocument to the query.

Parameters
  • field_name (str) – the field on which to sort

  • order (str, optional) – ascending or descending order, given as "asc" or "desc"

  • additional_fields (dict, optional) – additional data to include in the sort document

set_offset(offset: int) → globus_sdk.services.search.data.SearchQuery[source]¶

Set the offset for the query document.

Parameters

offset (int) – an offset into the set of all results for the query

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

Bases: globus_sdk.services.search.data.SearchQueryBase

A scrolling query type, for scrolling the full result set for an index.

Scroll queries have more limited capabilities than general searches. They cannot boost fields, sort, or apply facets. They can, however, still apply the same filtering mechanisms which are available to normal queries.

Scrolling also differs in that it supports the use of the marker field, which is used to paginate results.

Parameters
  • q (str, optional) – The query string

  • limit (int) – A limit on the number of results returned in a single page

  • advanced (bool, optional) – Whether to enable (True) or not to enable (False) advanced parsing of query strings. The default of False is robust and guarantees that the query will not error with “bad query string” errors

  • marker (str, optional) – the marker value

  • additional_fields (dict, optional) – additional data to include in the query document

set_marker(marker: str) → globus_sdk.services.search.data.SearchScrollQuery[source]¶

Set the marker on a scroll query.

Parameters

marker (str) – the marker value

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.

Next
Globus Timer
Previous
Globus Groups
Copyright © 2016-2023, Globus | Created using Sphinx and @pradyunsg's Furo theme. | Show Source
Contents
  • Globus Search
    • Helper Objects
    • Client Errors