Data Quality API

The Data Quality component of the GraphQL API is used to create, list, fetch, update, and delete data quality issues stored in the metrics database. The GraphQL API is served at /api/graphql.

These operations require DATA_QUALITY_ISSUES permissions. See Permissions for the default roles that provide them.

Queries

• getDataQualityIssue(id: ID!): DataQualityIssue: Returns a single issue by ID, or null if it does not exist.
• getDataQualityIssueCategories: [DataQualityIssueCategory]: Returns all available issue categories, sorted by name.
• getDataQualityIssues(limit: Int, offset: Long, filter: DataQualityIssueFilterInput): DataQualityIssuePage: Returns issues sorted by most recently updated. Pass limit=0 to return all matching results.
• searchDataQualityIssues(search: DataQualityIssueSearchInput!): [DataQualityIssue]: Searches data quality issues using criteria that can be combined with AND and OR, including nested search expressions.
• getDataQualityIssuesByExternalReferences(externalReferences: [String!]!): [DataQualityIssue]: Returns Data Quality Issues associated with any of the supplied external references.

Advanced search

The following fields can be searched:

• NAME
• STATUS
• SEVERITY
• PRIORITY
• EXTERNAL_REFERENCE
• CATEGORY
• CREATED_AT
• UPDATED_AT

Supported comparators depend on the field:

• NAME, EXTERNAL_REFERENCE: EQ, NE, MATCH
• STATUS, SEVERITY, PRIORITY, CATEGORY: EQ, NE
• CREATED_AT, UPDATED_AT: EQ, NE, G, GE, L, LE

Search criteria can be combined using AND or OR, and expressions can be nested.

Mutations

• createDataQualityIssue(input: DataQualityIssueInput!): DataQualityIssue: Creates a new data quality issue and returns it.
• updateDataQualityIssue(id: ID!, input: DataQualityIssueInput!): DataQualityIssue: Updates an existing data quality issue and returns the updated version.
• deleteDataQualityIssue(id: ID!): Boolean: Deletes a data quality issue. Returns true if it was removed.

Filters across different fields are combined with AND. Values within a single field use OR.

id, createdAt, createdBy, updatedAt, updatedBy, networkModelCreatedAgainst, and networkModelResolvedAgainst are set by the server. Do not include them in create or update input.

Example queries

Get all categories (use a returned id as category on create/update):

query {
    getDataQualityIssueCategories {
        id
        name
        description
    }
}

Get a single Data Quality Issue by ID:

query {
    getDataQualityIssue(id: "abc-123") {
        id
        status
        name
        description
        suggestedResolution
        associatedAssets {
            mRID
            name
        }
        annotationGeoJson
        category {
            id
            name
            description
        }
        externalReference
        severity
        priority
        createdAt
        createdBy
        updatedAt
        updatedBy
        networkModelCreatedAgainst
        networkModelResolvedAgainst
        callouts {
            id
            longitude
            latitude
            positionX
            positionY
            width
            height
            label
            description
            colour
        }
    }
}

Get Data Quality Issues by external reference:

query {
    getDataQualityIssuesByExternalReferences(
        externalReferences: ["100", "200"]
    ) {
        id
        name
        status
        externalReference
    }
}

Get the list of Data Quality Issues with pagination and filters:

query {
    getDataQualityIssues(limit: 10, offset: 0, filter: { statuses: [CREATED, IN_PROGRESS] }) {
        totalCount
        offset
        issues {
            id
            name
            status
            severity
            priority
            associatedAssets {
                mRID
                name
            }
            category {
                id
                name
            }
        }
    }
}

Search Data Quality Issues using nested search expressions:

query {
    searchDataQualityIssues(
        search: {
            operator: OR
            operands: [
                {
                    expression: {
                        operator: AND
                        operands: [
                            {
                                criteria: {
                                    field: STATUS
                                    comparator: NE
                                    value: "RESOLVED"
                                }
                            }
                            {
                                criteria: {
                                    field: SEVERITY
                                    comparator: EQ
                                    value: "2"
                                }
                            }
                        ]
                    }
                }
                {
                    criteria: {
                        field: PRIORITY
                        comparator: EQ
                        value: "1"
                    }
                }
            ]
        }
    ) {
        id
        name
        status
        severity
        priority
    }
}

Example mutations

Create Data Quality Issue:

mutation {
    createDataQualityIssue(input: {
        status: CREATED
        name: "abc"
        description: "abc"
        suggestedResolution: "abc"
        associatedAssets: ["123"]
        annotationGeoJSON: "{\"type\":\"Point\",\"coordinates\":[1.0,2.0]}"
        category: "abc-123"
        externalReference: "abc-123"
        severity: 2
        priority: 1
        callouts: []
    }) {
        id
        name
        status
        associatedAssets {
            mRID
            name
        }
        category {
            id
            name
        }
    }
}

Update an existing Data Quality Issue:

mutation {
    updateDataQualityIssue(id: "abc-123", input: {
        status: IN_PROGRESS
        name: "abc"
        description: "abc"
        suggestedResolution: "abc"
        associatedAssets: ["123"]
        annotationGeoJSON: "{\"type\":\"Point\",\"coordinates\":[1.0,2.0]}"
        category: "abc-123"
        externalReference: "abc-123"
        severity: 2
        priority: 1
        callouts: []
    }) {
        id
        status
        name
        associatedAssets {
            mRID
            name
        }
        category {
            id
            name
        }
        updatedAt
        updatedBy
    }
}

Delete an existing Data Quality Issue:

mutation {
    deleteDataQualityIssue(id: "abc-123")
}