Contents Menu Expand Light mode Dark mode Auto light/dark, in light mode Auto light/dark, in dark mode Skip to content
globus-sdk v3
Logo
globus-sdk v3

User Guide

  • Installation
  • Getting Started
    • Register an App in Globus Auth
    • Create a Minimal Script
    • Create a Minimal Script Without GlobusApp
  • Usage Patterns
    • Data Transfer
      • Initiating a Transfer
      • Scheduling a Repeating Transfer
      • Detecting data_access
      • Creating a Guest Collection
      • Setting a Relative Deadline for a Transfer
    • Sessions & Consents
      • Handling Authorization Parameters from a Transfer Operation

Reference

  • Service Clients
    • Globus Auth
    • Globus Compute
    • Globus Flows
    • Globus Groups
    • Globus Search
    • Globus Timers
    • Globus Transfer
    • Globus Connect Server API
  • Local Endpoints
  • Authorization
    • Globus App
      • GlobusApps
      • GlobusApp Configuration
    • Globus Authorizers
    • Scopes and Consents
      • Scopes and ScopeBuilders
      • MutableScopes
      • Consents
    • Login Flow Managers
    • Token Caching
      • Token Storages
      • Storage Adapters (Legacy)
    • Globus Auth Requirements Errors (GAREs)
  • Globus SDK Configuration
  • Globus SDK Core
    • BaseClient
    • Transport Layer
    • Responses
    • Paging and Paginators
    • Exceptions
    • Warnings
    • Utilities

Unstable

  • Globus SDK _testing
    • Getting Started with _testing
    • _testing Reference
    • _testing Method List
      • Globus Auth _testing Method List
      • Globus Groups _testing Method List
      • Globus Transfer _testing Method List
      • Globus Connect Server _testing Method List
      • Globus Timers _testing Method List
      • Globus Flows _testing Method List
      • Globus Search _testing Method List
  • Experimental Components
  • Updated Examples
    • OAuth2 at Globus
      • Using a GlobusApp

Examples

  • Globus SDK Examples
    • File Transfer Scripts
    • Manage Globus Auth Projects
    • Create & Run a Flow
    • Token Storage Adapters
    • Group Listing Script
    • Group Listing With Token Storage
    • API Authorization
    • Native App Login
    • Client Credentials Authentication
    • Three Legged OAuth with Flask
    • Recursive ls via TransferClient
    • Transfer Endpoint Type Enum
    • Timer Management
    • Guest Collection Creation Script

Changes

  • Versioning Policy
  • CHANGELOG
  • Upgrading

Additional Info

  • Apache License
Back to top
View this page

Globus Search¶

class globus_sdk.SearchClient(*, environment=None, base_url=None, app=None, app_scopes=None, authorizer=None, app_name=None, transport_params=None)[source]¶

Bases: BaseClient

Client for the Globus Search API

Parameters:
  • app (GlobusApp | None) – A GlobusApp which will be used for handling authorization and storing and validating tokens. Passing an app will automatically include a client’s default scopes in the app’s scope requirements unless specific app_scopes are given. If app_name is not given, the app’s app_name will be used. Mutually exclusive with authorizer.

  • app_scopes (list[Scope] | None) – Optional list of Scope objects to be added to app’s scope requirements instead of default_scope_requirements. Requires app.

  • authorizer (GlobusAuthorizer | None) – A GlobusAuthorizer which will generate Authorization headers. Mutually exclusive with app.

  • app_name (str | None) – Optional “nice name” for the application. Has no bearing on the semantics of client actions. It is just passed as part of the User-Agent string, and may be useful when debugging issues with the Globus Team. If both``app`` and app_name are given, this value takes priority.

  • base_url (str | None) – The URL for the service. Most client types initialize this value intelligently by default. Set it when inheriting from BaseClient or communicating through a proxy. This value takes precedence over the class attribute of the same name.

  • transport_params (dict[str, t.Any] | None) – Options to pass to the transport for this client

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.

