Search API Menu
  • Globus Search
  • Overview
  • API Usage & Basics
  • Ingest
  • Query
  • Types, Type Detection, and Schemas
  • Error Handling
  • API Reference
    • Create or Update Entry
    • Delete by Query
    • Delete by Subject
    • Delete Entry
    • Get Entry
    • GET Query
    • Get Subject
    • Get Task
    • Index Create (BETA)
    • Index Delete (BETA)
    • Index List
    • Index Reopen (BETA)
    • Ingest
    • POST Query
    • Role Create
    • Role Delete
    • Role List
    • Scroll Query
    • Show Index
    • Task List
  • Guides
    • Geospatial Search
    • Role Based Filtering
    • Searchable Files
  • Globus Search Limits
  • API Change History
Skip to main content
Globus Docs
  • APIs
    Auth Flows Groups Search Transfer Python SDK Helper Pages
  • How To
  • Guides
    Globus Connect Server High Assurance Collections for Protected Data Command Line Interface Premium Storage Connectors Security Modern Research Data Portal
  • Support
    FAQs Mailing Lists Contact Us Check Support Tickets
  1. Home
  2. Globus APIs
  3. Globus Search
  4. Guides

Role Based Filtering

In order to implement role-based filtering of search results, you need to use the principal_sets feature.

You must have an index where you have write permissions, and you must know the Group IDs or Identity IDs of the users and groups for whom you want to assign roles in your data.

API Methods

We will leverage these API methods:

Ingest API

Submit an Ingest Task

Get Query

Perform a simple query

You must have a means to use these APIs. For example, the Globus CLI.

Step 1: Identify Roles for Data

For the purposes of example, we will assume that we have two users, with IDs I and J, and groups with IDs G and H.

Furthermore, we’ll define roles on a few documents as follows:

Table 1. Document-to-Roles

doc0

No roles

doc1

I and J are admin, G is monitor

doc2

H is monitor

Let us assume, for simplicity, that doc0, doc1, and doc2 are all public data.

Note

Roles and visible_to are orthogonal and can both apply correctly to the same search.

In order to appear in search results, you must match both criteria if they are used.

Step 2: Define a GIngest document which encodes these roles

Using principal_sets, we would notate this by putting I, J, G, and H into Principal URNs and assigning them to each document.

Wrapping this in a GIngest document, we would see something like so:

Example 1. GIngest with principal_sets
{
  "ingest_type": "GMetaList",
  "ingest_data": {
    "gmeta": [
      {
        "subject": "doc0",
        "visible_to": ["public"],
        "content": {
          "foo": "value0"
        }
      },
      {
        "subject": "doc1",
        "visible_to": ["public"],
        "principal_sets": {
          "admin": [
            "urn:globus::auth:identity:I",
            "urn:globus::auth:identity:J"
          ],
          "monitor": [
            "urn:globus:groups:id:G"
          ]
        },
        "content": {
          "foo": "value1"
        }
      },
      {
        "subject": "doc2",
        "visible_to": ["public"],
        "principal_sets": {
          "monitor": [
            "urn:globus:groups:id:H"
          ]
        },
        "content": {
          "foo": "value2"
        }
      }
    ]
  }
}

We don’t care much about the content for this example, so each contains only one field, foo.

Step 3: Query the data

In order to query this data, use the filter_principal_sets parameter.

For example, I and J would find only doc1 if they query in the form

GET /v1/index/<index_id>/search?q=*&filter_principal_sets=admin

If I is a member of group H, they would find doc1 and doc2 with the query

GET /v1/index/<index_id>/search?q=*&filter_principal_sets=admin,monitor

For any user, the following query is valid but returns no results:

GET /v1/index/<index_id>/search?q=*&filter_principal_sets=nosuchrole
  • Globus Search
  • Overview
  • API Usage & Basics
  • Ingest
  • Query
  • Types, Type Detection, and Schemas
  • Error Handling
  • API Reference
    • Create or Update Entry
    • Delete by Query
    • Delete by Subject
    • Delete Entry
    • Get Entry
    • GET Query
    • Get Subject
    • Get Task
    • Index Create (BETA)
    • Index Delete (BETA)
    • Index List
    • Index Reopen (BETA)
    • Ingest
    • POST Query
    • Role Create
    • Role Delete
    • Role List
    • Scroll Query
    • Show Index
    • Task List
  • Guides
    • Geospatial Search
    • Role Based Filtering
    • Searchable Files
  • Globus Search Limits
  • API Change History
© 2010- The University of Chicago Legal Privacy Accessibility