Skip to main content

Making advanced search queries

API resources

This article refers to the following API resources:

  • Method: POST
  • Endpoint: /search
  • Description: Search specific sets of objects with filters.
  • Authentication: Bearer token

Overview​

The search feature has a crucial role in DataGalaxy’s API, it helps tackle complex problems and brings new customization possibilities to your automation.

This guide will give you a quick feature tour and cover the basics. We will then move on to a few use cases to demonstrate some of the search feature’s applications.

Basic request payload properties​

query​

The query property is a string that will be searched in the Description, Summary, and Name of an object. Use it as your search keyword, if one of the three attributes cited above contains it, it will be returned in the search result.

limit​

The limit property is a number determining the maximum amount of objects returned by the API in the search result.

If you know your search should not return more than n objects, setting "limit" = n is a good practice to limit unnecessary network and server load.

versionId​

Like any DataGalaxy API’s endpoint, the versionId is a string that will ensure your request is executed in the designated version’s perimeter.

This property should always be set if you know in which workspace or workspace version you want your search to be executed.

Advanced request payload properties​

filters​

This property is key when it comes to making advanced search queries. It lets you define a set of filters to make your search query more precise.

filters is a JSON Array, and each entry is a JSON Object made of three properties :

note

If you add multiple filters, the AND operator is applied between each filter, meaning an object has to match every filter for it to be returned in the search result.

POST /search - Request payload
{
  "filters": [
    {
      "attributeKey": "TechnologyCode",
      "operator": "contains",
      "values": ["mysql"]
    },
    {
      "attributeKey": "EntityStatus",
      "operator": "contains",
      "values": ["Proposed", "Obsolete"]
    }
  ]
}

includedAttributes​

The includedAttributes property is a JSON Array and each entry is a string containing an attributeKey. Attributes in the includedAttributes property will be included in each object returned in the search result.

POST /search - Request payload
{
  ...,
  "includedAttributes": [ "DataOwners", "EntityStatus", "Domains" ]
}
Response payload
{
  ...,
  "result": {
    "entities": [
      {
        "name": "Score",
        "type": "UsageField",
        ...,
        "attributes": {
            "owners": [ "john.smith@datagalaxy.com" ],
            "status": "Proposed",
            "tags": ["GDPR"]
        },
        ...
    ],
    ...
  }
}
tip

Use the GET /attributes endpoint to find attributes and their attributeKey.

includeAccessData

When set to true, this boolean property will return the list of access rights the requesting token has on each object.

Check out the search endpoint documentation to see an example.

saveSearchPayload

This boolean property will save your request payload when set to true.

Your saved payload can then be retrieved with the GET /history/search/queries endpoint (see API Reference).

Search Use Cases​

1. Retrieving a list of objects modified in the last seven days​

Time filters are an exception, the values property must stay empty, and the operator property will contain one of the following values:

pastHour, today, yesterday, currentWeek, pastWeek, beforeCurrentWeek, beforePastWeek, currentMonth, pastMonth, beforeCurrentMonth, beforePastMonth, bedoreToday, currentYear, last365days, isEmpty, isNotEmpty.

Request payload
{
  "filters": [
    {
      "attributeKey": "LastModificationTime",
      "operator": "currentWeek",
      "values": []
    }
  ]
}

2. Filtering objects on a set of owners/stewards users​

When filtering on a list of users, we first have to get each user’s id (i.e.: userId) with the GET /users endpoint.

curl 'https://{clientName}.api.datagalaxy.com/v2/users?userId=a862af3a-9a9a-4858-b09e-ee8e68758a62' -H 'Authorization: Bearer {token}'
Response payload
{
  "results": [
    {
      "userId": "a862af3a-9a9a-4858-b09e-ee8e68758a62",
      "licenseLevel": "Steward",
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@datagalaxy.com",
      ...
    },
    ...
  ]
}

Once we fetch the userIds we can start building our search query :

POST /search - Request payload
{
  "filters": [
    {
      "attributeKey": "DataOwners",
      "operator": "contains",
      "values": ["a862af3a-9a9a-4858-b09e-ee8e68758a62"]
    }
  ]
}

Link-based filters have special attributeKeys built with a ObjectLinks_ prefix, like this : ObjectLinks_{linkType}

The values property expects a list of objectId / entityId corresponding to the object

For example, a search filter on objects with a link of type HasForDomain to a specific object will be :

Request payload
{
  "filters": [
    {
      "attributeKey": "ObjectLinks_HasForDomain",
      "operator": "contains",
      "values": ["{objectId}"]
    }
  ]
}