🎯 Definicja
Zapytania One API (One API Queries) to zapytania w języku GraphQL służące do pobierania danych i metadanych z platformy Ataccama ONE (np. modułu Metadata Management). W przeciwieństwie do tradycyjnych interfejsów REST API, GraphQL umożliwia klientom precyzyjne określenie struktury zwracanych danych w ramach jednego żądania HTTP, eliminując problem nadmiarowego pobierania danych (over-fetching).
🔑 Kluczowe punkty
- Precyzja: Klient definiuje dokładnie te pola, które są mu potrzebne, w tym dane zagnieżdżone i powiązane encje.
- Identyfikator GID: Podstawą pobierania konkretnych encji jest ich unikalny, globalny identyfikator
gid. - Funkcje zaawansowane: Zapytania obsługują sortowanie (
orderBy), stronicowanie (paginację z parametramiskip,size,cursor) oraz filtrowanie (za pomocą języka AQL i AI). - Zadania asynchroniczne: Przez API można wywoływać operacje takie jak profilowanie danych, a następnie odpytywać o ich status (Job status).
📚 Szczegółowe wyjaśnienie
Pobieranie i przeszukiwanie encji
Zapytania GraphQL pozwalają na przeglądanie struktury metadanych Ataccama ONE. Możliwe jest nakładanie filtrów oraz sortowania:
- Prymitywne sortowanie: np.
orderBy: [{ property: "name", direction: ASC }]. - Paginacja: kontrolowana za pomocą parametrów
skipisizelub kursorów. - Filtrowanie:
filter– standardowe filtry oparte na języku AQL (Ataccama Query Language).query– zapytanie AQL przetwarzane wstępnie przez algorytmy sztucznej inteligencji.queryParts– przyjazne dla użytkownika klocki filtrów przetwarzane przez AI.
Statystyki i agregacje Jakości Danych (DQ)
Platforma umożliwia pobieranie zagregowanych wyników jakości danych dla pojęć biznesowych (Business Terms):
- Wystąpienia terminu (Term occurrences): Określa, do ilu encji (np. atrybutów, elementów katalogu) przypisano dany termin słownikowy. Parametr
withCount: trueuwzględnia kaskadowo encje potomne. - Agregacja DQ (Aggregation Results): Zbiera ostatnie wyniki testów jakości ze wszystkich atrybutów powiązanych z terminem. Parametr
atpozwala odpytać o stan historyczny. - Ważność terminu (Term Validity): Zwraca liczbę poprawnych (valid) i niepoprawnych (invalid) rekordów w powiązanych regułach.
💡 Przykłady zapytań (Queries)
1. Listowanie elementów katalogu (List catalog items)
Zapytanie zwraca listę elementów katalogu, ich identyfikatory gid, nazwy w wersji roboczej (draftVersion) oraz przypisane do nich atrybuty.
Zapytanie (Query):
query listCatalogItems {
catalogItems(versionSelector: {draftVersion: true}) {
edges {
node {
gid
draftVersion {
name
attributes {
edges {
node {
gid
draftVersion {
name
}
}
}
}
}
}
}
}
}Odpowiedź (Response JSON):
{
"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": "2ece8b69-df78-4a95-abf9-cdbea8ebb252",
"draftVersion": {
"name": "src_sin"
}
}
}
]
}
}
}
}
]
}
}
}2. Listowanie atrybutów wybranego elementu katalogu (List CI attributes)
Pobiera listę atrybutów dla konkretnego obiektu na podstawie jego zmiennej $gid.
Zapytanie (Query):
query listAttributes ($gid: GID!) {
catalogItem(gid: $gid) {
publishedVersion {
attributes {
edges {
node {
gid
draftVersion {
name
}
}
}
}
}
}
}Odpowiedź (Response JSON):
{
"data": {
"catalogItem": {
"publishedVersion": {
"attributes": {
"edges": [
{
"node": {
"gid": "75642c37-8e88-4241-9a50-4f801eb47ade",
"draftVersion": {
"name": "name"
}
}
},
{
"node": {
"gid": "808fef47-5dc8-4e60-8e91-e914cf18dec7",
"draftVersion": {
"name": "modifieddate"
}
}
}
]
}
}
}
}
}3. Listowanie źródeł danych (List data sources)
Zwraca listę zdefiniowanych źródeł danych oraz powiązanych z nimi połączeń (connections).
Zapytanie (Query):
query listDataSources {
sources(versionSelector: { draftVersion: true }) {
edges {
node {
gid
draftVersion {
name
connections {
edges {
node {
gid
draftVersion {
name
}
}
}
}
}
}
}
}
}Odpowiedź (Response JSON):
{
"data": {
"sources": {
"edges": [
{
"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"
}
}
}
]
}
}
}
}
]
}
}
}4. Listowanie pojęć słownika biznesowego (List glossary terms)
Zwraca wszystkie dostępne terminy słownikowe w wersji roboczej.
Zapytanie (Query):
query listGlossaryTerms {
terms(versionSelector: {draftVersion: true}) {
edges {
node {
gid
draftVersion {
name
}
}
}
}
}Odpowiedź (Response JSON):
{
"data": {
"terms": {
"edges": [
{
"node": {
"gid": "033df1b9-ef3c-48c7-b40a-a8fc98249221",
"draftVersion": {
"name": "Gender"
}
}
},
{
"node": {
"gid": "08fcb90f-763b-40bf-ae7d-0601e7ec1651",
"draftVersion": {
"name": "Airports"
}
}
}
]
}
}
}5. Listowanie typów terminów słownikowych (List term types)
Odpytuje o typ każdego zdefiniowanego pojęcia biznesowego (np. keyPerformanceIndicator, businessTerm).
Zapytanie (Query):
query getTermTypes {
terms(versionSelector: { draftVersion: true }) {
edges {
node {
gid
type
}
}
}
}Odpowiedź (Response JSON):
{
"data": {
"terms": {
"edges": [
{
"node": {
"gid": "01503672-d0a0-492f-9ac6-b318fb9ee7d2",
"type": "keyPerformanceIndicator"
}
},
{
"node": {
"gid": "03b3e732-cded-40fd-9b52-134c2cfbefe3",
"type": "businessTerm"
}
}
]
}
}
}6. Listowanie projektów monitorowania jakości (List monitoring projects)
Zapytanie wyciągające identyfikatory wszystkich projektów monitorowania reguł jakościowych.
Zapytanie (Query):
query getProjects {
monitoringProjects(versionSelector: { draftVersion: true }) {
edges {
node {
gid
}
}
}
}Odpowiedź (Response JSON):
{
"data": {
"monitoringProjects": {
"edges": [
{
"node": {
"gid": "0f8f3b16-a9a4-491e-9384-eb302dda1fba"
}
},
{
"node": {
"gid": "19fce03c-e238-49c9-ab26-ddddc48c95e0"
}
}
]
}
}
}7. Wyszukiwanie wystąpień terminu (Retrieve term occurrences)
Zwraca statystyki powiązań wybranego pojęcia biznesowego (słownikowego) ze strukturami danych.
Zapytanie (Query):
query getTermOccurrences {
term(gid: "033df1b9-ef3c-48c7-b40a-a8fc98249221") {
statistics(withCount: true, relationships: []) {
usageStatistics {
nodePath
totalCount
}
}
}
}Odpowiedź (Response JSON):
{
"data": {
"term": {
"statistics": {
"usageStatistics": [
{
"nodePath": "/sources/locations/catalogItems",
"totalCount": 5
},
{
"nodePath": "/sources/locations",
"totalCount": 4
}
]
}
}
}
}8. Wyniki agregacji jakości danych (DQ) dla terminu (Retrieve term DQ aggregation results)
Zwraca wyniki jakości danych zagregowane z przypisanych atrybutów dla wybranego momentu w historii (at).
Zapytanie (Query):
query GetTermDQ {
term(gid: "410c6bac-0000-7000-0000-000000051ce3") {
publishedVersion {
aggregationResult(at: "2022-07-26T09:34:27.117946Z") {
ruleInstanceCount
attributeCount
catalogItemCount
totalCount
results {
id
count
name
}
}
}
}
}9. Szczegółowa agregacja atrybutów terminu (Retrieve term’s attribute aggregation results)
Pobiera wyniki jakości danych na poziomie konkretnych atrybutów przy użyciu filtra selektora (np. {limit: 1} dla ostatniego uruchomienia).
Zapytanie (Query):
query GetAttributeDQ {
term(gid: "410c6bac-0000-7000-0000-000000051ce3") {
publishedVersion {
attributeAggregationResult(
selector: { limit: 1 }
attributes: [
{ attributeId: "5c866cdf-0000-7000-0000-000000055412" },
{ attributeId: "5c866cdf-0000-7000-0000-000000055408" }
]
) {
attributeId
aggregations {
aggregationId
processings {
processingId
startedAt
ruleInstanceCount
attributeCount
totalCount
results {
count
name
id
}
}
}
}
}
}
}10. Walidacja i poprawność terminu (Retrieve Term Validity)
Zwraca ogólne metryki poprawności (liczba rekordów poprawnych/błędnych) przypisane do reguł powiązanych z terminem.
Zapytanie (Query):
query GetValidity {
term(gid: "410c6bac-0000-7000-0000-000000051ce3") {
publishedVersion {
dqEvalTermAggr {
publishedVersion {
attributeCount
ruleCount
validCount
invalidCount
recordCount
}
}
}
}
}11. Profilowanie: Pobieranie konfiguracji (Profiling configurations)
Przed uruchomieniem profilowania należy pobrać identyfikator konfiguracji (domyślne to FULL lub SAMPLE).
Zapytanie (Query):
query listProfilingConfigurations {
profilingConfigurations(versionSelector: { publishedVersion: true }) {
edges {
node {
gid
publishedVersion {
name
type
description
anomalyDetectionEnabled
samplingLimitCount
samplingLimitPercentage
}
}
}
}
}Odpowiedź (Response JSON):
{
"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
}
}
}
]
}
}
}12. Uruchomienie profilowania elementu katalogu (Profile catalog items: Request)
Uruchamia proces profilowania na wybranym elemencie przy użyciu pobranego identyfikatora konfiguracji (configId).
Zapytanie (Query):
query profiling {
catalogItem(gid: "0726c74e-fc9e-40ad-a29d-23ec1dac8769") {
gid
profile(defaultCredential: true, configId: "723fa8c2-9ea9-4119-b0a7-d49f1f6e4c45") {
gid
}
}
}Odpowiedź (Response JSON):
{
"data": {
"catalogItem": {
"gid": "0726c74e-fc9e-40ad-a29d-23ec1dac8769",
"profile": {
"gid": "1f6fe8e6-5b19-439d-ad2f-99b60beaefda"
}
}
}
}13. Sprawdzanie statusu zadania profilowania (Job status)
Asynchroniczne sprawdzanie stanu uruchomionego zadania (np. FINISHED, RUNNING, FAILED).
Zapytanie (Query):
query getJobStatus {
job(gid: "1f6fe8e6-5b19-439d-ad2f-99b60beaefda") {
gid
draftVersion {
status
}
}
}Odpowiedź (Response JSON):
{
"data": {
"job": {
"gid": "1f6fe8e6-5b19-439d-ad2f-99b60beaefda",
"draftVersion": {
"status": "FINISHED"
}
}
}
}📌 Źródła
👽 Brudnopis
- Różnice z REST: GraphQL pozwala pobrać dokładnie to, co zadeklarowano w zapytaniu (jeden endpoint, zagnieżdżone obiekty).
- Struktura połączeń: Wykorzystanie schematu
edgesinodedo paginacji oraz pobierania rekordów. - Parametry DQ dla terminów:
statistics: liczba przypisań pojęć w kataloguaggregationResult: zbiorcza jakość danych z poziomu regułdqEvalTermAggr: podsumowanie poprawności (valid/invalid)
- Workflow profilowania:
- Pobierz konfigurację (np.
FULL/SAMPLE) ->profilingConfigurations - Uruchom zadanie ->
profile(...) - Odpytuj o status zadania ->
job(gid) { draftVersion { status } }
- Pobierz konfigurację (np.