Methods

  • batch_delete_by_subject()

  • create_entry()

  • create_index()

  • create_role()

  • delete_by_query()

  • delete_entry()

  • delete_index()

  • delete_role()

  • delete_subject()

  • get_entry()

  • get_index()

  • get_role_list()

  • get_subject()

  • get_task()

  • get_task_list()

  • index_list()

  • ingest()

  • post_search(), paginated.post_search()

  • reopen_index()

  • scroll(), paginated.scroll()

  • search(), paginated.search()

  • update_entry()

scopes: ScopeBuilder | None = <globus_sdk.scopes.builder.ScopeBuilder object>¶

the scopes for this client may be present as a ScopeBuilder

property default_scope_requirements: list[Scope]¶

Scopes that will automatically be added to this client’s app’s scope_requirements during _finalize_app.

For clients with static scope requirements this can just be a static value. Clients with dynamic requirements should use @property and must return sane results while the Base Client is being initialized.

create_index(display_name, description)[source]¶

Create a new index.

Parameters:
  • display_name (str) – the name of the index

  • description (str) – a description of the index

Return type:

GlobusHTTPResponse

New indices default to trial status. For subscribers with a subscription ID, indices can be converted to non-trial by sending a request to support@globus.org

sc = globus_sdk.SearchClient(...)
r = sc.create_index(
    "History and Witchcraft",
    "Searchable information about history and witchcraft",
)
print(f"index ID: {r['id']}")
{
  "@datatype": "GSearchIndex",
  "@version": "2017-09-01",
  "creation_date": "2021-04-05 15:05:18",
  "display_name": "Awesome Index of Awesomeness",
  "description": "An index so awesome that it simply cannot be described",
  "id": "f8929533-ed26-4651-ae7f-ac0565b2e8c5",
  "is_trial": true,
  "subscription_id": null,
  "max_size_in_mb": 1,
  "num_entries": 0,
  "num_subjects": 0,
  "size_in_mb": 0,
  "status": "open"
}

POST /v1/index

See Index Create in the API documentation for details.

delete_index(index_id)[source]¶

Mark an index for deletion.

Globus Search does not immediately delete indices. Instead, this API sets the index status to "delete-pending". Search will move pending tasks on the index to the CANCELLED state and will eventually delete the index.

If the index is a trial index, it will be deleted a few minutes after being marked for deletion. If the index is non-trial, it will be kept for 30 days and will be eligible for use with the reopen API (see reopen_index()) during that time.

Parameters:

index_id (UUID | str) – the ID of the index

Return type:

GlobusHTTPResponse

sc = globus_sdk.SearchClient(...)
sc.delete_index(index_id)
{
  "index_id": "974ab3a2-ed5d-4933-83e7-d4db527733b3",
  "acknowledged": true
}

DELETE /v1/index/<index_id>

See Index Delete in the API documentation for details.

reopen_index(index_id)[source]¶

Reopen an index that has been marked for deletion, cancelling the deletion.

Parameters:

index_id (UUID | str) – the ID of the index

Return type:

GlobusHTTPResponse

sc = globus_sdk.SearchClient(...)
sc.reopen_index(index_id)
{
  "index_id": "7d9129dd-2751-4ccc-a8d2-d6ea552ace56",
  "acknowledged": true
}

POST /v1/index/<index_id>/reopen

See Index Reopen in the API documentation for details.

get_index(index_id, *, query_params=None)[source]¶

Get descriptive data about a Search index, including its title and description and how much data it contains.

Parameters:
  • index_id (UUID | str) – the ID of the index

  • query_params (dict[str, Any] | None) – additional parameters to pass as query params

Return type:

GlobusHTTPResponse

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

GET /v1/index/<index_id>

See Index Show in the API documentation for details.

index_list(*, query_params=None)[source]¶

Get a list of indices on which the caller has permissions.

Parameters:

query_params (dict[str, Any] | None) – additional parameters to pass as query params

Return type:

IterableResponse

