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 Data Governance Center 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 and, if set (default), can lead to the same search with different results in Collibra Data Governance Center 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.

Wildcard character

Usage

Search example

Result example

? Replaces exactly one character. iss?e issue
* Replaces none or more characters. compl* completeness, compliance
~

Performs a fuzzy search.

You must place the wildcard character after the search term.

application~ applications, duplication
! or -

Excludes results that contain the search term.

You must place the wildcard character before the search term.

business !new or business -new Business Analysts Community but not New Business Terms
+

Excludes results that do not contain the search term.

You must place the wildcard character before the search term.

business +new New Business Terms and New Applications but not Business Analysts Community
&&

Excludes results that do not contain all the search terms.

You must place the wildcard character between the search terms.

new && data New Reference Data and New Data Assets
" "

Performs an exact search.

You must escape the double quotation marks: \"

\"policy issue\" Data Policy Issue
" "~n Performs an exact search with no or up to n words between the search terms. \"policy issue\"~2 Data Policy Issue and Policy non Compliance Issue
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.

Filter

Field name

Description

Search filter filters A filter to refine the search results based on specific types, statuses, dates and tags of the returned resources.
Search in fields searchInFields A filter to refine the search results based on the occurrence of the search term in specific fields of resource types.

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:

field

values as array of strings

Result

community One or more community UUIDs Only resources that belong to the selected communities, excluding communities.
domain One or more domain UUIDs Only resources that belong to the selected domains, excluding domains and communities.
domainType One or more domain type UUIDs Only domains that are of the selected domain type.
assetType One or more asset type UUIDs Only assets that are of the selected asset types.
status One or more status UUIDs Only assets that have the selected statuses.
createdBy One or more user UUIDs Only resources created by the selected users.
lastModifiedOn Exactly one of the following values: LAST_24H, LAST_7D, LAST_30D, LAST_365D, OLDER_THAN_365D Only resources that were last modified in the selected time period.
createdOn Only resources that were created in the selected time period.
tags One or more tags Only assets with the selected tags.

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 made up 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:

resourceType

fields as array of strings

Result

community Possible values are name and comments Only communities that have the search term in their name or comments.
domain Only domains that have the search term in their name or comments.
asset Possible values are name, displayName, comments, tags, dataClassification, attributes and attribute:<attribute_type_UUID> Only assets that have the search term in the selected fields. attributes refers to all the attribute types of an asset while the pair attribute:<attribute_type_UUID> only refers to one specific attribute type.
user name Only users that have the search term in their name.
userGroup Only user groups that have the search term in their name.

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.

Example

Valid

Reason

"searchInFields": [
  {
    "resourceType": "domain",
    "fields": ["name", "comments"]
  },
  {
    "resourceType": "user",
    "fields": ["name"]
  }
]
Yes The only common fields value for the pairs is name and both pairs contain it.
"searchInFields": [
  {
    "resourceType": "domain",
    "fields": ["name", "comments"]
  },
  {
    "resourceType": "asset",
    "fields": ["name"]
  }
]
No

The equivalent of name for asset is displayName.

comments is also available for asset but not specified.

The correct pair should be:

{
  "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.