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 `owner`, `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

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"
      }
    }'

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"
      }
    }'

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 data, typically a URI or other identifier for the document in question.
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 strings `"public"` or `"all_authenticated_users"`.
principal_sets	Object	A mapping from strings to lists of principals in Principal URN format. These allow for search results to be filtered based on a user’s principals (identities and groups) using the `filter_principal_sets` query feature. The `principal_sets` of an entry do not impact visibility positively or negatively. They only apply as filters when `filter_principal_sets` is used. `principal_sets` also appear in search results in the `matched_principal_sets` field.
content	Object	An arbitrary object containing data. This is the actual data which will be indexed and queryable.
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.

Warning

For older indices, @context is a field within content with special meaning.

{
  "subject": "https://search.api.globus.org/robots.txt",
  "visible_to": ["public"],
  "content": {
    "type": "file"
  }
}

{
  "subject": "https://search.api.globus.org/robots.txt",
  "mimetype": "application/json",
  "visible_to": ["urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c"],
  "id" : "visible_to_globus@globus.org",
  "content": {
    "type": "file",
    "extension": "txt",
    "name" : "robots.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.

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

This document is a similar to the others, but includes a principal_sets declaration listing globus@globus.org under the admin set. The document is visible to all_authenticated_users — meaning anyone can see it once they login.

For most users, the admin list is not visible, but for globus@globus.org, the search results will include "matched_principal_sets": ["admin"]. A query by this user with filter_principal_sets=admin would return the document, but a query with filter_principal_sets=monitor (not listed here) would not.

This demonstrates how principal_sets can be used to implement role-based filtering on documents without impacting visibility.

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.

Content Schema is Recorded

The format and schema of content must match any existing documents in your index.

For example, if last_modified is a field in content which is formatted as a date, and parsed as a date (see Type Detection), then last_modified must always be formatted as a date. Passing an integer, String, Object, or other datatype will cause the ingest task to fail.

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`