sc = globus_sdk.SearchClient(...)
for index_doc in sc.index_list():
    print(index_doc["display_name"], f"({index_doc['id']}):")
    print("  permissions:", ", ".join(index_doc["permissions"]))
{
  "index_list": [
    {
      "@datatype": "GSearchIndex",
      "@version": "2017-09-01",
      "id": "6824d27c-4187-11f0-a527-56de84ed1654",
      "is_trial": true,
      "status": "open",
      "subscription_id": null,
      "creation_date": "2038-07-17 16:48:24",
      "display_name": "Index of Indexed Awesomeness",
      "description": "Turbo Awesome",
      "max_size_in_mb": 1,
      "size_in_mb": 0,
      "num_subjects": 0,
      "num_entries": 0,
      "permissions": [
        "owner"
      ]
    },
    {
      "@datatype": "GSearchIndex",
      "@version": "2017-09-01",
      "id": "6824d34e-4187-11f0-a527-56de84ed1654",
      "is_trial": false,
      "status": "open",
      "subscription_id": "6824d3d0-4187-11f0-a527-56de84ed1654",
      "creation_date": "2470-10-11 20:09:40",
      "display_name": "Catalog of encyclopediae",
      "description": "Encyclopediae from Britannica to Wikipedia",
      "max_size_in_mb": 100,
      "size_in_mb": 23,
      "num_subjects": 1822,
      "num_entries": 3644,
      "permissions": [
        "writer"
      ]
    }
  ]
}

GET /v1/index_list

See Index List in the API documentation for details.

search(index_id, q, *, offset=0, limit=10, advanced=False, query_params=None)[source]¶

Execute a simple Search Query, described by the query string q.

Parameters:
  • index_id (UUID | str) – the ID of the index

  • q (str) – the query string

  • offset (int) – an offset for pagination

  • limit (int) – the size of a page of results

  • advanced (bool) – enable ‘advanced’ query mode, which has sophisticated syntax but may result in BadRequest errors when used if the query is invalid

  • query_params (dict[str, Any] | None) – additional parameters to pass as query params

Return type:

GlobusHTTPResponse

For details on query syntax, including the advanced query behavior, see the Search Query Syntax documentation.

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

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.

GET /v1/index/<index_id>/search

See GET Search Query in the API documentation for details.

{
  "@datatype": "GSearchResult",
  "@version": "2017-09-01",
  "count": 1,
  "gmeta": [
    {
      "@datatype": "GMetaResult",
      "@version": "2019-08-27",
      "entries": [
        {
          "content": {
            "foo": "bar"
          },
          "entry_id": null,
          "matched_principal_sets": []
        }
      ],
      "subject": "foo-bar"
    }
  ],
  "has_next_page": true,
  "offset": 0,
  "total": 10
}
post_search(index_id, data, *, offset=None, limit=None)[source]¶

Execute a complex Search Query, using a query document to express filters, facets, sorting, field boostring, and other behaviors.

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

  • data (dict[str, Any] | SearchQuery) – A Search Query document containing the query and any other fields

  • offset (int | None) – offset used in paging (overwrites any offset in data)

  • limit (int | None) – limit the number of results (overwrites any limit in data)

Return type:

GlobusHTTPResponse

For details on query syntax, including the advanced query behavior, see the Search Query Syntax documentation.

sc = globus_sdk.SearchClient(...)
query_data = {
    "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)

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.

POST /v1/index/<index_id>/search

See POST Search Query in the API documentation for details.

scroll(index_id, data, *, marker=None)[source]¶

Scroll all data in a Search index. The paginated version of this API should typically be preferred, as it is the intended mode of usage.

Note that if data is written or deleted during scrolling, it is possible for scrolling to not include results or show other unexpected behaviors.

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

  • data (dict[str, Any] | SearchScrollQuery) – A Search Scroll Query document

  • marker (str | None) – marker used in paging (overwrites any marker in data)

Return type:

GlobusHTTPResponse

For details on query syntax, including the advanced query behavior, see the Search Query Syntax documentation.

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

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.

POST /v1/index/<index_id>/scroll

See Scroll Query in the API documentation for details.

ingest(index_id, data)[source]¶

Write data to a Search index as an asynchronous task. The data can be provided as a single document or list of documents, but only one task_id value will be included in the response.

Parameters:
  • index_id (UUID | str) – The index into which to write data

  • data (dict[str, Any]) – an ingest document

Return type:

GlobusHTTPResponse

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)

