Using Metadata Interface

Guide objective

This guide explains how to use the Metadata Interface.

The Metadata Interface is used to query metadata of your project. It includes metadata about packages, entities, loads, schedules, workflows and so on. Use External API to connect the Metadata Interface. For test and development purposes, you can use a Swagger UI or a GraphQL client such as GraphQL Playground.

Metadata Interface Data Model

An “indicative“ ER model of the Metadata Interface can be found below. Remember to check the model in the Metadata Interface itself, because the model may vary slightly between different versions.

Connect Metadata Interface using External API

Go to Swagger UI's Metadata related API.

Enter the tenant, installation, environment, and then press Authorize.

Enter the API keys and press Authorize after the id and the secret.

Connect Metadata Interface using GraphQL Playground

To connect the Metadata Interface using GraphQL Playground, you need to first install the tool and then connect to Metadata Interface:

CODE

# Endpoint URL
https://external.services.saas.agiledataengine.com/external-api/api/<tenant>/<installation>/<environment>/metadata/v1/graphql

# HTTP HEADERS
{
  "X-API-KEY-ID": "<X-API-KEY-ID>" , 
  "X-API-KEY-SECRET": "<X-API-KEY-SECRET>"
}

Schema and Docs Tabs

GraphQL Playground has schema and docs tabs. The schema tab has a list of types and their fields and the docs tab has a list of queries and types related to the selected query.

Docs view with entity_list query selected

Example Queries

Query schema

Use the following query to get the available types and their fields.

CODE

{__schema {types
 {name
  kind
  fields {name
  description}
  }}}

Schema content query and result in GraphQL Playground

Query Entities

Query without variables

Use the following query to list 100 entities with selected fields.

CODE

# query
query{entity_list(size: 100, page: 0) 
  { page
    hasNextPage
    pageSize
    content {
      ... on ENTITY {
        id
        package_id
        schema
        name
        type
        physical_type
        source_id
      }
    }
  } 
}

Entity list query and result in GraphQL Playground

Query with variables

Use the following query to list entities with selected fields using variables.

CODE

# query
query($size: Int! $page: Int!){entity_list(size: $size, page: $page) 
  { page
    hasNextPage
    pageSize
    content {
      ... on ENTITY {
        id
        package_id
        schema
        name
        type
        physical_type
        source_id
      }
    }
  } 
}


# query variables
{
 "size": 100, 
 "page": 0
 }

Entity list query with variables and result in GraphQL Playground

Query Packages

Use the following query to list 100 packages with selected fields.

CODE

# query
query($size: Int! $page: Int!){package_list(size: $size, page: $page) 
  { page
    hasNextPage
    pageSize
    content {
      ... on PACKAGE {
        id
        type
        is_deleted
        version
        name
        status
      }
    }
  } 
}

# query variables
{
 "size": 100, 
 "page": 0
}

Package list query and result in GraphQL Playground

Query Fields of Specific Entity

Query the fields of the specific entity using entity id.

CODE

# query
query($entity_id: String!){entity(id: $entity_id)
  { id
    package_id
    schema
    name
    type
    physical_type
  }
}

# query variables
{"entity_id": "986ff984-1354-4e9d-889c-34ccc1a170e9"}

Entity specific query and result in GraphQL Playground

Query Workflow Statuses

Use the following query to list the workflow statuses.

CODE

# query
query ($startTimeFrom: IsoDateTimeAtUtcScalar!, 
  $startTimeTo: IsoDateTimeAtUtcScalar!, $size: Int! $page: Int!) {
  workflow_stats_list(startTimeFrom: $startTimeFrom, startTimeTo: $startTimeTo, 
    size: $size, page: $page) {
    page
    pageSize
    hasNextPage
    content {
      ... on WORKFLOW_STATS {
        id
        workflow_execution_id
        name
        start_time
        end_time
        exec_time_ms
        is_successful
      }
    }
  }
}

# query variables
{
  "startTimeFrom": "2023-09-13T00:00:00.000000",
  "startTimeTo": "2023-09-13T23:59:59.999999",
  "size": 20, 
  "page": 0
}

Workflow stats list query and result in GraphQL Playground