Content Search

Seismic public search API provides our customers and partners a programmatic interface to search Seismic content. Developers can query all content that a user has access to using a search term, and further apply a content filter, specify return fields, and sort the search results.

SCOPES

Requires: seismic.search See Permissions for additional details.

REQUEST HEADERS

The client details object must contain at least the property “application“, representing the application name with which the search activity will be tagged.
Example client details object:

{ "application": "application1" }

BODY PARAMETER DEFINITIONS

Search Term (Optional)

term specifies the search term against which Seismic search service matches content.

{ "term": "test" }

for example, conducts a full text search for all content containing "test".

Correspondingly, a query not specifying a search term or simply providing a completely empty query body, such as

empty or `{}`

queries all content.

Search Fields (Optional)

searchFields specifies where in the content Seismic search service conducts the search.

A query can set searchFields to be a subset of the fields in the table below. By default, Seismic search service searches all fields.

For example,

{"term":"test","options":{"searchFields":["name","properties"]}}

searches for content containing search term "test" in its name or custom properties.

Return Fields (Optional)

returnFields specifies the content property fields that Seismic search service returns for matching content found.

A query can set returnFields to be a subset of the fields in the table below.

For example,

{"term":"test", "options":{"returnFields":["name", "type"]}}

searches for all content containing "test", and returns only the name and type of the matching content found.

When a query does not explicitly specify the return fields, Seismic search service returns all fields in the table above where "Return by default?" is "Yes".

Sort Fields (Optional)

A query can sort search results returned by the following fields:

For example, the following query searches for all content containing "test", returns default fields, and sorts the returned search results by content name in ascending / descending order.

{"term":"test", "sort":[{"field":"name","order":"asc|desc"}]}

Multiple sort fields can be specified to sort search results on multiple fields.
If no sort criteria is provided, Seismic search service returns results sorted by relevance.

Filtering (Optional)

Seismic search service supports filtering through a filter expression in the query. A filter expression can be a single condition or multiple conditions and / or filters connected by filter operators.

Filter Fields

Fields that can be used in filter condition.

Note: date format should follow RFC 3339. For more details, please refer to Conventions and Formats
Supported date examples: 2018-01-01T08:00:00+00:00 2018-01-01T08:00:00 2018-01-01T08:00:00Z 2018-01-01.

Condition Operators

Seismic search service supports the following condition operators:

For example, to filter content from Seismic that satisfies

`repository="library"`,

we can set up a filter with a single condition:

{
  "filter": {
    "operator": "and",
    "conditions":[
      {
        "attribute": "repository",
        "operator": "equal",
        "value": "library"
      }
    ]
  }
}

Note: operator must be provided even though there is only one condition

As another example, to filter content from Seismic that satisfies

`profile in ("Profile A","Profile B")`,

we can set up a filter using the in operator:

{
  "filter": {
    "operator": "and",
    "conditions": [
      {
        "attribute": "profile",
        "operator": "in",
        "value": [
          "Profile A",
          "Profile B"
        ]
      }
    ]
  }
}

Filter Operators

Seismic search service supports and, or filter operators. We can use these filter operators to construct more complex filters.

For example, to filter content from Seismic that satisfies

`repository="library" AND format="TXT"`,

we can use the and operator to set up the following filter:

{
  "filter": {
    "operator": "and",
    "conditions": [
      {
        "attribute": "repository",
        "operator": "equal",
        "value": "library"
      },
      {
        "attribute": "format",
        "operator": "equal",
        "value": "TXT"
      }
    ]
  }
}

Note: currently the max filter depth is 2.

To demonstrate a filter of maximum depth of 2, we can query for content that satisfies

`latestApprovedVersion=true AND ((repository="library" AND format="TXT") OR (repository="workspace" AND format="PPTX"))`.

The corresponding filter using the combination of and and or operators is:

{
  "filter": {
    "operator": "and",
    "conditions": [
      {
        "attribute": "latestVersion",
        "operator": "equal",
        "value": true
      }
    ],
    "filters": [
      {
        "operator": "or",
        "filters": [
          {
            "operator": "and",
            "conditions": [
              {
                "attribute": "repository",
                "operator": "equal",
                "value": "library"
              },
              {
                "attribute": "format",
                "operator": "equal",
                "value": "TXT"
              }
            ]
          },
          {
            "operator": "and",
            "conditions": [
              {
                "attribute": "repository",
                "operator": "equal",
                "value": "workspace"
              },
              {
                "attribute": "format",
                "operator": "equal",
                "value": "PPTX"
              }
            ]
          }
        ]
      }
    ]
  }
}

Filter Expression

In general, a filter is constructed with a group of conditions and a group of filters. The items in conditions and filters are connected with same operator.
A condition is a single conditional expression (e.g. repository="library"), whereas a filter is a logical grouping of conditions. filters can be empty or a list of filters, as described above.
operator is always needed in a filter expression.

{
  "filter": {
    "operator": "and|or",
    "conditions": [
      {
        "attribute": "field name",
        "operator": "in|equal|greaterThan|greaterThanOrEqual|lessThan|lessThanOrEqual",
        "value": "value that needs to match"
      }
    ],
    "filters": []
  }
}

Page Size (Optional)

Seismic search service organizes search results returned by pages. Page size, which specifies the number of search results that a page can hold, ranges between 0 and 100, with a default value of 40.

To specify a page size of 5, we can use:

{"options":{"pageSize":5}}

Pagination

If search results span multiple pages, the response will contain a continuationToken property of non-null value. A request with parameter ?continuationToken=<continuationTokenValue> in the request URL fetches the next page of the search results, and body is not required in this case.

Validation Rules And Errors

Seismic search service performs validation on incoming requests. The table below provides validation rules, error codes, and corresponding error messages. If there are multiple errors in the request, only the first one captured is returned.