POST /v1/index/<index_id>/ingest

See Ingest in the API documentation for details.

delete_by_query(index_id, data)[source]¶

Delete data in a Search index as an asynchronous task, deleting all documents which match a given query. The query uses a restricted subset of the syntax available for complex queries, as it is not meaningful to boost, sort, or otherwise rank data in this case.

A task_id value will be included in the response.

Parameters:
  • index_id (UUID | str) – The index in which to delete data

  • data (dict[str, Any]) – a query document for documents to delete

Return type:

GlobusHTTPResponse

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)

POST /v1/index/<index_id>/delete_by_query

See Delete By Query in the API documentation for details.

batch_delete_by_subject(index_id, subjects, additional_params=None)[source]¶

Delete data in a Search index as an asynchronous task, deleting multiple documents based on their subject values.

A task_id value will be included in the response.

Parameters:
  • index_id (UUID | str) – The index in which to delete data

  • subjects (Iterable[str]) – The subjects to delete, as an iterable of strings

  • additional_params (dict[str, Any] | None) – Additional parameters to include in the request body

Return type:

GlobusHTTPResponse

sc = globus_sdk.SearchClient(...)
sc.batch_delete_by_subject(
    index_id,
    subjects=[
        "very-cool-document",
        "less-cool-document",
        "document-wearing-sunglasses",
    ],
)
{
  "task_id": "68287c2e-4187-11f0-a527-56de84ed1654"
}

POST /v1/index/<index_id>/batch_delete_by_subject

See Delete By Subject in the API documentation for details.

get_subject(index_id, subject, *, query_params=None)[source]¶

Fetch exactly one Subject document from Search, containing one or more Entries.

Parameters:
  • index_id (UUID | str) – the index containing this Subject

  • subject (str) – the subject string to fetch

  • query_params (dict[str, Any] | None) – additional parameters to pass as query params

Return type:

GlobusHTTPResponse

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")

GET /v1/index/<index_id>/subject

See Get By Subject in the API documentation for details.

delete_subject(index_id, subject, *, query_params=None)[source]¶

Delete exactly one Subject document from Search, containing one or more Entries, as an asynchronous task.

A task_id value will be included in the response.

Parameters:
  • index_id (UUID | str) – the index in which data will be deleted

  • subject (str) – the subject string for the Subject document to delete

  • query_params (dict[str, Any] | None) – additional parameters to pass as query params

Return type:

GlobusHTTPResponse

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(...)
response = sc.delete_subject(index_id, "http://example.com/abc")
task_id = response["task_id"]

DELETE /v1/index/<index_id>/subject

See Delete By Subject in the API documentation for details.

get_entry(index_id, subject, *, entry_id=None, query_params=None)[source]¶

Fetch exactly one Entry document from Search, identified by the combination of subject string and entry_id, which defaults to null.

Parameters:
  • index_id (UUID | str) – the index containing this Entry

  • subject (str) – the subject string for the Subject document containing this Entry

  • entry_id (str | None) – the entry_id for this Entry, which defaults to null

  • query_params (dict[str, Any] | None) – additional parameters to pass as query params

Return type:

GlobusHTTPResponse

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")

GET /v1/index/<index_id>/entry

See Get Entry in the API documentation for details.

create_entry(index_id, data)[source]¶

This API method is in effect an alias of ingest and is deprecated. Users are recommended to use ingest() instead.

Create or update one Entry document in Search.

The API does not enforce that the document does not exist, and will overwrite any existing data.

Parameters:
  • index_id (UUID | str) – the index containing this Entry

  • data (dict[str, Any]) – the entry document to write

Return type:

GlobusHTTPResponse

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"},
    },
)

POST /v1/index/<index_id>/entry

See Create Entry in the API documentation for details.

update_entry(index_id, data)[source]¶

