Search API Menu

Globus SearchOverviewAPI Usage & BasicsIngestQueryTypes, Type Detection, and SchemasError Handling
API Reference
Create or Update EntryDelete by QueryDelete by SubjectDelete EntryGet EntryGET QueryGet SubjectGet TaskIngestPOST QueryQuery Template APIsScroll QueryShow IndexTask List
Guides
Role Based Filtering
Globus Search LimitsAPI Change History
Globus Docs
  • APIs
    • Auth
    • Transfer
    • Groups
    • Search
    • Python SDK
    • Helper Pages
  • How To
  • Guides
    • Globus Connect Server Installation Guides
    • High Assurance Collections for Protected Data
    • Management Console Guide
    • 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. API Reference

Create or Update Entry

Create or update a single entry in a Search Index. This API submits an asynchronous (ingest) task.

This returns a task_id which can be used to monitor thestatus of the task. You must have permissions to write to the index.

Method

POST or PUT

URL

/v1/index/<index_id>/entry

Authentication required?

Yes

Required Roles

You must have either admin, writer access

Request Body

A GMetaEntry

Response Body

An IngestResponse

These scopes are valid for authenticated calls:

Authentication & Authorization

Tokens for this call must have one of these scopes.

urn:globus:scopes:search.api.globus.org:all
urn:globus:scopes:search.api.globus.org:ingest

Examples

Create an entry (1)

  • in the index 4de0e89e-a395-11e7-bc54-8c705ad34f60

  • with a subject of https://example.com/foo/bar

  • with a null entry_id

  • public visibility

curl -XPOST 'https://search.api.globus.org/v1/index/4de0e89e-a395-11e7-bc54-8c705ad34f60/entry' \
    --data '{
      "subject": "https://example.com/foo/bar",
      "visible_to": ["public"],
      "content": {
        "foo/bar": "some val"
      }
    }'

Create an entry (2)

  • in the index 4de0e89e-a395-11e7-bc54-8c705ad34f60

  • with a subject of https://example.com

  • with an entry_id of foo/bar

  • public visibility

curl -XPOST 'https://search.api.globus.org/v1/index/4de0e89e-a395-11e7-bc54-8c705ad34f60/entry' \
    --data '{
      "subject": "https://example.com",
      "id": "foo/bar",
      "visible_to": ["public"],
      "content": {
        "foo/bar": "some val"
      }
    }'

Update an entry

  • in the index 4de0e89e-a395-11e7-bc54-8c705ad34f60

  • with a subject of https://example.com/foo/bar

  • with a null entry_id

  • visible only to globus@globus.org (which has ID 46bd0f56-e24f-11e5-a510-131bef46955c)

curl -XPUT 'https://search.api.globus.org/v1/index/4de0e89e-a395-11e7-bc54-8c705ad34f60/entry' \
    --data '{
      "subject": "https://example.com/foo/bar",
      "visible_to": ["urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c"],
      "content": {
        "foo/bar": "some new val"
      }
    }'

Request Schemas

GMetaEntry

A GMetaEntry is a single block of data pertaining to a given subject.

Field Name Type Description

subject

String

The entity described by this metadata, typically a URI

visible_to

Array of Strings

This is a list of security principals allowed to read the metadata. Each string will be in the form of a Principal URN, or the special string "public".

content

Object

A GMetaContent. This is the actual metadata to assert about subject

id

String

Optional. A unique identifier for this metadata entry. This value will be used on further API operations which reference this entry such as updates or delete. When id is not provided, it is assumed to have a default "null" value.

Example 1

{
  "subject": "https://search.api.globus.org/abc.txt",
  "visible_to": ["public"],
  "content": {
    "http://transfer.api.globus.org/metadata-schema/file#type": "file"
  }
}

Example 2

{
  "subject": "https://search.api.globus.org/abc.txt",
  "mimetype": "application/json",
  "visible_to": ["urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c"],
  "id" : "visible_to_globus@globus.org",
  "content": {
    "http://transfer.api.globus.org/metadata-schema/file#type": "file",
    "http://transfer.api.globus.org/metadata-schema/file#extension": "txt",
    "http://transfer.api.globus.org/metadata-schema/file#name" : "abc.txt"
  }
}

This document is a superset of Example 1, but is only visible to the user globus@globus.org. This demonstrates how multiple entries about the same subject, but with different IDs, can be useful: some data is only visible to certain users or groups, while other data is public.

GMetaContent

GMetaContent is arbitrary structured data provided by data sources for Globus Search. It has only one special field, @context.

Field Name Type Description

@context

Object

A set of shorthands which will be expanded in all other fields of the document

The @context field is used to define a shorthand for values which are interpolated into the document keys. To best understand, see the examples section.

Special Note: Long Fields

All text or string type fields are constrained on their total length when used for faceting or sorting. A record containing more than 10,000 characters in a field will not appear in any facet buckets for that field. A record which contains more than 10,000 characters will appear at the end of any sort operation on that field even though it may lexically appear earlier in the list.

Example 1

{
  "@context": {
    "f": "file_meta"
  },
  "f:type": "file",
  "f:extension": "txt",
  "f:name" : "abc.txt"
}

which is equivalent to and will be expanded as:

{
  "file_meta#type": "file",
  "file_meta#extension": "txt",
  "file_meta#name": "abc.txt"
}

Response Schemas

IngestResponse

Field Name Type Description

task_id

UUID

The ID of the submitted Task

as_identity

String

The principal URN of the caller’s primary ID

success

Boolean

This is a deprecated field kept for backwards compatibility. Always true

num_documents_ingested

Integer

This is a deprecated field kept for backwards compatibility. Always 0

Globus SearchOverviewAPI Usage & BasicsIngestQueryTypes, Type Detection, and SchemasError Handling
API Reference
Create or Update EntryDelete by QueryDelete by SubjectDelete EntryGet EntryGET QueryGet SubjectGet TaskIngestPOST QueryQuery Template APIsScroll QueryShow IndexTask List
Guides
Role Based Filtering
Globus Search LimitsAPI Change History
© 2010- The University of Chicago Legal Accessibility