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
, anddelete
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
post_search()
,paginated.post_search()
scroll()
,paginated.scroll()
search()
,paginated.search()
- 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 indexindex_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 indexindex_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 offoo/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 offoo/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
oradmin
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
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
oradmin
role on an index to list roles.- Parameters
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
oradmin
role on an index to delete roles. You cannot remove the lastowner
from an index.- Parameters
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.
- 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
)
- 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 ofFalse
is robust and guarantees that the query will not error with “bad query string” errorsadditional_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.
- 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.
- 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 ofFalse
is robust and guarantees that the query will not error with “bad query string” errorsmarker (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
andmessage
instance variables, provideserror_data
.- Variables
error_data – Additional object returned in the error response. May be a dict, list, or None.