This API method is in effect an alias of ingest and is deprecated. Users are recommended to use ingest() instead.

Create or update one Entry document in Search.

This does not do a partial update, but replaces the existing document.

Parameters:
  • index_id (UUID | str) – the index containing this Entry

  • data (dict[str, Any]) – the entry document to write

Return type:

GlobusHTTPResponse

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"},
    },
)

PUT /v1/index/<index_id>/entry

See Update Entry in the API documentation for details.

delete_entry(index_id, subject, *, entry_id=None, query_params=None)[source]¶

Delete exactly one Entry document in Search as an asynchronous task.

A task_id value will be included in the response.

Parameters:
  • index_id (UUID | str) – the index in which data will be deleted

  • subject (str) – the subject string for the Subject of the document to delete

  • entry_id (str | None) – the ID string for the Entry to delete

  • query_params (dict[str, Any] | None) – additional parameters to pass as query params

Return type:

GlobusHTTPResponse

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")

DELETE  /v1/index/<index_id>/entry

See Delete Entry in the API documentation for details.

get_task(task_id, *, query_params=None)[source]¶

Fetch a Task document by ID, getting task details and status.

Parameters:
  • task_id (UUID | str) – the task ID from the original task submission

  • query_params (dict[str, Any] | None) – additional parameters to pass as query params

Return type:

GlobusHTTPResponse

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

GET /v1/task/<task_id>

See Get Task in the API documentation for details.

get_task_list(index_id, *, query_params=None)[source]¶

Fetch a list of recent Task documents for an index, getting task details and status.

Parameters:
  • index_id (UUID | str) – the index to query

  • query_params (dict[str, Any] | None) – additional parameters to pass as query params

Return type:

GlobusHTTPResponse

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

GET /v1/task_list/<index_id>

See Task List in the API documentation for details.

create_role(index_id, data, *, query_params=None)[source]¶

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 | str) – The index on which to create the role

  • data (dict[str, Any]) – The partial role document to use for creation

  • query_params (dict[str, Any] | None) – Any additional query params to pass

Return type:

GlobusHTTPResponse

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}"},
)

POST /v1/index/<index_id>/role

See Create Role in the API documentation for details.

get_role_list(index_id, *, query_params=None)[source]¶

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

Parameters:
  • index_id (UUID | str) – The index on which to list roles

  • query_params (dict[str, Any] | None) – Any additional query params to pass

Return type:

GlobusHTTPResponse

GET /v1/index/<index_id>/role_list

See Get Role List in the API documentation for details.

delete_role(index_id, role_id, *, query_params=None)[source]¶

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 | str) – The index from which to delete a role

  • role_id (str) – The role to delete

  • query_params (dict[str, Any] | None) – Any additional query params to pass

Return type:

GlobusHTTPResponse

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

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: 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, values, *, type='match_all', additional_fields=None)[source]¶

Add a filter subdocument to the query.

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

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

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

  • additional_fields (dict[str, Any] | None) – additional data to include in the filter document

Return type:

SearchQueryT

set_advanced(advanced)[source]¶

Enable or disable advanced query string processing.

Parameters:

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

Return type:

SearchQueryT

set_limit(limit)[source]¶

Set the limit for the query document.

Parameters:

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

Return type:

SearchQueryT

set_query(query)[source]¶

Set the query string for the query document.

Parameters:

query (str) – the new query string

Return type:

SearchQueryT

class globus_sdk.SearchQuery(q=None, *, limit=None, offset=None, advanced=None, additional_fields=None)[source]¶

Bases: SearchQueryBase

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

Parameters:
  • q (str | None) – The query string. Required unless filters are used.

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

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

  • advanced (bool | None) – 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[str, t.Any] | None) – 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, factor, *, additional_fields=None)[source]¶

Add a boost subdocument to the query.

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

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

  • additional_fields (dict[str, Any] | None) – additional data to include in the boost document

Return type:

SearchQuery

