Search API

Description

This feature gives authorized users access to our internal Search API, allowing users to see search results without having to navigate through the Alation UI. This should allow customers to integrate Search functionality outside of Alation, or simply access search results quickly in a programmatic manner either through the browser or hitting the endpoint directly.

OpenAPI 3.0 Specification

The Search API uses the OpenAPI 3.0 Specification (OAS). OAS is a broadly adopted industry standard for describing APIs.

To see the specification, replace {AlationInstanceURL} below with your Alation instance's URL and visit the link:

{AlationInstanceURL}/openapi/search/

NOTE:

1. This API is available in Alation 2021.1 and later.
   
2. The OpenAPI UI is not enabled by default on an Alation instance. Please set the flag alation.feature_flags.enable_swagger to True using alation_conf.
   

Configuration Steps/Usage

• Search API endpoint can be visited in browser or accessed programmatically using a GET request at: {alation_domain}/integration/v1/search/
• The request must include a valid user token

Example Usage

See below for some examples using this API.

Search & Parameters

• How similar is the Search API to the existing Full Search Page? Search API results should match results found when navigating to the full_search_url returned in the response. However, there are the following caveats:
  • Search API does not currently support all the parameters present on Full Search. These are the permitted params (please see intractable UI for the Search API by visiting {alation_domain}/openapi/search/ for more detailed information):
    • q: String; Query string to search for—you can use quotes for an exact match and an asterisk as a wildcard
    • limit: Integer; Maximum number of results to return in request
    • offset: Integer; Index of first search result to return from full result set
    • filters: Object; Filters object used to restrict search results. These are the permitted filter object properties:
      • starred: Boolean; restrict results to objects marked "Starred" by the requesting user
      • watching: Boolean; restrict results to objects marked "Watching" by the requesting user
      • recent: Boolean; restrict results to objects marked "Recent", indicating whether the object was recently visited by the requesting user
      • flags: Array; restrict results to objects with specified flags present on the result object
      • otypes: Array; restrict results to objects with specified otypes.
  • Search API allows passing any combination of otypes, but the Full Search page does not. The only combinations allowed in Full Search are within the same otype set. This means that "otypes":["table", "schema"] works on Full Search, but "otypes":["table", "file"] does not. Below are the relevant otype sets:
    • API Resource Otypes: api_resource, api_resource_field, api_resource_folder
    • BI Otypes: bi_field, report_collection, report_datasource, report_object, report_source
    • Data Otypes: column, datasource, doc_schema, docstore_collection, docstore_folder, schema, table, value
    • File Otypes: file, filesystem

Response

Please see the above recipe for an example output.

• What are "breadcrumbs"?
  * The Breadcrumbs array in the response represents the hierarchy of objects that the result object belongs to. For example, a Column object may have a Datasource breadcrumb and a Table breadcrumb. Breadcrumbs are returned in highest → lowest order (eg Datasource, then Table).

• What is the difference between "name" and "title"?
  * Throughout the Alation app, title is a field that can be changed through our UI, while name represents a characteristic of the underlying data object that we cannot change. For example, DataSources have a title (which can be changed), while BIFolders have a name (which is imported form the BI source and cannot be changed)

• What are "highlights"?
  * When providing a keyword to search for (the param q), the Search API will return a highlight, which is a portion of surrounding text within which the keyword is found in the result object fields. For example, searching /integration/v1/search/?q=smile would return result objects that may contain a highlight snippet that looks like "I like to smile every morning, smile every evening".

• What are "offsets" within "highlights"?
  * Within highlights, the offset arrays show the start and end indices for the matching keyword within the highlight snippet text. For example, searching /integration/v1/search/?q=smile would return result objects that may contain a highlight snippet that looks like "I like to smile every morning, smile every evening", and offsets would look like: [[10, 14], [31, 35]] since the word "smile" is found in the snippet text at index 10→14 and 31→35.

• I added/updated data but Search results look stale. Why is this happening and how can I update the data?
  * Indexing can take some time to complete, especially if the change(s) made are far-reaching. To see the status of reindexing, Click on Settings → Monitor. If you see update_search_index in the Active Tasks tab, it is still underway.

Error Codes

If you do not receive a 200 OK Response, please check the following: