Getting started with the Search API

In this tutorial you perform your first query with the Collibra REST Search API. You use wildcard characters to expand your search and filters to refine it.

curl -X POST 'https://<your_collibra_url>/rest/2.0/search' \
-H 'Content-Type: application/json' \
-d '{
  "keywords": "issue"
}'

All of the examples in this tutorial work with the out-of-the-box resources created during the installation of the Collibra platform.

Prerequisites

• Access to Collibra Data Governance Center.
• Postman or an alternative HTTP API client.

  Some references might be specific to the Postman application.

For more information on how to install Postman and establish an authentication session, see the Collibra REST API authentication tutorial.

About the Collibra REST Search API

The Search API allows you to take advantage of the same engine that powers the Collibra user interface search. It uses the same wildcard characters as the UI search and the search results are influenced by the same Search index configuration settings in Console.

The UI search appends wildcard * setting only applies to the UI search without any impact on the API search. If set (default), it can lead to the same search having different results in Collibra and the Search API.

The search request

The search request is a JSON object. The simplest request contains the only mandatory field that represents the search term:

{
  "keywords": "search term"
}

Wildcards

To expand your search, you can use the same wildcard characters available in the user interface search.

curl -X POST 'https://<your_collibra_url>/rest/2.0/search' \
-H 'Content-Type: application/json' \
-d '{
  "keywords": "\"policy issue\""
}

Filters

You can narrow down you search results by indicating what kind of resource to return or where to look for the search term in a resource.

You can use both types of filters at the same time.

Search filter

The search filter is an array of objects made up of field and values pairs:

curl -X POST 'https://<your_collibra_url>/rest/2.0/search' \
-H 'Content-Type: application/json' \
-d '{
  "keywords": "data",
  "filters": [
    {
      "field": "assetType",
      "values": ["00000000-0000-0000-0000-000000031112"]
    }
  ]
}'

You can combine each field value with certain values values:

The field / values pairs are joined using the logical AND operator, unless the same key is repeated and they are joined using the OR operator. The elements of the values arrays are joined using the logical OR operator.

Some combinations will not return results because the filters refer to different types of resources, for example a combination of domainType and tags returns 0 results because domains do not have tags.

Search in fields

The search in fields filter is an array of objects consisting of resourceType and fields pairs:

curl -X POST 'https://<your_collibra_url>/rest/2.0/search' \
-H 'Content-Type: application/json' \
-d '{
  "keywords": "data",
  "searchInFields": [
    {
      "resourceType": "domain",
      "fields": ["name"]
    }
  ]
}'

You can combine each resourceType value with certain fields values:

The resourceType / fields pairs are joined using the logical OR operator. For the request to be valid, if one of the fields values is available for the other pairs, it must be present in all the pairs.

The equivalent of name for asset is displayName.

"searchInFields": [
  {
    "resourceType": "domain",
    "fields": ["name", "comments"]
  },
  {
    "resourceType": "user",
    "fields": ["name"]
  }
]

"searchInFields": [
  {
    "resourceType": "domain",
    "fields": ["name", "comments"]
  },
  {
    "resourceType": "asset",
    "fields": ["name"]
  }
]

{
  "resourceType": "asset",
  "fields": ["displayName", "comments"]
}

The elements of the fields arrays are joined using the logical OR operator.

The Search API REST call

To perform a search, use the POST method and the /search endpoint of the Search resource.

There are no parameters but you must include the JSON body.

curl -X POST 'https://<your_collibra_url>/rest/2.0/search' \
-H 'Content-Type: application/json' \
-d '{
  "keywords": "issue",
  "searchInFields": [
    {
      "resourceType": "domain",
      "fields": ["name"]
    }
  ]
}'

The response contains the total number of results and the details for each result.

Summary

By following this tutorial:

• You have learned about the following components of the Collibra REST Search API:
  • The JSON object.
  • Wildcard characters.
  • The search filter.
  • The search in fields filter.
  • The API call.

Additional resources

• Consult the Collibra REST Import API documentation provided with your version of Collibra Data Governance Center at https://<your_collibra_url>/api-docs/index.html?urls.primaryName=search-api.