add_facet(name, field_name, *, type='terms', size=None, date_interval=None, histogram_range=None, additional_fields=None)[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 | None) – the size parameter for the facet

  • date_interval (str | None) – the date interval for a date histogram facet

  • histogram_range (tuple[Any, Any] | None) – a low and high bound for a numeric histogram facet

  • additional_fields (dict[str, Any] | None) – additional data to include in the facet document

Return type:

SearchQuery

add_sort(field_name, *, order=None, additional_fields=None)[source]¶

Add a sort subdocument to the query.

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

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

  • additional_fields (dict[str, Any] | None) – additional data to include in the sort document

Return type:

SearchQuery

set_offset(offset)[source]¶

Set the offset for the query document.

Parameters:

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

Return type:

SearchQuery

class globus_sdk.SearchQueryV1(*, q=MISSING, limit=MISSING, offset=MISSING, advanced=MISSING, filters=MISSING, facets=MISSING, post_facet_filters=MISSING, boosts=MISSING, sort=MISSING, additional_fields=MISSING)[source]¶

Bases: PayloadWrapper

A specialized dict which has helpers for creating and modifying a Search Query document. Replaces the usage of SearchQuery.

Parameters:
  • q (str | utils.MissingType) – The query string. Required unless filters are used.

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

  • offset (int | utils.MissingType) – An offset into the set of all results for the query

  • advanced (bool | utils.MissingType) – 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

  • filters (list[dict[str, t.Any]] | utils.MissingType) – a list of filters to apply to the query

  • facets (list[dict[str, t.Any]] | utils.MissingType) – a list of facets to apply to the query

  • post_facet_filters (list[dict[str, t.Any]] | utils.MissingType) – a list of filters to apply after facet results are returned

  • boosts (list[dict[str, t.Any]] | utils.MissingType) – a list of boosts to apply to the query

  • sort (list[dict[str, t.Any]] | utils.MissingType) – a list of fields to sort results

  • additional_fields (dict[str, t.Any] | utils.MissingType) – additional data to include in the query document

class globus_sdk.SearchScrollQuery(q=None, *, limit=None, advanced=None, marker=None, additional_fields=None)[source]¶

Bases: 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 | None) – The query string

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

  • advanced (bool | None) – 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 | None) – the marker value

  • additional_fields (dict[str, t.Any] | None) – additional data to include in the query document

set_marker(marker)[source]¶

Set the marker on a scroll query.

Parameters:

marker (str) – the marker value

Return type:

SearchScrollQuery

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)[source]¶

Bases: GlobusAPIError

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

Variables:

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

Next
Globus Timers
Previous
Globus Groups
Copyright © 2016-2025, Globus
Made with Sphinx and @pradyunsg's Furo
On this page
  • Globus Search
    • SearchClient
      • SearchClient.scopes
      • SearchClient.default_scope_requirements
      • SearchClient.create_index()
      • SearchClient.delete_index()
      • SearchClient.reopen_index()
      • SearchClient.get_index()
      • SearchClient.index_list()
      • SearchClient.search()
      • SearchClient.post_search()
      • SearchClient.scroll()
      • SearchClient.ingest()
      • SearchClient.delete_by_query()
      • SearchClient.batch_delete_by_subject()
      • SearchClient.get_subject()
      • SearchClient.delete_subject()
      • SearchClient.get_entry()
      • SearchClient.create_entry()
      • SearchClient.update_entry()
      • SearchClient.delete_entry()
      • SearchClient.get_task()
      • SearchClient.get_task_list()
      • SearchClient.create_role()
      • SearchClient.get_role_list()
      • SearchClient.delete_role()
    • Helper Objects
      • SearchQueryBase
        • SearchQueryBase.add_filter()
        • SearchQueryBase.set_advanced()
        • SearchQueryBase.set_limit()
        • SearchQueryBase.set_query()
      • SearchQuery
        • SearchQuery.add_boost()
        • SearchQuery.add_facet()
        • SearchQuery.add_sort()
        • SearchQuery.set_offset()
      • SearchQueryV1
      • SearchScrollQuery
        • SearchScrollQuery.set_marker()
    • Client Errors
      • SearchAPIError