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.

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 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
        }
    }
}

List 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
            }
        }
    }
}

Example mutations

Create an 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 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 issue:

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

Advanced search example

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
    }
}