ONE API
ONE API can be queried using GraphQL, a query language for working with APIs and a dedicated runtime system that fulfills the queries based on a type system that you defined specifically for your data.
This guide is intended to give you a brief overview of several key concepts and actions in GraphQL and equip you with a basic understanding of how data can be queried and manipulated through GraphQL in ONE. Before you proceed, take time to get familiar with how GraphQL functions using their official guide: Introduction to GraphQL.
|
Ataccama ONE comes with a preconfigured playground for trying out GraphQL queries against our platform.
The GraphQL Playground is available at the following URL: In addition to a graphical interface, the tool provides context assist when constructing queries and lets you preview queries as well as schema and type details. |
Work with GraphQL
Endpoints
All GraphQL queries are sent to a single endpoint where the GraphQL service is running.
Typically, that is <ataccama_URL>/graphql.
The host corresponds to the location at which the HTTP server of Metadata Management Module (MMM) is available by default.
When working with subscriptions, queries are directed to <ataccama_URL>/subscriptions.
Subscriptions are event-triggered operations that allow you to send updates to users in real time. After the client subscribes to a channel of events, events are pushed by the server without any further action required on the client’s side.
HTTP headers
Request type and Content-Type
GraphQL queries are sent as POST requests with the query itself provided in the request body in JSON format.
The request needs to include Content-Type (application/json) and Authorization (Basic or Bearer) headers.
Authentication
You can use Bascic or Bearer HTTP authentication.
For basic authentication, the token consists of a Base64-encoded username and password combination.
For example, the username-password combination admin:admin is encoded to YWRtaW46YWRtaW4=.
|
To include the |
Request body
GraphQL query example
In GraphQL, the query is specified as follows:
query q {
catalogItems(versionSelector: {draftVersion: true}) {
edges {
node {
gid
draftVersion {
name
}
}
}
}
}-
Root item: Each query begins with a root item starting from which nodes are retrieved. In this case, the root object is
catalogItems. -
Fields: Queries look for information contained in fields. Objects have a number of fields that can be used to filter query results.
-
Arguments: It is possible to narrow down the query results through arguments, which define additional features of the object.
In this case, the argument
draftVersionis supplied for the fieldversionSelector. Since the requested value of the argument istrue, the query is expected to return catalog items that are in draft or published state. -
Edges: A technical wrapper that allows you to fetch more information, such as
totalCount, and customize other fields related to pagination. This way, you can specify how many nodes the query returns. For more information, see [Pagination in GraphQL]. -
Node: Nodes are queried items. In this example, the query searches for two fields on each node,
gid, which is the unique identifier of the catalog item, anddraftVersion, for which thenameshould be retrieved.
The same query is then provided as query property in JSON format in the request body.
Additional fields include operationName and variables, which are optional.
However, operationName should be used when working with multiple operations simultaneously.
{
"operationName": "q",
"variables": {},
"query": "query q {catalogItems(versionSelector: {draftVersion: true}) {edges {node {gid draftVersion { name }}}}}"
}|
Make sure to escape any quotation marks used in the query property, for example: |
The query is expected to return a list of catalog items with their unique identifier and names.
Listing catalog items query response body - example
{
"data": {
"catalogItems": {
"edges": [
{
"node": {
"gid": "0726c74e-fc9e-40ad-a29d-23ec1dac8769",
"draftVersion": {
"name": "addresstype"
}
}
},
{
"node": {
"gid": "07c3923c-b726-4424-8ca4-b6bc7867a842",
"draftVersion": {
"name": "phonenumbertype"
}
}
},
{
"node": {
"gid": "0c93d74b-0aa1-40bf-a022-b6aaeb73b321",
"draftVersion": {
"name": "currencyrate"
}
}
},
{
"node": {
"gid": "11fbfa28-5b37-4e8b-b0f2-c3aa7d85c559",
"draftVersion": {
"name": "businessentityaddress"
}
}
},
{
"node": {
"gid": "15070fa8-08b5-4204-889e-acedf49b7bd1",
"draftVersion": {
"name": "salespersonquotahistory"
}
}
}
...
]
}
}
}Operation name and type
The operation name should be a meaningful name assigned to each request. If you are sending only one query at a time, using an operation name is not necessary. However, when making multiple queries at once, operation names are very helpful for interpreting results and debugging any issues.
A GraphQL operation can be one of the following types:
-
Query: Returns data without making any changes.
-
Mutation: Generally used when modifying data or starting processes.
-
Subscription: Refers to a real-time or continual consumption of events.
The operation type is declared at the beginning of the query.
query operationName {
...
}Variables
If you are using variables, these need to be declared after the operation name while the value is provided in the variables property in the request body.
In the following example, the gid variable is declared as a non-null globally unique identifier type (GID).
Values that cannot be empty are marked by an exclamation mark following the variable type (!).
In the query itself, the variable is passed as an argument using the syntax $<variable_name>.
In variables, you need to reference the variable name without any prefixes and supply its value.
{
"operationName": "q",
"variables": {
"gid": "0726c74e-fc9e-40ad-a29d-23ec1dac8769"
},
"query": "query q($gid: GID!) {catalogItem(gid: $gid) { ... }}"
}If you are using GraphQL Playground, variables are declared in the Query Variables section using the following syntax:
{
"gid": "0726c74e-fc9e-40ad-a29d-23ec1dac8769"
}Error handling
Requests sent to a GraphQL endpoint always return the HTTP 200 OK response.
Any errors are shown in the errors field in the returned JSON.
For example, if you attempt to publish an entity that no longer exists, the following response is returned:
{
"errors": [
{
"message": "The node was not found.",
"locations": [
{
"line": 2,
"column": 1
}
],
"path": [
"catalogItemPublish"
],
"extensions": {
"reason": "NOT_FOUND",
"code": "NOT_FOUND",
"gid": "07c3923c-b726-4424-8ca4-b6bc7867a842",
"time": {
"nano": 220422000,
"epochSecond": 1617648635
},
"type": "catalogItem",
"hash": "dd4a08d8bed5c1f2e16c12205f39efd1",
"classification": "DataFetchingException"
}
}
],
"data": {
"catalogItemPublish": null
}
}When there is an issue with authentication, the following response is expected.
You can find more details in error_description in the message field.
{
"errors": [
{
"message": "{\"error\":\"invalid_grant\",\"error_description\":\"Invalid user credentials\"}",
"locations": [
{
"line": 2,
"column": 1
}
],
"path": [
"catalogItem"
],
"extensions": {
"reason": "INVALID_TOKEN",
"code": "UNAUTHORIZED",
"time": {
"nano": 800461000,
"epochSecond": 1617648843
},
"hash": "76ebda2290ffe334d9e54e98159eedaa",
"classification": "DataFetchingException"
}
}
],
"data": {
"catalogItem": null
}
}GraphQL operations
List entities
You can retrieve an entity, including its content and the embedded attributes, by the entity identifier. The operation also lets you query deep structures such as embedded entities and references.
It is also possible to apply primitive ordering (orderBy: [{ property: "name", direction: ASC }]), pagination (skip, size, cursor), and filtering (filter for AQL, query for AQL that is preprocessed by AI, queryParts` for user-friendly filters which are processed by AI).
For more information about how to use cursor-based pagination, see GraphQL’s guide about Pagination.
To view all catalog items that you can access, use the following query:
query listCatalogItems {
catalogItems(versionSelector: {draftVersion: true}) {
edges {
node {
gid
draftVersion {
name
attributes {
edges {
node {
gid
draftVersion {
name
}
}
}
}
}
}
}
}
}The query is expected to return a response in the following format:
Listing catalog items query response body - example
{
"data": {
"catalogItems": {
"edges": [
{
"node": {
"gid": "1589346f-d5b5-4400-9a13-ad3f733c70ea",
"draftVersion": {
"name": "party_full",
"attributes": {
"edges": [
{
"node": {
"gid": "0fb027e1-e680-496f-91a6-f43fb1b1e4eb",
"draftVersion": {
"name": "src_email"
}
}
},
{
"node": {
"gid": "1594ffae-ac27-447f-9204-4e412d1aecc7",
"draftVersion": {
"name": "src_gender"
}
}
},
{
"node": {
"gid": "202e490b-af4a-411a-903b-e1e75e4e7c85",
"draftVersion": {
"name": "meta_last_update"
}
}
},
{
"node": {
"gid": "2ece8b69-df78-4a95-abf9-cdbea8ebb252",
"draftVersion": {
"name": "src_sin"
}
}
},
{
"node": {
"gid": "6718299d-e931-454a-b9ee-7bbf628c57e8",
"draftVersion": {
"name": "src_card"
}
}
},
{
"node": {
"gid": "6da73afb-8ff3-436c-9e69-e20eaaf527a5",
"draftVersion": {
"name": "src_address"
}
}
},
{
"node": {
"gid": "8b2b919f-8357-4377-943b-99ca6718b4f3",
"draftVersion": {
"name": "src_name"
}
}
},
{
"node": {
"gid": "93b9e3c2-1cfb-47c0-95a3-47e43236f238",
"draftVersion": {
"name": "src_birth_date"
}
}
},
{
"node": {
"gid": "f231b0ad-ccd0-4aa5-b2f0-728c01822367",
"draftVersion": {
"name": "src_primary_key"
}
}
}
]
}
}
}
},
{
...
}
]
}
}
}To retrieve all available glossary terms, run the following query:
query listGlossaryTerms {
terms(versionSelector: {draftVersion: true}) {
edges {
node {
gid
draftVersion {
name
}
}
}
}
}The query returns the identifier and name of each glossary term:
Listing glossary terms query response body
{
"data": {
"terms": {
"edges": [
{
"node": {
"gid": "033df1b9-ef3c-48c7-b40a-a8fc98249221",
"draftVersion": {
"name": "Gender"
}
}
},
{
"node": {
"gid": "08fcb90f-763b-40bf-ae7d-0601e7ec1651",
"draftVersion": {
"name": "Airports"
}
}
},
{
"node": {
"gid": "194e2db8-f939-45ae-8ebd-db7cf8c10bab",
"draftVersion": {
"name": "First name"
}
}
},
{
"node": {
"gid": "8495a8d2-65b7-487d-acad-61b901324b58",
"draftVersion": {
"name": "Country"
}
}
}
...
]
}
}
}To get a list of all attributes of a specific catalog item, use the following query.
The catalog item identifier (gid) is provided as a variable and its value is specified outside of the query (see Variables).
query listAttributes ($gid: GID!) {
catalogItem(gid: $gid) {
publishedVersion {
attributes {
edges {
node {
gid
draftVersion {
name
}
}
}
}
}
}
}The response structure is shown in the following example:
Listing catalog item attributes query response body
{
"data": {
"catalogItem": {
"publishedVersion": {
"attributes": {
"edges": [
{
"node": {
"gid": "75642c37-8e88-4241-9a50-4f801eb47ade",
"draftVersion": {
"name": "name"
}
}
},
{
"node": {
"gid": "77215050-8ce9-4b12-94d9-2bc9265c2c07",
"draftVersion": {
"name": "rowguid"
}
}
},
{
"node": {
"gid": "808fef47-5dc8-4e60-8e91-e914cf18dec7",
"draftVersion": {
"name": "modifieddate"
}
}
},
{
"node": {
"gid": "c271635a-e3b0-499e-9bc3-81b8ae28a480",
"draftVersion": {
"name": "addresstypeid"
}
}
}
]
}
}
}
}
}To list all data sources and their data source connections, run the following query:
query listDataSources {
sources(versionSelector: { draftVersion: true }) {
edges {
node {
gid
draftVersion {
name
connections {
edges {
node {
gid
draftVersion {
name
}
}
}
}
}
}
}
}
}The query returns the following structure:
Listing data sources query response body
{
"data": {
"sources": {
"edges": [
{
"node": {
"gid": "1a6b74ff-726d-472c-85ac-f193c68dcfdd",
"draftVersion": {
"name": "RDM",
"connections": {
"edges": [
{
"node": {
"gid": "c94f2e3f-5a5e-4a7c-af0d-9d1da2020968",
"draftVersion": {
"name": "rdmapp"
}
}
}
]
}
}
}
},
{
"node": {
"gid": "3bc4a6c0-cd9f-4e6f-a1c4-d0d5de161eee",
"draftVersion": {
"name": "AWS MySQL source",
"connections": {
"edges": [
{
"node": {
"gid": "10dca55a-2be8-459b-a4e6-44dd0f018cfb",
"draftVersion": {
"name": "mysql aws"
}
}
}
]
}
}
}
},
{
"node": {
"gid": "8e1ee98b-0ae3-4579-ba3e-ff238cd2f076",
"draftVersion": {
"name": "Local Postgres source",
"connections": {
"edges": [
{
"node": {
"gid": "c7c17fbf-8482-46c0-8177-4040b285eab9",
"draftVersion": {
"name": "postgres local"
}
}
}
]
}
}
}
},
{
"node": {
"gid": "a4baa2d9-a399-4a10-ad93-21d45158d1de",
"draftVersion": {
"name": "AWS S3",
"connections": {
"edges": [
{
"node": {
"gid": "b2325313-30a6-4057-9cdf-bc5aa5845165",
"draftVersion": {
"name": "AWS S3"
}
}
}
]
}
}
}
},
{
"node": {
"gid": "b62a3108-d107-4041-bfe6-d03672a31625",
"draftVersion": {
"name": "Local filesystem",
"connections": {
"edges": [
{
"node": {
"gid": "2ec920b8-35f1-4fcb-9756-e113be0e79a2",
"draftVersion": {
"name": "local filesystem"
}
}
}
]
}
}
}
},
{
"node": {
"gid": "d5c951ee-2080-4460-8eea-e126e239ee3a",
"draftVersion": {
"name": "AWS Postgres source",
"connections": {
"edges": [
{
"node": {
"gid": "ad2553e8-af9e-4271-b354-a993494a2078",
"draftVersion": {
"name": "postgres aws"
}
}
}
]
}
}
}
},
{
"node": {
"gid": "e8357b1c-ef36-4627-97fd-cb69aa2b85e1",
"draftVersion": {
"name": "Compose PostgresTestData",
"connections": {
"edges": [
{
"node": {
"gid": "2e42a730-3a6e-4c50-ace7-f92b633edd65",
"draftVersion": {
"name": "tcd compose"
}
}
}
]
}
}
}
}
]
}
}
}Profile catalog items
To start profiling catalog items, you first need to retrieve information about available profiling configurations. To list all published profiling configurations, use the following query:
query listProfilingConfigurations {
profilingConfigurations(versionSelector: { publishedVersion: true }) {
edges {
node {
gid
publishedVersion {
name
type
description
anomalyDetectionEnabled
samplingLimitCount
samplingLimitPercentage
}
}
}
}
}There are two default profiling configurations: FULL and SAMPLE.
If there are no user-defined profiling configurations, the listProfilingConfigurations query returns only these two options.
If you select the SAMPLE profiling configuration, profiling covers only a subset of records in the catalog item.
A profiling configuration needs to be published before it can applied during profiling.
To specify which profiling configuration you want to use, you need to provide the unique identifier of that configuration (gid).
The listProfilingConfigurations query also returns details about the configuration itself, such as name, type, description, sampling limits, and information about anomaly detection.
Listing profiling configurations query response body
{
"data": {
"profilingConfigurations": {
"edges": [
{
"node": {
"gid": "723fa8c2-9ea9-4119-b0a7-d49f1f6e4c45",
"publishedVersion": {
"name": "Full profiling",
"type": "FULL",
"description": "Full profiling of all the table rows",
"anomalyDetectionEnabled": true,
"samplingLimitCount": null,
"samplingLimitPercentage": null
}
}
},
{
"node": {
"gid": "bb3815bc-6b30-49b0-94c1-d19915750aa4",
"publishedVersion": {
"name": "Sample profiling",
"type": "SAMPLE",
"description": "Sample profiling of table",
"anomalyDetectionEnabled": false,
"samplingLimitCount": 10000,
"samplingLimitPercentage": 20
}
}
}
]
}
}
}The following query triggers profiling on a catalog item.
query profiling {
catalogItem(gid: "0726c74e-fc9e-40ad-a29d-23ec1dac8769") {
gid
profile(defaultCredential: true, configId: "723fa8c2-9ea9-4119-b0a7-d49f1f6e4c45") {
gid
}
}
}These arguments are required:
-
gidon thecatalogItemfield. Refers to the unique identifier of the catalog item that should be profiled. -
configIdon theprofilefield. Points to the identifier (gid) of the selected profiling configuration, which was obtained using thelistProfilingConfigurationsquery.
Profiling catalog items query response body
{
"data": {
"catalogItem": {
"gid": "0726c74e-fc9e-40ad-a29d-23ec1dac8769",
"profile": {
"gid": "1f6fe8e6-5b19-439d-ad2f-99b60beaefda"
}
}
}
}To check the job status after the profiling has started, run the following query:
query getJobStatus {
job(gid: "5b899c99-bee5-4a5f-93e1-85a4d4768f41") {
gid
draftVersion {
status
}
}
}The gid argument on the job field matches the gid field on the profile item that is found in the results returned by the profiling query.
Retrieving job status query response body
{
"data": {
"job": {
"gid": "1f6fe8e6-5b19-439d-ad2f-99b60beaefda",
"draftVersion": {
"status": "FINISHED"
}
}
}
}In case the profiling job has failed, you can view the error by repeating the getJobStatus query with the added error field in the draftVersion field.
Connect to a data source and import metadata
To connect to a data source, you first need to obtain the source connection details. You can get a list of all data sources by running the following query (for more information, refer to List entities):
query listDataSources {
sources(versionSelector: { draftVersion: true }) {
edges {
node {
gid
draftVersion {
name
connections {
edges {
node {
gid
draftVersion {
name
}
}
}
}
}
}
}
}
}In the response, locate the data source and the identifier of the connection with which you want to work (gid).
This identifier is then used in the next query to connect to the source.
Listing data sources query response body
{
"data": {
"sources": {
"edges": [
{
"node": {
"gid": "8e1ee98b-0ae3-4579-ba3e-ff238cd2f076",
"draftVersion": {
"name": "Local Postgres source",
"connections": {
"edges": [
{
"node": {
"gid": "c7c17fbf-8482-46c0-8177-4040b285eab9", # Data source connection identifier
"draftVersion": {
"name": "postgres local"
}
}
}
]
}
}
}
},
...
]
}
}
}The following query establishes a connection with the selected source and imports the metadata for one of the tables.
If path is omitted, the query initiates metadata import for the whole source.
query connectToASource {
connection(gid: "a69e6a13-7863-44c7-9c4e-49aad1d431b3") {
import(defaultCredential: true, path: ["sourceName/schemaName/tableName"]) {
gid
}
}
}The query returns the import job identifier.
Importing metadata query response body
{
"data": {
"connection": {
"import": {
"gid": "5801073d-d8c3-4315-8e06-b82e85fc1ee4"
}
}
}
}You can then profile the imported catalog item. For more information, see Profile catalog items.
Run DQ evaluation
You can run data quality evaluation on a catalog item, a specific column in a catalog item, or a glossary term. Depending on the entity type, you need to provide the corresponding identifier. For more information about how to retrieve the correct identifier for each type of entity, see List entities.
In this case, the operation type is mutation (see Operation name and type).
mutation catalogItemDQ {
catalogItemEvaluateDq(gid: <catalog_item_id>) {
gid
}
}mutation catalogItemAttributeDQ {
attributeEvaluateDq(gid: <catalog_item_attribute_id>) {
gid
}
}mutation glossaryTermDQ {
termEvaluateDq(gid: <glossary_term_identifier>) {
gid
}
}All three operations return the same response format with the identifier of the DQ evaluation job (gid).
The name of the first field under data matches the executed mutation; in the following example, DQ evaluation was performed on a catalog item.
Other values include attributeEvaluateDq for DQ evaluation on catalog item attributes and termEvaluateDq for DQ evaluation on glossary terms.
Running DQ evaluation on a catalog item operation response body
{
"data": {
"catalogItemEvaluateDq": {
"gid": "e80174ca-a512-40e0-8975-b1417a63b4a9"
}
}
}In all three cases, the operation is expected to return the job identifier. You can further customize what the operation returns as needed.
Share entities
Before sharing an entity with another user or a group of users, start by exploring with which users that entity has already been shared (assignedRoles) and with which capabilities an entity can be shared (assignableCapabilities).
query listSharingRolesAndCapabilities {
catalogItem(gid: "0726c74e-fc9e-40ad-a29d-23ec1dac8769") {
assignableCapabilities {
id
displayName
}
assignedRoles {
grantingStrategy
role {
name
}
capability {
id
displayName
}
source {
gid
type
nodePath
}
}
}
}The following example shows the expected result of the query:
Listing sharing capabilities and assigned roles query response body
{
"data": {
"catalogItem": {
"assignableCapabilities": [
{
"id": "editor@/sources/locations/catalogItems",
"displayName": "Editor Everywhere"
},
{
"id": "owner@/sources/locations/catalogItems",
"displayName": "Owner Everywhere"
},
{
"id": "viewer@/sources/locations/catalogItems",
"displayName": "Viewer Everywhere"
}
],
"assignedRoles": [
{
"grantingStrategy": "GRANT",
"role": {
"name": "MMM_read-only"
},
"capability": {
"id": "super-viewer@/",
"displayName": "Super Viewer"
},
"source": {
"gid": "00000000-0000-0000-0000-000000000001",
"type": "metadata",
"nodePath": "/"
}
},
{
"grantingStrategy": "GRANT",
"role": {
"name": "MMM_metadata-manager"
},
"capability": {
"id": "catalog-admin@/",
"displayName": "Catalog Admin"
},
"source": {
"gid": "00000000-0000-0000-0000-000000000001",
"type": "metadata",
"nodePath": "/"
}
},
{
"grantingStrategy": "GRANT",
"role": {
"name": "MMM_data-manager"
},
"capability": {
"id": "catalog-admin@/",
"displayName": "Catalog Admin"
},
"source": {
"gid": "00000000-0000-0000-0000-000000000001",
"type": "metadata",
"nodePath": "/"
}
},
{
"grantingStrategy": "GRANT",
"role": {
"name": "MMM_admin"
},
"capability": {
"id": "importedCatalog@/",
"displayName": "Immutable Catalog"
},
"source": {
"gid": "00000000-0000-0000-0000-000000000001",
"type": "metadata",
"nodePath": "/"
}
},
{
"grantingStrategy": "GRANT",
"role": {
"name": "MMM_admin"
},
"capability": {
"id": "super-admin@/",
"displayName": "Super Admin"
},
"source": {
"gid": "00000000-0000-0000-0000-000000000001",
"type": "metadata",
"nodePath": "/"
}
},
{
"grantingStrategy": "GRANT",
"role": {
"name": "MMM_data-governor"
},
"capability": {
"id": "catalog-viewer@/",
"displayName": "Catalog Viewer"
},
"source": {
"gid": "00000000-0000-0000-0000-000000000001",
"type": "metadata",
"nodePath": "/"
}
},
{
"grantingStrategy": "GRANT",
"role": {
"name": "MMM_dq-specialist"
},
"capability": {
"id": "catalog-viewer@/",
"displayName": "Catalog Viewer"
},
"source": {
"gid": "00000000-0000-0000-0000-000000000001",
"type": "metadata",
"nodePath": "/"
}
},
{
"grantingStrategy": "GRANT",
"role": {
"name": "MMM_data-analyst"
},
"capability": {
"id": "catalog-viewer@/",
"displayName": "Catalog Viewer"
},
"source": {
"gid": "00000000-0000-0000-0000-000000000001",
"type": "metadata",
"nodePath": "/"
}
}
]
}
}
}To assign a sharing role, use the operation shown in the example.
When unassigning a sharing role, use the operation catalogItemUnassignCapabilities; the operation structure remains the same.
The two operations can be applied to every mmd node.
When sharing a business term, the root field is termAssignCapabilities.
The capabilities argument in the following mutation should be set to one of id fields of assignableCapabilities that you obtained through the query listSharingRolesAndCapabilities.
The same query returns the available options for the roles argument, which takes the value of the name field on role in assignedRoles.
With the following mutation, you can assign capabilities on a source or catalog item.
In the following mutation example body we use catalogItemAssignCapabilities to assign capabilities to a person or role on a catalog item.
You can use sourceAssignCapabilities to assign capabilities on a source.
mutation shareEntity {
catalogItemAssignCapabilities( # catalogItemUnassignCapabilities is used when revoking permissions
capabilities: "editor@/sources/locations/catalogItems"
gid: "0726c74e-fc9e-40ad-a29d-23ec1dac8769"
grantingStrategy: GRANT
roles: "default"
) {
result {
gid
}
}
}The response contains the identifier of the shared entity:
Sharing assets operation response body
{
"data": {
"catalogItemAssignCapabilities": {
"result": {
"gid": "0726c74e-fc9e-40ad-a29d-23ec1dac8769"
}
}
}
}Delete entities
When deleting an entity, similarly to other edit operations such as creating or updating an entity, you first need to create a delete draft and then publish the draft. The operation requires the identifier of the entity.
To delete a catalog item attribute, replace the root item catalogItemDelete with attributeDelete.
When deleting a glossary term, use termDelete instead.
mutation deleteEntity {
catalogItemDelete(gid: "0726c74e-fc9e-40ad-a29d-23ec1dac8769") {
success
}
}The query returns the following structure:
Deleting catalog items operation response body
{
"data": {
"catalogItemDelete": {
"success": true
}
}
}For more information about how to publish the delete draft, see Publish entities.
Publish entities
Any mmd node can be published using the mutation publishEntity.
Currently, this operation bypasses the publishing workflow, which means that the approval request is automatically resolved (this behavior is expected to change later).
When publishing attributes, the root item should be attributePublish.
For glossary terms, use termPublish.
If the field result is added as shown in the example, the operation returns the name of the published node.
|
Depending on the type of entity, the
The content assist feature of GraphQL Playground can help you customize what the |
mutation publishEntity {
catalogItemPublish(gid: "0726c74e-fc9e-40ad-a29d-23ec1dac8769") {
success
result {
publishedVersion {
name
}
}
}
}The response is structured as follows:
Publishing entities operation response body
{
"data": {
"catalogItemPublish": {
"success": true,
"result": {
"publishedVersion": {
"name": "customers.csv"
}
}
}
}
}When publishing a delete draft, the operation returns a response in the following format:
Publishing a delete draft operation response body
{
"data": {
"catalogItemDelete": {
"success": true,
"result": {
"publishedVersion": null
}
}
}
}Duplicate rules and terms
It is possible to duplicate the configuration of rules and terms. This is useful when, for example, similar rules need to be assigned to multiple lookup files. This operation only copies the configuration and none of the entity relationships, which means that the duplicated rule or term is not assigned anywhere.
In both cases, you need to specify the identifier (gid) of the term or rule which you would like to duplicate.
mutation copyTerm {
termCopy(gid: "<term_ID>") {
result {
gid
}
}
}mutation copyRule {
ruleCopy(gid: "<rule_ID>") {
result {
gid
}
}
}In these examples, both operations return the identifier of the copied entity, for example:
Duplicating a rule operation response body
{
"data": {
"ruleCopy": {
"result": {
"gid": "a0ceca7a-1653-4338-9054-8da4e45dcd7e"
}
}
}
}Glossary terms
The following examples cover use cases specific for glossary terms, such as exporting term types and obtaining term statistics.
List term types
To retrieve a list of all terms types, along with term identifiers, use the following query. As needed, the query can be expanded to include additional information about terms (see List entities).
query getTermTypes {
terms(versionSelector: { draftVersion: true }) {
edges {
node {
gid
type
}
}
}
}Listing term types query response body
{
"data": {
"terms": {
"edges": [
{
"node": {
"gid": "01503672-d0a0-492f-9ac6-b318fb9ee7d2",
"type": "keyPerformanceIndicator"
}
},
{
"node": {
"gid": "029d5ece-d9ef-4dd9-a1c2-8e74289874d2",
"type": "keyPerformanceIndicator"
}
},
{
"node": {
"gid": "03b3e732-cded-40fd-9b52-134c2cfbefe3",
"type": "businessTerm"
}
},
...
]
}
}
}Retrieve term occurrences
To get an overview of the entities to which a specific glossary term has been assigned, run the following query.
The term identifier (gid) can be obtained using the previous query for listing term types.
When the withCount argument is set to true, the total count also includes the occurrences on child entities.
For example, this means that terms assigned to attributes are also counted for the catalog items containing those attributes.
To calculate occurrences of only directly assigned terms (that is, to exclude catalog item counts), set the value to false.
query getTermOccurrences {
term(gid: "033df1b9-ef3c-48c7-b40a-a8fc98249221") {
statistics(withCount: true, relationships: []) {
usageStatistics {
nodePath
totalCount
}
}
}
}The query returns a list of available entities and the number of times the term has been assigned to each entity type.
Retrieving term occurrences query response body
{
"data": {
"term": {
"statistics": {
"usageStatistics": [
{
"nodePath": "/sources/workspace/catalogItems/attributes",
"totalCount": 0
},
{
"nodePath": "/sources/locations/catalogItems",
"totalCount": 5
},
{
"nodePath": "/sources/locations",
"totalCount": 4
},
{
"nodePath": "/monitoringProjects",
"totalCount": 1
},
{
"nodePath": "/sources/workspace/catalogItems",
"totalCount": 0
},
{
"nodePath": "/sources/locations/catalogItems/attributes",
"totalCount": 0
},
{
"nodePath": "/components",
"totalCount": 0
},
{
"nodePath": "/rules",
"totalCount": 0
},
{
"nodePath": "/sources",
"totalCount": 3
},
{
"nodePath": "/sources/workspace",
"totalCount": 0
}
]
}
}
}
}Work with monitoring projects
Monitoring project queries live under the monitoringProject entity.
This section provides examples illustrating some common use cases for monitoring projects that should help you when constructing your own queries. These include running a monitoring project and retrieving monitoring results with different levels of detail.
Running a monitoring project
To run a monitoring project, you need the monitoring project identifier (projectId).
All project identifiers can be retrieved through the following query:
query getProjects {
monitoringProjects(versionSelector: { draftVersion: true }) {
edges {
node {
gid
}
}
}
}Listing monitoring projects query response body
{
"data": {
"monitoringProjects": {
"edges": [
{
"node": {
"gid": "0f8f3b16-a9a4-491e-9384-eb302dda1fba"
}
},
{
"node": {
"gid": "19fce03c-e238-49c9-ab26-ddddc48c95e0"
}
},
{
"node": {
"gid": "22f888c1-2dcc-466e-9b0f-95e19470ae27"
}
},
...
]
}
}
}Using the following query, DQ is monitored only on the most recent partition of the catalog item.
If partition options are not provided, monitoring uses the default catalog item settings defined in the project, which means that it runs either on the whole catalog item (FULL) or its latest partition (LATEST).
mutation startMonitoring {
runMonitoringProject(projectId: "89b662a3-8ece-409f-b523-01aeba8240a2",
partitionSettings: [
{
catalogItemId: "7c4993f7-bb8c-4885-a4e5-d3930d043f8e",
partitionType: LATEST
}
]
) {
loadMonitoringProjectId
}
}The query returns the following:
Running a monitoring project operation response body
{
"data": {
"runMonitoringProject": {
"loadMonitoringProjectId": "89b662a3-8ece-409f-b523-01aeba8240a2"
}
}
}Monitoring projects results global retention
To define a global retention policy on monitoring project results:
-
First create a configuration draft, with the retention value and unit defined as required. The mutation should be as follows:
GrapghQL mutation for setting global results retentionmutation createGlobalConfiguration{ projectResultsRetentionConfigurationCreate( parentNode: "metadata", parentProperty: "projectResultsRetentionConfiguration", parentGid:"00000000-0000-0000-0000-000000000001", new: { enabled: true, value:10, unit: "RUNS", # RUNS or DAYS _type: "projectResultsRetentionConfiguration"} ){ success aliasMapping { gid alias } result { gid } } } -
The response will contain the GID of the newly created configuration:
Expand source.
{ "data": { "projectResultsRetentionConfigurationCreate": { "success": true, "aliasMapping": [], "result": { "gid": "b8a87c0e-827d-46c0-9fa6-765ab5b39950" # <- id of new configuration } } } } -
Use the GID from the response and publish the draft:
mutation publishConfig { projectResultsRetentionConfigurationPublish(gid: "b8a87c0e-827d-46c0-9fa6-765ab5b39950"){ success } }
To remove the configuration:
-
Send delete mutation using the GID of the configuration.
mutation delete { projectResultsRetentionConfigurationDelete(gid: "b8a87c0e-827d-46c0-9fa6-765ab5b39950"){ success result { gid } } } -
Response will contain a GID for the delete configuration.
-
Publish the delete config using the GID from previous response.
mutation publishConfig { projectResultsRetentionConfigurationPublish(gid: "b8a87c0e-827d-46c0-9fa6-765ab5b39950"){ success } }
DQ results dqCheckResultOverTime
This query returns results of selected DQ checks. DQ checks of the type validity also include the explanation for invalid results.
There are a number of parameters that can be defined:
-
Selector. Processing selector specifies which runs should be included in the results. You can use these 3 approaches:-
Limit: returns last n runs. Use the format
{limit: X}. -
Time range: returns runs in specified time range. Unspecified
toparameter means until present time. Use the format seen below.timeRange: { from: "2021-01-16T00:00:00.000000Z", to: "2021-01-17T00:00:00.000000Z" # `to` parameter is optional } -
Processing ids: list of specific processing ids. Use the format seen below.
selector: { processingIds: [ "34174311-f4b0-4efe-9462-272a066e6117", "00e71092-a53b-47f4-ae50-792b777609e7" ] }
-
-
Filter. Filter parameter specifies which rows should be included in results. Filter attributes must match filter configuration of run. I.e. If run was started with filters enabled on attributes A and B. Filter should also include these attributes. If the attributes do not match any run, the run will be missing from results.Expand source.
filter: [ { attributeId: "d3c8da98-0dea-4523-903c-cbc4a3f28e8b" values: ["Fire", "Water", "Grass"] } { attributeId: "00e71092-a53b-47f4-ae50-792b777609e7" values: ["Blastoise", "Bulbasaur","Charizard"]} ]Values field can be empty. That has same meaning as listing all possible values. Never use value ALLwith other values. It will give you incorrect results. You can use it alone but preferred way is to use empty list instead. -
catalogItemId: Id of the catalog item. -
checkIds: List of DQ check ids (gid attribute of dqCheck entity).
Example query:
query CheckResults {
monitoringProject(gid: "957a400f-cfb7-4c0b-91f1-2f4ec441d734"){
publishedVersion {
dqCheckResultOverTime(
selector: {
limit: 2
},
catalogItemId: "6b03e87f-ae53-4c41-a16e-3c4b7234063b",
checkIds: [
"7b24c572-93be-462e-8b54-e76772b00f6d"
],
filter: [
{
attributeId: "d3c8da98-0dea-4523-903c-cbc4a3f28e8b"
values: ["Fire", "Water", "Grass"]
}
{
attributeId: "00e71092-a53b-47f4-ae50-792b777609e7"
values: ["Blastoise", "Bulbasaur","Charizard"]}
]
)
{
processingId
startedAt
results {
dqCheckId
results {
id
count
name
}
explanations {
id
count
name
}
alerts {
id
name
}
}
}
}
}
}The following response structure is returned.
Listing basic monitoring results query response body
{
"data": {
"monitoringProject": {
"publishedVersion": {
"dqCheckResultOverTime": [
{
"processingId": "c770437f-e59c-4203-aa37-8093b475a59e",
"startedAt": "2021-10-25T09:54:30.871811Z",
"results": [
{
"dqCheckId": "7b24c572-93be-462e-8b54-e76772b00f6d",
"results": [
{
"id": "67b7aed6-b54f-4be3-a987-95899f605029",
"count": 3,
"name": "Valid"
},
{
"id": "ec49b8ed-52b2-469c-8424-4866249755cb",
"count": 3,
"name": "Invalid"
}
],
"explanations": [
{
"id": "5a69e2d1-c74c-43a2-a5a2-2705cc2a760d",
"count": 3,
"name": "IS_EMPTY"
}
],
"alerts": [
{
"id": "5a69e2d1-c74c-43a2-a5a2-2705cc2aabcd",
"name": "WARNING"
}
]
}
]
},
{
"processingId": "9ba1d3c4-9e01-4960-8344-4948a1373bb8",
"startedAt": "2021-10-27T09:22:59.491476Z",
"results": [
{
"dqCheckId": "7b24c572-93be-462e-8b54-e76772b00f6d",
"results": [
{
"id": "67b7aed6-b54f-4be3-a987-95899f605029",
"count": 3,
"name": "Valid"
},
{
"id": "ec49b8ed-52b2-469c-8424-4866249755cb",
"count": 3,
"name": "Invalid"
}
],
"explanations": [
{
"id": "5a69e2d1-c74c-43a2-a5a2-2705cc2a760d",
"count": 3,
"name": "IS_EMPTY"
}
],
"alerts": []
}
]
}
]
}
}
}
}Aggregation results dqAggregationResultOverTime
This query provides results of selected aggregations. There are a number of parameters that can be defined:
-
Selector. Processing selector specifies which runs should be included in the results. You can use these 3 approaches:-
Limit: returns last n runs. Use the format
{limit: X}. -
Time range: returns runs in specified time range. Unspecified
toparameter means until present time. Use the format seen below.timeRange: { from: "2021-01-16T00:00:00.000000Z", to: "2021-01-17T00:00:00.000000Z" # `to` parameter is optional } -
Processing ids: list of specific processing ids. Use the format seen below.
selector: { processingIds: [ "34174311-f4b0-4efe-9462-272a066e6117", "00e71092-a53b-47f4-ae50-792b777609e7" ] }
-
-
Filter. Filter parameter specifies which rows should be included in results. Filter attributes must match filter configuration of run. I.e. If run was started with filters enabled on attributes A and B. Filter should also include these attributes. If the attributes do not match any run, the run will be missing from results.filter: [ { attributeId: "d3c8da98-0dea-4523-903c-cbc4a3f28e8b" values: ["Fire", "Water", "Grass"] } { attributeId: "00e71092-a53b-47f4-ae50-792b777609e7" values: ["Blastoise", "Bulbasaur","Charizard"]} ]Values field can be empty. That has same meaning as listing all possible values. Never use value ALLwith other values. It will give you incorrect results. You can use it alone but preferred way is to use empty list instead. -
catalogItemId: ID of the catalog item. -
aggregationIds: Id of aggregation. There are three possible values that can be used:-
Custom aggregation ID.
-
Catalog item id (aggregated results of all existing checks on the catalog item).
-
Attribute ID (aggregated results of all existing checks on the attribute).
-
Example query:
Expand source.
query FetchProjectAggregationResults {
monitoringProject(gid: "957a400f-cfb7-4c0b-91f1-2f4ec441d734"){
publishedVersion {
dqAggregationResultOverTime(
selector: {
limit: 1,
},
catalogItemId: "6b03e87f-ae53-4c41-a16e-3c4b7234063b",
aggregationIds: [
"d046700c-f668-4d11-86bb-8af529deecf5"
"6b03e87f-ae53-4c41-a16e-3c4b7234063b"
],
filter: [
{
attributeId: "d3c8da98-0dea-4523-903c-cbc4a3f28e8b"
values: ["Fire", "Water", "Grass"]
}
{
attributeId: "00e71092-a53b-47f4-ae50-792b777609e7"
values: ["Blastoise", "Bulbasaur","Charizard"]}
]
){
processingId
startedAt
results {
aggregationId
results {
id
count
name
}
}
}
}
}
}The following response structure is returned.
Expand source.
{
"data": {
"monitoringProject": {
"publishedVersion": {
"dqAggregationResultOverTime": [
{
"processingId": "9ba1d3c4-9e01-4960-8344-4948a1373bb8",
"startedAt": "2021-10-27T09:22:59.491476Z",
"results": [
{
"aggregationId": "6b03e87f-ae53-4c41-a16e-3c4b7234063b",
"results": [
{
"id": "67b7aed6-b54f-4be3-a987-95899f605029",
"count": 4,
"name": "Valid"
},
{
"id": "ec49b8ed-52b2-469c-8424-4866249755cb",
"count": 5,
"name": "Invalid"
}
]
},
{
"aggregationId": "d046700c-f668-4d11-86bb-8af529deecf5",
"results": [
{
"id": "67b7aed6-b54f-4be3-a987-95899f605029",
"count": 4,
"name": "Valid"
},
{
"id": "ec49b8ed-52b2-469c-8424-4866249755cb",
"count": 5,
"name": "Invalid"
}
]
}
]
}
]
}
}
}
}Monitoring project results dqProjectResultsOverTime
This query gives you project validity results over time. The results are aggregated over all catalog items in a monitoring project. The following parameter needs defining:
-
Selector. Processing selector specifies which runs should be included in the results. You can use these 3 approaches:-
Limit: returns last n runs. Use the format
{limit: X}. -
Time range: returns runs in specified time range. Unspecified
toparameter means until present time. Use the format seen below.timeRange: { from: "2021-01-16T00:00:00.000000Z", to: "2021-01-17T00:00:00.000000Z" # `to` parameter is optional } -
Processing ids: list of specific processing ids. Use the format seen below.
selector: { processingIds: [ "34174311-f4b0-4efe-9462-272a066e6117", "00e71092-a53b-47f4-ae50-792b777609e7" ] }
-
Example query:
query {
monitoringProject(gid: "957a400f-cfb7-4c0b-91f1-2f4ec441d734"){
publishedVersion {
dqProjectResultOverTime(
selector: {
limit: 10
}
)
{
processingId
startedAt
results {
aggregationId
results {
id
count
name
}
}
}
}
}
}The following response structure is returned.
Expand source.
{
"data": {
"monitoringProject": {
"publishedVersion": {
"dqProjectResultOverTime": [
{
"processingId": "c770437f-e59c-4203-aa37-8093b475a59e",
"startedAt": "2021-10-25T09:54:30.871811Z",
"results": [
{
"aggregationId": "957a400f-cfb7-4c0b-91f1-2f4ec441d734",
"results": [
{
"id": "67b7aed6-b54f-4be3-a987-95899f605029",
"count": 7,
"name": "Valid"
},
{
"id": "ec49b8ed-52b2-469c-8424-4866249755cb",
"count": 3,
"name": "Invalid"
}
]
}
]
},
{
"processingId": "9ba1d3c4-9e01-4960-8344-4948a1373bb8",
"startedAt": "2021-10-27T09:22:59.491476Z",
"results": [
{
"aggregationId": "957a400f-cfb7-4c0b-91f1-2f4ec441d734",
"results": [
{
"id": "67b7aed6-b54f-4be3-a987-95899f605029",
"count": 4,
"name": "Valid"
},
{
"id": "ec49b8ed-52b2-469c-8424-4866249755cb",
"count": 6,
"name": "Invalid"
}
]
}
]
}
]
}
}
}
}Was this page useful?