Lead your team forward
OCT 24 / 9AM ET Register nowONE 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
For testing purposes, you can use the Basic HTTP Authentication Scheme.
The authentication token for the Basic HTTP Authentication consists of a base64-encoded username and password combination.
For example, the username-password combination admin:admin
is encoded to YWRtaW46YWRtaW4=
.
For real-life applications, we recommend using more secure forms of authentication. For more information, see API Requests Authentication.
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
draftVersion
is 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. -
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 thename
should 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:
-
gid
on thecatalogItem
field. Refers to the unique identifier of the catalog item that should be profiled. -
configId
on theprofile
field. Points to the identifier (gid
) of the selected profiling configuration, which was obtained using thelistProfilingConfigurations
query.
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 and with which access levels an entity can be shared (assignableAccessLevels). To assign an access level, use the operation shown in the example. When sharing, use the operation <entityName>ShareAccessLevel. The list of sharingRequests has either "action": "ADD" or "action": "REMOVE". The two operations can be applied to every mmd node.
To assign an access level, use the operation shown in the example.
When sharing, use the operation <entityName>ShareAccessLevel
.
The list of sharingRequests
has either "action": "ADD"`
or "action": "REMOVE"
.
The two operations can be applied to every mmd
node.
query GetAccessLeveles_catalogItem($gid: GID!) {
catalogItem(gid: $gid) {
gid
assignableAccessLevels {
accessLevel {
name
displayName
description
order
}
allowed
assignedDuringCreation
preselectedDuringSharing
}
assignedAccessLevels {
accessLevel {
name
displayName
description
order
}
assignedToIdentity {
... on Group {
gid
name
description
numericalIdentifier
}
... on Person {
gid
firstName
lastName
username
email
numericalIdentifier
}
__typename
}
assignedToNode {
gid
nodePath
type
}
assignedToSteward
}
}
}
The following example shows the expected result of the query:
Listing sharing access levels and assigned groups or users query response body
{
"extensions": {
"__$r": "U[ftT#rOG1DeDiVFYlfV?ZF:&g.z)IA+gT]=V/lPF%K0xM_]I//lkn~gnA&8MY&\\Q0%!p(~<Go(KBCsXZ[Wp';e-++Ymdk#8Yd}WQE wKz8HhF}o&ZJ># D!hp1T5]7SYi&6(gZ}!WFj(bHpSqIITr`1[JVXJ{K6SMsBBc!AF`T^^\\^|7zbBVi"
},
"data": {
"catalogItem": {
"gid": "08664d56-0000-7000-0000-00000008d94a",
"assignableAccessLevels": [
{
"accessLevel": {
"name": "full",
"displayName": "Full access",
"description": "Full access is a complete set of permissions to an asset, including the permissions to delete, create, publish, and share. Default roles data owner and data steward have full access to some assets.",
"order": -1000
},
"allowed": true,
"assignedDuringCreation": true,
"preselectedDuringSharing": false
},
{
"accessLevel": {
"name": "edit",
"displayName": "Editing access",
"description": "Share edit access to collaborate with other users and groups. Editors can't create, delete, and publish assets. They can't manage access to assets either.",
"order": 0
},
"allowed": true,
"assignedDuringCreation": false,
"preselectedDuringSharing": false
},
{
"accessLevel": {
"name": "viewData",
"displayName": "View data access",
"description": "Viewers can view all data and metadata but can't edit anything. Share view access to allow other users and groups to view real data, to review assets, and add comments.",
"order": 500
},
"allowed": true,
"assignedDuringCreation": false,
"preselectedDuringSharing": false
},
{
"accessLevel": {
"name": "viewMetadata",
"displayName": "View metadata access",
"description": "Viewers can view metadata and can't edit anything. Share view metadata access to allow other users and groups to access only metadata.",
"order": 1000
},
"allowed": true,
"assignedDuringCreation": false,
"preselectedDuringSharing": true
}
],
"assignedAccessLevels": [
{
"accessLevel": {
"name": "full",
"displayName": "Full access",
"description": "Full access is a complete set of permissions to an asset, including the permissions to delete, create, publish, and share. Default roles data owner and data steward have full access to some assets.",
"order": -1000
},
"assignedToIdentity": {
"gid": "15bbce34-0000-7000-0000-00000047025b",
"name": "Data Office",
"description": "This group include users with Data Owner and Data Steward roles that watch quality of the company data. They own data governance rules and strategies, define how the product is used, help other teams with onboarding and so on.",
"numericalIdentifier": 23,
"__typename": "Group"
},
"assignedToNode": {
"gid": "15bbce34-0000-7000-0000-0000001612c9",
"nodePath": "/sources",
"type": "source"
},
"assignedToSteward": false
}
]
}
}
}
You can find out with whom you can share an entity, by using the following query:
query {
_listOfIdentities (identityTypes: [USER, GROUP]) {
edges {
node {
__typename
... on Person {
gid
firstName
lastName
username
email
numericalIdentifier
}
... on Group {
gid
name
description
numericalIdentifier
}
}
}
}
}
The following example shows the expected result of the query:
Listing sharing capabilities and assigned roles query response body
{
"extensions": {
"__$r": "kKK=od!<8m/63]`1Id)@;4bB$u&tA1z52V[X]'p40TL|x=7;'PNr{w??\\>o%n5(PaD: {AGF,*=Dh#r#~<O69Q+eax0XC:~'r>+&!bOmqoF?u6Z1@Z_q9_l![/mzv4&C#&gNE/I:M4_2t1~rDP3\"UI6gH&h~rXaf%z~'e>#GFgsu>tQcm!u\"}eUb$!_.2|~GGx6)+|`t);,!:UsK(`Z*Zo7[9$8Q~lp:1d#ZajAqZYN"
},
"data": {
"_listOfIdentities": {
"edges": [
{
"node": {
"__typename": "Group",
"gid": "15bbce34-0000-7000-0000-00000047025a",
"name": "Administrators",
"description": "Group of users with the highest permissions that make sure the platform and the system works well. They perform configuration and administration changes to the platform. Users with ONE SuperAdmin, ONE Administrator, and ONE Operator level permissions will typically belong here.",
"numericalIdentifier": 13
}
},
{
"node": {
"__typename": "Group",
"gid": "15bbce34-0000-7000-0000-00000047025b",
"name": "Data Office",
"description": "This group include users with Data Owner and Data Steward roles that watch quality of the company data. They own data governance rules and strategies, define how the product is used, help other teams with onboarding and so on.",
"numericalIdentifier": 23
}
},
{
"node": {
"__typename": "Group",
"gid": "16d3a735-0000-7000-0000-000000088d0b",
"name": "Default",
"description": null,
"numericalIdentifier": 73
}
},
{
"node": {
"__typename": "Group",
"gid": "16d3a735-0000-7000-0000-0000000e0054",
"name": "Finance",
"description": null,
"numericalIdentifier": 103
}
},
{
"node": {
"__typename": "Group",
"gid": "15bbce34-0000-7000-0000-000000470266",
"name": "HR",
"description": null,
"numericalIdentifier": 63
}
},
{
"node": {
"__typename": "Group",
"gid": "15bbce34-0000-7000-0000-000000470262",
"name": "IT",
"description": null,
"numericalIdentifier": 53
}
},
{
"node": {
"__typename": "Group",
"gid": "16d3a735-0000-7000-0000-0000000e0048",
"name": "Manufacturing",
"description": null,
"numericalIdentifier": 93
}
},
{
"node": {
"__typename": "Group",
"gid": "15bbce34-0000-7000-0000-00000047025d",
"name": "Marketing",
"description": null,
"numericalIdentifier": 43
}
},
{
"node": {
"__typename": "Group",
"gid": "00000000-8dbd-4f77-a9a1-b05d109ef274",
"name": "Organization",
"description": null,
"numericalIdentifier": 3
}
},
{
"node": {
"__typename": "Group",
"gid": "16d3a735-0000-7000-0000-0000000e0060",
"name": "Procurement",
"description": null,
"numericalIdentifier": 113
}
},
{
"node": {
"__typename": "Group",
"gid": "16d3a735-0000-7000-0000-0000000e006c",
"name": "R&D",
"description": null,
"numericalIdentifier": 123
}
},
{
"node": {
"__typename": "Group",
"gid": "15bbce34-0000-7000-0000-00000047025c",
"name": "Sales",
"description": null,
"numericalIdentifier": 33
}
},
{
"node": {
"__typename": "Group",
"gid": "16d3a735-0000-7000-0000-0000000e003c",
"name": "Supply Chain",
"description": null,
"numericalIdentifier": 83
}
},
{
"node": {
"__typename": "Person",
"gid": "5e6ad3f9-0000-7000-0000-000000099d7f",
"firstName": "Admin",
"lastName": null,
"username": "admin",
"email": "admin@admin.com",
"numericalIdentifier": 1
}
},
{
"node": {
"__typename": "Person",
"gid": "5e6ad3f9-0000-7000-0000-000000099d9c",
"firstName": "",
"lastName": "",
"username": "emma.anderson@ataccama.com",
"email": "emma.anderson@ataccama.com",
"numericalIdentifier": 31
}
},
{
"node": {
"__typename": "Person",
"gid": "5e6ad3f9-0000-7000-0000-000000099d95",
"firstName": "first-name",
"lastName": "last-name",
"username": "access-request-user",
"email": "access-request-user@ataccama.com",
"numericalIdentifier": 11
}
},
{
"node": {
"__typename": "Person",
"gid": "5e6ad3f9-0000-7000-0000-000000099da5",
"firstName": "first-name",
"lastName": "last-name",
"username": "full-access-user",
"email": "full-access-user@ataccama.com",
"numericalIdentifier": 71
}
},
{
"node": {
"__typename": "Person",
"gid": "5e6ad3f9-0000-7000-0000-000000099d9d",
"firstName": "",
"lastName": "",
"username": "it@ataccama.com",
"email": "it@ataccama.com",
"numericalIdentifier": 41
}
},
{
"node": {
"__typename": "Person",
"gid": "5e6ad3f9-0000-7000-0000-000000099dbb",
"firstName": "James",
"lastName": "Jones",
"username": "james.jones",
"email": "james.jones@ataccama.com",
"numericalIdentifier": 81
}
},
{
"node": {
"__typename": "Person",
"gid": "5e6ad3f9-0000-7000-0000-000000099dc6",
"firstName": "Jane",
"lastName": "Smith",
"username": "jane.smith",
"email": "jane.smith@ataccama.com",
"numericalIdentifier": 91
}
},
{
"node": {
"__typename": "Person",
"gid": "5e6ad3f9-0000-7000-0000-000000099ddb",
"firstName": "John",
"lastName": "Taylor",
"username": "john.taylor",
"email": "john.taylor@ataccama.com",
"numericalIdentifier": 101
}
},
{
"node": {
"__typename": "Person",
"gid": "5e6ad3f9-0000-7000-0000-000000099de7",
"firstName": "Mark",
"lastName": "Goodwill",
"username": "mark.goodwill",
"email": "mark.goodwill@ataccama.com",
"numericalIdentifier": 111
}
},
{
"node": {
"__typename": "Person",
"gid": "5e6ad3f9-0000-7000-0000-000000099da0",
"firstName": null,
"lastName": null,
"username": "monitoring_user",
"email": null,
"numericalIdentifier": 61
}
},
{
"node": {
"__typename": "Person",
"gid": "5e6ad3f9-0000-7000-0000-000000099df2",
"firstName": "Olivia",
"lastName": "Miller",
"username": "olivia.miller",
"email": "olivia.miller@ataccama.com",
"numericalIdentifier": 121
}
},
{
"node": {
"__typename": "Person",
"gid": "5e6ad3f9-0000-7000-0000-000000099dfe",
"firstName": "Paul",
"lastName": "James",
"username": "paul.james",
"email": "paul.james@ataccama.com",
"numericalIdentifier": 131
}
},
{
"node": {
"__typename": "Person",
"gid": "5e6ad3f9-0000-7000-0000-000000099e0a",
"firstName": "Rachel",
"lastName": "Adams",
"username": "rachel.adams",
"email": "rachel.adams@ataccama.com",
"numericalIdentifier": 141
}
},
{
"node": {
"__typename": "Person",
"gid": "5e6ad3f9-0000-7000-0000-000000099d9b",
"firstName": "",
"lastName": "",
"username": "tom.peters@ataccama.com",
"email": "tom.peters@ataccama.com",
"numericalIdentifier": 21
}
},
{
"node": {
"__typename": "Person",
"gid": "5e6ad3f9-0000-7000-0000-000000099d9e",
"firstName": "",
"lastName": "",
"username": "vincent.parker@ataccama.com",
"email": "vincent.parker@ataccama.com",
"numericalIdentifier": 51
}
}
]
}
}
}
You can check which permissions are applied on a catalog item with the following query:
query GetCatalogItemOperationsPermissions($gid: GID!) {
catalogItem(gid: $gid) {
operationsPermissions {
_operations {
operation
__typename
}
__typename
}
gid
nodePath
parentNodePath
parentGid
type
__typename
}
}
The following example shows the expected result of the query:
Listing catalog item operations permissions query response body
{
"extensions": {
"__$r": "syA?~&X>oj^3=5 c&[_)Q |1t2G9U/X-=uBQuPM_`ctp|Y+XL6d(,e-e.C EfaB'/N8`\\+b_!x`Hh(C`k.)60.xzP"
},
"data": {
"catalogItem": {
"operationsPermissions": {
"_operations": [
{
"operation": "anomalyDetection:anomalies",
"__typename": "OperationPermission"
},
{
"operation": "anomalyDetection:attributeAnomalies",
"__typename": "OperationPermission"
},
{
"operation": "catalog:partitionsInfo",
"__typename": "OperationPermission"
},
{
"operation": "catalog:preview",
"__typename": "OperationPermission"
},
{
"operation": "catalog:readData",
"__typename": "OperationPermission"
},
{
"operation": "comments:closeOpenComments",
"__typename": "OperationPermission"
},
{
"operation": "comments:createComments",
"__typename": "OperationPermission"
},
{
"operation": "comments:deleteComments",
"__typename": "OperationPermission"
},
{
"operation": "comments:deleteOwnComments",
"__typename": "OperationPermission"
},
{
"operation": "comments:readComments",
"__typename": "OperationPermission"
},
{
"operation": "comments:readCommentsMetadata",
"__typename": "OperationPermission"
},
{
"operation": "comments:readCommentsThreadMetadata",
"__typename": "OperationPermission"
},
{
"operation": "comments:uploadPictures",
"__typename": "OperationPermission"
},
{
"operation": "core:access",
"__typename": "OperationPermission"
},
{
"operation": "core:copy",
"__typename": "OperationPermission"
},
{
"operation": "core:createDeleteDraft",
"__typename": "OperationPermission"
},
{
"operation": "core:createNew",
"__typename": "OperationPermission"
},
{
"operation": "core:createResurrectDraft",
"__typename": "OperationPermission"
},
{
"operation": "core:discard",
"__typename": "OperationPermission"
},
{
"operation": "core:editAll",
"__typename": "OperationPermission"
},
{
"operation": "core:manageAccess",
"__typename": "OperationPermission"
},
{
"operation": "core:publish",
"__typename": "OperationPermission"
},
{
"operation": "core:revert",
"__typename": "OperationPermission"
},
{
"operation": "core:transferStewardship",
"__typename": "OperationPermission"
},
{
"operation": "core:updateReferences",
"__typename": "OperationPermission"
},
{
"operation": "core:viewAccess",
"__typename": "OperationPermission"
},
{
"operation": "core:viewAll",
"__typename": "OperationPermission"
},
{
"operation": "dataExport:dataExportStart",
"__typename": "OperationPermission"
},
{
"operation": "dataExport:downloadFile",
"__typename": "OperationPermission"
},
{
"operation": "dataOutlierDetector:deleteOutlierDetectionResult",
"__typename": "OperationPermission"
},
{
"operation": "dataOutlierDetector:deleteOutlierDetectionResults",
"__typename": "OperationPermission"
},
{
"operation": "dataOutlierDetector:getOutlierDetectionResult",
"__typename": "OperationPermission"
},
{
"operation": "dataOutlierDetector:getOutlierDetectionResults",
"__typename": "OperationPermission"
},
{
"operation": "dataOutlierDetector:getServiceConfiguration",
"__typename": "OperationPermission"
},
{
"operation": "dataOutlierDetector:runOutlierDetection",
"__typename": "OperationPermission"
},
{
"operation": "dmm-dq:dmmImportCatalogItemDQ",
"__typename": "OperationPermission"
},
{
"operation": "dmm-dq:dmmValuesValidation",
"__typename": "OperationPermission"
},
{
"operation": "dmm-dq:dmmValuesValidationUpToDateInfo",
"__typename": "OperationPermission"
},
{
"operation": "dmm-stewardship:dmmDeleteAllRecords",
"__typename": "OperationPermission"
},
{
"operation": "dmm-stewardship:dmmDeleteAttributes",
"__typename": "OperationPermission"
},
{
"operation": "dmm-stewardship:dmmDeleteEntity",
"__typename": "OperationPermission"
},
{
"operation": "dmm-stewardship:dmmDeleteEntityAttribute",
"__typename": "OperationPermission"
},
{
"operation": "dmm-stewardship:dmmDeleteRecord",
"__typename": "OperationPermission"
},
{
"operation": "dmm-stewardship:dmmDeleteRecords",
"__typename": "OperationPermission"
},
{
"operation": "dmm-stewardship:dmmDuplicateAttribute",
"__typename": "OperationPermission"
},
{
"operation": "dmm-stewardship:dmmDuplicateAttributes",
"__typename": "OperationPermission"
},
{
"operation": "dmm-stewardship:dmmDuplicateRecord",
"__typename": "OperationPermission"
},
{
"operation": "dmm-stewardship:dmmRecords",
"__typename": "OperationPermission"
},
{
"operation": "dmm-stewardship:dmmRenameAttribute",
"__typename": "OperationPermission"
},
{
"operation": "dmm-stewardship:dmmReorderAttributes",
"__typename": "OperationPermission"
},
{
"operation": "dmm-stewardship:dmmReorderRecord",
"__typename": "OperationPermission"
},
{
"operation": "dmm-stewardship:dmmSaveEntityAttribute",
"__typename": "OperationPermission"
},
{
"operation": "dmm-stewardship:dmmSaveRecordValue",
"__typename": "OperationPermission"
},
{
"operation": "dmm-stewardship:dmmSetAttributeValues",
"__typename": "OperationPermission"
},
{
"operation": "dmm-stewardship:importCatalogItem",
"__typename": "OperationPermission"
},
{
"operation": "dmm-stewardship:triggerImportFileData",
"__typename": "OperationPermission"
},
{
"operation": "dqEvalCheck:checkCatalogItemDqEval",
"__typename": "OperationPermission"
},
{
"operation": "dqeval:runCatalogItemDqEval",
"__typename": "OperationPermission"
},
{
"operation": "profiling:bulkProfile",
"__typename": "OperationPermission"
},
{
"operation": "profiling:profile",
"__typename": "OperationPermission"
},
{
"operation": "pushdown:getSnowflakeSupport",
"__typename": "OperationPermission"
},
{
"operation": "reconciliation:compareProfilingResults",
"__typename": "OperationPermission"
},
{
"operation": "reportCatalog:originLink",
"__typename": "OperationPermission"
},
{
"operation": "reportCatalog:preview",
"__typename": "OperationPermission"
},
{
"operation": "reportCatalog:structure",
"__typename": "OperationPermission"
},
{
"operation": "reportCatalog:thumbnail",
"__typename": "OperationPermission"
},
{
"operation": "storage:getAttributeAggregationResultOverTime",
"__typename": "OperationPermission"
},
{
"operation": "storage:getCatalogItemAggregationResultOverTime",
"__typename": "OperationPermission"
},
{
"operation": "storage:getProcessings",
"__typename": "OperationPermission"
},
{
"operation": "storage:getRuleInstanceResultOverTime",
"__typename": "OperationPermission"
}
],
"__typename": "catalogItemOperationPermissions"
},
"gid": "08664d56-0000-7000-0000-00000008d94a",
"nodePath": "/sources/locations/catalogItems",
"parentNodePath": "/sources/locations",
"parentGid": "15bbce34-0000-7000-0000-0000001612ed",
"type": "tableCatalogItem",
"__typename": "catalogItemNodeWrapper"
}
}
}
To update the access levels on entity, use the following mutation:
mutation UpdateAccessLevel_catalogItem($gid: GID!, $sharingRequests: [SharingRequestGT!]!) {
catalogItemShareAccessLevel(gid: $gid, sharingRequests: $sharingRequests) {
result {
gid
__typename
}
__typename
}
}
An example of variables to execute the mutation with:
Updating access level on a catalog item variables
{
"gid": "08664d56-0000-7000-0000-00000008d94a",
"sharingRequests": [
{
"accessLevel": "edit", // access level name from the assignableAccessLevels
"action": "ADD", // or REMOVE
"target": { // exactly one of the following must be provided
"identity": 103 // numericalIdentifier
"group": "Finance" // group name
"username": "john.taylor" // username
}
}
]
}
The example response contains the identifier of the shared entity:
Updating access level on a catalog item operation response body
{
"extensions": {
"__$r": "tMDTs#/]_93ai?i`OL8;l{z\\y^;wQG,QdaE\")HTV^o/1_G2`1J,h8>ng?6< !"
},
"data": {
"catalogItemShareAccessLevel": {
"result": {
"gid": "08664d56-0000-7000-0000-00000008d94a",
"__typename": "catalogItemNodeWrapper"
},
"__typename": "catalogItemMutationResult"
}
}
}
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
}
]
}
}
}
}
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.
Run 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: "dqConfiguration", 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 contains the GID of the newly created configuration:
Setting global results retention operation response body{ "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:
GrapghQL mutation for publishing monitoring project configurationmutation publishConfig { projectResultsRetentionConfigurationPublish(gid: "b8a87c0e-827d-46c0-9fa6-765ab5b39950"){ success } }
To remove the configuration:
-
Send a
delete
mutation using the GID of the configuration.GrapghQL mutation for removing monitoring project configurationmutation delete { projectResultsRetentionConfigurationDelete(gid: "b8a87c0e-827d-46c0-9fa6-765ab5b39950"){ success result { gid } } }
-
The response contains a GID for the
delete
configuration. -
Publish the
delete
configuration using the GID from the previous response.GrapghQL mutation for publishing the configuration removalmutation publishConfig { projectResultsRetentionConfigurationPublish(gid: "b8a87c0e-827d-46c0-9fa6-765ab5b39950"){ success } }
DQ results
This query (dqCheckResultOverTime
) 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
- Specifies which runs should be included in the results. You can use these three approaches:-
Limit: Returns last n runs. Use the format
{limit: X}
.By default, there is a limit of 10. This means, for example, that if you define a time range within which more than 10 processings are available, only results for 10 processings are returned. Increase the limit in combination with other parameters, such as time range, when required (maximum possible limit value is 2147483647
). -
Time range: Returns runs in specified time range. Unspecified
to
parameter means until present time. Use the following format: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 following format:
selector: { processingIds: [ "34174311-f4b0-4efe-9462-272a066e6117", "00e71092-a53b-47f4-ae50-792b777609e7" ] }
-
-
Filter
- Specifies which rows should be included in results. Filter attributes must match filter configuration of run.In other words, 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 is 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 the same meaning as listing all possible values. Never use value #ALL#
with other values as it gives incorrect results. You can use it alone but the preferred way is to use an empty list instead. -
catalogItemId
- ID of the catalog item. -
checkIds
- List of DQ check IDs (gid
attribute ofdqCheck
entity).
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
}
}
}
}
}
}
Aggregation results
This query (dqAggregationResultOverTime
) returns results of selected aggregations.
There are a number of parameters that can be defined:
-
Selector
- Specifies which runs should be included in the results. You can use these three approaches:-
Limit: Returns last n runs. Use the format
{limit: X}
.By default, there is a limit of 10. This means, for example, that if you define a time range within which more than 10 processings are available, only results for 10 processings are returned. Increase the limit in combination with other parameters, such as time range, when required (maximum possible limit value is 2147483647
). -
Time range: Returns runs in specified time range. Unspecified
to
parameter means until present time. Use the following format: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 following format:
selector: { processingIds: [ "34174311-f4b0-4efe-9462-272a066e6117", "00e71092-a53b-47f4-ae50-792b777609e7" ] }
-
-
Filter
- Specifies which rows should be included in results. Filter attributes must match filter configuration of run.In other words, 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 is 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 the same meaning as listing all possible values. Never use value #ALL#
with other values as it gives incorrect results. You can use it alone but the preferred way is to use an 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).
-
query DqAggregationResultOverTime {
monitoringProject(gid: "5c866cdf-0000-7000-0000-000000080043") {
publishedVersion {
dqAggregationResultOverTime(
selector: { limit: 1 }
catalogItemId: "6b03e87f-ae53-4c41-a16e-3c4b7234063b"
aggregationIds: [
"6b03e87f-ae53-4c41-a16e-3c4b7234063b"
"d046700c-f668-4d11-86bb-8af529deecf5"
]
filter: [
{
attributeId: "d3c8da98-0dea-4523-903c-cbc4a3f28e8b"
values: ["Fire", "Water", "Grass"]
}
{
attributeId: "00e71092-a53b-47f4-ae50-792b777609e7"
values: ["Blastoise", "Bulbasaur", "Charizard"]
}
]
) {
aggregationId
dimensions {
dimensionId
processings {
processingId
startedAt
totalCount
results {
count
id
name
}
}
}
}
}
}
}
Monitoring project results
This query (dqProjectResultsOverTime
) 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
- Specifies which runs should be included in the results. You can use these three approaches:-
Limit: Returns last n runs. Use the format
{limit: X}
.By default, there is a limit of 10. This means, for example, that if you define a time range within which more than 10 processings are available, only results for 10 processings are returned. Increase the limit in combination with other parameters, such as time range, when required (maximum possible limit value is 2147483647
). -
Time range: Returns runs in specified time range. Unspecified
to
parameter means until present time. Use the following format: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 following format:
selector: { processingIds: [ "34174311-f4b0-4efe-9462-272a066e6117", "00e71092-a53b-47f4-ae50-792b777609e7" ] }
-
query {
monitoringProject(gid: "957a400f-cfb7-4c0b-91f1-2f4ec441d734") {
publishedVersion {
dqProjectResultOverTime(selector: { limit: 10 }) {
dimensionId
processings {
processingId
startedAt
totalCount
results {
count
id
name
}
}
}
}
}
}
This query returns results for each dimension and also the aggregation of the overall quality.
Overall quality has its own dimensionId
which comes from the entitydqOverallDimensionConfiguration
.
You can find out which ID correlates to overall quality using the following query:
dqOverallDimensionConfigurations(
versionSelector: { publishedVersion: true }
) {
edges {
node {
gid
publishedVersion {
_displayName
}
}
}
}
Filter values
This query (dqFilterValues
) provides data values of filter attributes.
You need to define the parameter catalogItemId
.
This must be the ID of the catalog item, not the catalog item instance.
query ProcessingFilterValues {
monitoringProjectProcessing(gid: "da0be1f4-c8c2-430e-85ee-747861e357e6"){
publishedVersion {
dqFilterValues(catalogItemId: "6f589e83-ebd4-4486-8b79-f7d0498e6c6e"){
name
values
attributeId
order
}
}
}
}
Retrieving filter values query response body
{
"data": {
"monitoringProjectProcessing": {
"publishedVersion": {
"dqFilterValues": [
{
"name": "type",
"values": [
"#ALL#",
"Fire",
"Grass",
"Water",
"null"
],
"attributeId": "d3c8da98-0dea-4523-903c-cbc4a3f28e8b",
"order": 0
},
{
"name": "name",
"values": [
"#ALL#",
"Blastoise",
"Bulbasaur",
"Charizard",
"Charmander",
"Charmeleon",
"Invalidosaur",
"Ivysaur",
"Squirtle",
"Venusaur",
"Wartortle"
],
"attributeId": "00e71092-a53b-47f4-ae50-792b777609e7",
"order": 1
}
]
}
}
}
}
Each attribute includes value "#ALL#" .
This is a keyword marking all possible values.
|
Catalog items
Catalog result queries live under the catalogItem
or attribute
entities.
DQ rule instance results
This query (dqRuleInstanceResultOverTime
) returns results of DQ rule instances.
Results also include explanations for invalidity.
-
Selector
- Specifies which runs should be included in the results. You can use these three approaches:-
Limit: Returns last n runs. Use the format
{limit: X}
.By default, there is a limit of 10. This means, for example, that if you define a time range within which more than 10 processings are available, only results for 10 processings are returned. Increase the limit in combination with other parameters, such as time range, when required (maximum possible limit value is 2147483647
). -
Time range: Returns runs in specified time range. Unspecified
to
parameter means until present time. Use the following format: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 following format:
selector: { processingIds: [ "34174311-f4b0-4efe-9462-272a066e6117", "00e71092-a53b-47f4-ae50-792b777609e7" ] }
-
-
Attribute - List of attributes IDs and optional list of rule IDs.
query {
catalogItem(gid: "5c866cdf-0000-7000-0000-0000000553fb") {
publishedVersion {
dqRuleInstanceResultOverTime(
selector: { limit: 1 }
attributes: [
{
attributeId: "5c866cdf-0000-7000-0000-000000055408"
},
{
attributeId: "5c866cdf-0000-7000-0000-000000055406",
ruleIds: ["5c866cdf-0000-7000-0000-00000005542a"]
}
]
) {
attributeId
results {
ruleId
processings {
processingId
startedAt
partitionInfo {
partitionType
partitions {
dataType
name
value
}
}
results {
count
name
id
explanations {
count
name
id
}
}
}
}
}
}
}
}
Attribute aggregation results
This query (dqAttributeAggregationResultOverTime
) returns results of certain DQ aggregations for attributes.
There are a number of parameters that can be defined:
-
Selector
- Specifies which runs should be included in the results. You can use these three approaches:-
Limit: Returns last n runs. Use the format
{limit: X}
.By default, there is a limit of 10. This means, for example, that if you define a time range within which more than 10 processings are available, only results for 10 processings are returned. Increase the limit in combination with other parameters, such as time range, when required (maximum possible limit value is 2147483647
). -
Time range: Returns runs in specified time range. Unspecified
to
parameter means until present time. Use the following format: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 following format:
selector: { processingIds: [ "34174311-f4b0-4efe-9462-272a066e6117", "00e71092-a53b-47f4-ae50-792b777609e7" ] }
-
-
Attribute IDs - List of attributes and optional list of dimension IDs.
query {
catalogItem(gid: "5c866cdf-0000-7000-0000-0000000553fb") {
publishedVersion {
dqAttributeAggregationResultOverTime(
selector: { limit: 1 }
attributes: [
{
attributeId: "5c866cdf-0000-7000-0000-000000055408",
aggregationIds: ["0a2a2a64-ff0f-4e05-94c1-3413f09a50e0"]
},
{
attributeId: "5c866cdf-0000-7000-0000-000000055406"
}
]
) {
attributeId
aggregations {
dimensionId
processings {
processingId
partitionInfo {
partitions {
dataType
name
value
}
partitionType
}
ruleInstanceCount
attributeCount
totalCount
startedAt
results {
count
name
id
}
}
}
}
}
}
}
Catalog item aggregation results
This query (aggregationResultOverTime
) returns results of certain DQ aggregations for catalog items.
There are a number of parameters that can be defined:
-
Selector
- Specifies which runs should be included in the results. You can use these three approaches:-
Limit: Returns last n runs. Use the format
{limit: X}
.By default, there is a limit of 10. This means, for example, that if you define a time range within which more than 10 processings are available, only results for 10 processings are returned. Increase the limit in combination with other parameters, such as time range, when required (maximum possible limit value is 2147483647
). -
Time range: Returns runs in specified time range. Unspecified
to
parameter means until present time. Use the following format: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 following format:
selector: { processingIds: [ "34174311-f4b0-4efe-9462-272a066e6117", "00e71092-a53b-47f4-ae50-792b777609e7" ] }
-
-
Dimension IDs - Optional list of dimension IDs. They can be IDs for specific dimensions or for the overall quality.
query {
catalogItem(gid: "5c866cdf-0000-7000-0000-0000000553fb") {
publishedVersion {
aggregationResultOverTime(
selector: { limit: 2 }
dimensionIds: ["0a2a2a64-ff0f-4e05-94c1-3413f09a50e0"]
) {
dimensionId
processings {
processingId
startedAt
ruleInstanceCount
attributeCount
totalCount
partitionInfo {
partitions {
dataType
name
value
}
partitionType
}
results {
count
name
id
}
}
}
}
}
}
Catalog item validity
This query (validityAggr
) returns the latest validity result for a catalog item.
query {
catalogItem(gid: "5c866cdf-0000-7000-0000-0000000553fb") {
publishedVersion {
validityAggr {
publishedVersion {
validCount
invalidCount
validColor
invalidColor
overallQuality
}
}
}
}
}
Catalog item processing
This query (dqProcessings
) returns a list of catalog item processings.
There are a number of parameters that can be defined:
-
skip
- Pagination, how many results should be skipped. -
size
- Pagination, result limit.
query {
attribute(gid: "5c866cdf-0000-7000-0000-000000055408") {
publishedVersion {
dqProcessings(size: 3) {
processingId
startedAt
partitionInfo {
partitionType
partitions {
dataType
name
value
}
}
}
}
}
}
Attribute validity
This query (validityAggr
) returns the latest validity result for an attribute.
query {
attribute(gid: "77215050-8ce9-4b12-94d9-2bc9265c2c07"){
publishedVersion {
validityAggr {
publishedVersion {
validCount
invalidCount
validColor
invalidColor
overallQuality
}
}
}
}
}
Change rule reference strategy
By default, componentInstances
has the trait core:reference
with value versionStrategy = FIX_HCN
.
This means the reference is fixed to the history change number at time of creation, and component rules might not use the latest component implementation.
To remove the trait and always reference the latest version instead, use the mutation:
mutation {
ruleComponentInstanceUpdateReferences(
gid: "4671cd3c-0000-7000-0000-000000060036",
referenceNodePaths: ["target"],
fixLatestHcn:true
) {
success
}
}
This mutation is generic and can be used to change traits on other entities within monitoring projects but needs to be executed separately for each entity. |
Was this page useful?