Search Overview

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

You can access an intractable UI for the Search API by vising the below URL. 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 {alation_domain} below with your Alation instance's URL and visit the link: {alation_domain}/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 Otypescolumn, 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.

17141714

Error Codes

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

Type of ErrorWhen it happensWhat to do
400 "Malformed Request"Request parameters are not in the correct formatPlease double check the request format- is the filters param correctly encoded?
401 "Unauthorized"No authorization providedPlease confirm you are passing a user token with the request
403 "Forbidden Action"No authorization provided, or User is not permitted to access Search APIPlease confirm you are passing a user token with the request. Please check if the user token being used corresponds to a user who has permission to access the Search API
404 "Resource not found"Page not foundPlease double check the url and endpoint; the API exists at /integration/v1/search/
429 "Too many requests"Too many simultaneous API callsThis can be resolved by increasing the Search API throttling rate (which defaults to 20/sec), but that could potentially result in other performance related issues, including 500 Errors.alation_conf alation.api.throttling.search.read -s <newRate>
500 "Internal Server Error"Internal Server Error, or Front End Web Application ErrorIf this is a Server error, useful information may be available in the Alation Server logs or the Celery job logsIf this is due to an error in the Front End Web Application when accessing the endpoint through the browser, there is likely to be verbose error information in the Browser Console.