Vanliga frågor (FAQ)

Här hittar du svar på de vanligaste frågorna om PDQ-dataplattformen.

Plattformsarkitektur och grundbegrepp

F: Vad är PDQ-plattformen, och hur hänger kärnmodulerna ihop?

S: PDQ by Simplitics är en samlad dataplattform som kombinerar automation med end-to-end aktiv metadatahantering. Sju moduler täcker flödet från källa till leverans:

• AME (Active Metadata Engine): Det centrala repositoryt som håller all systemlogik, historiska operationer och planerade scheman. Alla andra moduler kommunicerar via AME:s API:er.
• INGEST (Data Importer): En containerbaserad agent som hämtar data från SQL-databaser, REST-API:er och filsystem enligt schema, och skriver rådata till Landing-zonen.
• DLS (Data Lake Service): En händelsestyrd worker som upptäcker nya filer i Landing, arkiverar dem i Raw Archive, standardiserar dem till Trusted och publicerar dem för SQL-åtkomst.
• DWA (Data Warehouse Automation): En batch- och händelsestyrd motor som automatiserar datamodellering, SQL-kodgenerering och ELT-laddning med push-down i måldatabasen.
• QPI (Quality Performance Indicator): Ramverkets datakvalitetsmotor, som kör SQL-kontroller mot data i DWA. Den rapporterar avvikelser; den blockerar inte laddningen.
• DataOps-konsolen: Det operatörsinriktade gränssnittet för att övervaka den dagliga körningen, bryta ned körtidsstatistik och åtgärda fel.
• Config UI: Utvecklargränssnittet, med Git-integration, för att hantera metadatadefinitioner och CI/CD-driftsättning.

Se Arkitektur för helhetsbilden, och sidorna INGEST, DLS och DWA för detaljerna lager för lager.

F: Vad betyder "Design as Documentation", och hur förhindrar det kodglidning?

S: Design as Documentation är grundprincipen att din design är dokumentationen — och att dokumentationen är det som genererar den körbara koden. Eftersom tabeller, transformationsregler och laddningsskript genereras från aktiv metadata kan dokumentationen inte hamna i otakt med det som faktiskt körs. Det finns ingen separat artefakt att underhålla, och därmed ingen kodglidning över tid.

F: Vad skapar PDQ egentligen i min måldatabas, utöver tabeller och rader?

S: Genereringskörningen skapar styrningen tillsammans med strukturen:

• Kolumn- och tabellkommentarer, inuti CREATE TABLE på Snowflake och Databricks, hämtade ur beskrivningarna i datakontraktet och modellen.
• Primärnycklar på publiceringstabeller, unika villkor ur affärsnycklar på core-tabeller och främmande nycklar ur relationsmetadata. Alla tre är på som standard.
• Kategoritaggar ur fieldDomain och känslighetstaggar ur flaggan sensitive, med varje plattforms egen taggningsfunktion — SET TAGS på Databricks, som inte genererar någon mask.
• Frågetaggar på varje sats, så att varje fråga i målets historik namnger jobbet, steget och körningen som utfärdade den.

Inget på den listan är ett separat steg du kör i efterhand. Se Vad som landar i målmiljön.

F: Måste jag klassificera känsliga kolumner igen i målet?

S: Nej. Klassificering deklareras en gång på källfilsfältet — sensitive och fieldDomain — och generatorn applicerar den på målkolumnerna som en del av att tabellerna byggs. På hierarkiska källor appliceras även domäntaggarna för affärsnycklar som ärvts från förfädernivåer på de normaliserade barntabeller som bär de nycklarna, så en kolumn som klassificerats en gång förblir klassificerad överallt plattformen kopierar den.

Två förbehåll är värda att känna till: Databricks genererar inga upprätthållna UNIQUE, PK eller FK, så unikhet måste där vara en QPI-kvalitetskontroll; och taggnamnen kommer från TAG_NAME, SENSITIVE_TAG_NAME och SENSITIVE_TAG_VALUE, som är värda att sätta till ditt eget schema före den första genereringskörningen.

F: Kan jag få in PDQ:s metadata och härkomst i min egen katalog?

S: Ja, på två vägar.

• REST-API:et. AME:s v3-API är samma gränssnitt som konsolen och generatorerna läser — konfiguration, datakontrakt, scheman, loggar, revisionsposter och härkomst. /api/v3.2 täcker objektnivågenerering, och SQL Generator-API:et returnerar den genererade DDL:en själv, så definitioner kan diffas i CI innan driftsättning.
• OpenLineage. Varje exekvering genererar start- och sluthändelser; QPI-kvalitetskontroller genererar föräldrajobbhändelser; härkomst på attributnivå finns som ett detaljerat alternativ. Härkomsten landar därmed i den katalog eller observabilitetsplattform du redan kör, utan en egen separat inläsningspipeline.

F: Hur undviker PDQ inlåsning mot moln och databaser?

S: Alla moduler paketeras som fristående Docker-containrar (Python 3.12 på Debian 12), så plattformen kör på Azure, AWS, Cleura eller on-premises utan förändring.

Data kan dessutom läggas till, ändras eller avvecklas i vilket arkitekturlager som helst — Landing, Raw Archive, Trusted, Published, Integrated eller Business. Den lösa kopplingen gör att du kan hoppa över en komponent eller byta ut föredragen lagrings- eller databasteknik utan att resten av ekosystemet går sönder.

Installation och konfiguration

F: Vilka är minimikraven för att köra PDQ-plattformen?

S: Plattformen körs som Docker-containrar på en Linux-värd — Ubuntu 22.04 är referensplattformen — med nätverksåtkomst till käll- och målsystem.

	Minimum	Rekommenderat
Docker Engine	20.10+	24.0+
RAM	8 GB	16 GB
CPU	4 kärnor	8 kärnor
Lagring	100 GB	500 GB
Databas	Delad	Dedikerad instans (SQL Server, PostgreSQL eller annan motor som stöds)

Dimensioneringstabellen underhålls i Installera och säkra plattformen — behandla den sidan som facit.

F: Hur konfigurerar jag FQDN för Caddy?

S: För Caddy-konfiguration:

1. Säkerställ att din server har ett Fully Qualified Domain Name (FQDN)
2. Öppna port 443 i brandväggen (endast internt, inte offentligt)
3. Skapa ett nytt Docker-nätverk (t.ex. xx_caddynet)
4. Ta bort alla mappade portar från ame-compose.yml för säkerhet
5. Konfigurera Azure AD App Registration för autentisering

F: Varför kan jag inte komma åt utvecklargränssnittet?

S: Kontrollera följande:

1. Docker-containrar körs: docker ps -a - alla bör vara "Up"
2. Nätverkskonfiguration: Verifiera att ports är korrekt mappade
3. Caddy-status: Om använt, kontrollera Caddy-konfigurationen
4. Brandväggsinställningar: Säkerställ att rätt portar är öppna
5. DNS-upplösning: Kontrollera att FQDN fungerar korrekt

Datainhämtning (INGEST)

F: Hur lägger jag till en ny datakälla?

S: Ett inhämtningsflöde konfigureras antingen via Config UI eller programmatiskt via API:et.

Via Config UI:

1. Öppna sidan Ingest och klicka på Add new system (ett unikt systemnamn i ett ord plus en beskrivning)
2. Välj anslutningstyp — DB eller API
3. För DB: ange databasnamn, alias, serveradress, port, användare och lösenord
4. För API: ange API-URL, autentiseringsmetod (OAuth 2.0, TOKEN eller NONE), token-URL samt eventuella headers och anslutningsegenskaper
5. Konfigurera Source Export: fromClause (DB) eller apiPath (API), utdataformat (JSON eller CSV), filnamn, suffix och schemacykel
6. Testa anslutningen och verifiera första leveransen

Via kod:

1. Anslutning — posta en anslutnings-JSON till /api/v3/ingest/connection/for/:sourceSystem. Databaslösenord måste först krypteras via AME:s krypterings-API.
2. Exportdefinition — posta en export-JSON med fromClause/apiPath, alias, suffix, inclColumns/exclColumns, whereClause, scheduleCycle och enableCDC till /api/v3.1/ingest/definition/for/:sourceSystem/:alias
3. Agent — starta en INGEST-container med målet -n :sourceSystem

Fullständig parameterreferens: Arbeta med Ingest.

F: Hur fungerar Change Data Capture (CDC) i INGEST?

S: Med enableCDC = 1 jämför INGEST varje exporterad rad mot det tidigare exporterade tillståndet och skriver bara nya, ändrade eller borttagna poster.

CDC jämför varje körning mot en baseline som agenten håller lokalt, i filen <alias>_latestversion.txt inuti sin egen container. Baselinen överlever en omstart — det är vad filen finns för. Den överlever inte att containern förstörs eller tas bort: nästa körning exporterar då allt en gång och bygger upp en ny baseline.

Att kombinera enableCDC = 1 med dynamisk filtrering i whereClause gör att rader som filtret utesluter rapporteras som borttagningar. Använd det ena eller det andra.

F: Vilka dynamiska tidsstämpel-platshållare finns?

S: Platshållarna kan användas både i filnamnets suffix och i frågefilter:

Platshållare	Betydelse
[__SCHEDULEDTIME__]	Den planerade schematidpunkten. Ett jobb som kör försent hämtar ändå det tidsfönster det var tänkt att hämta, inte det fönster då det råkade köras.
[__EXECUTIONTIME__]	Den faktiska tidpunkten då exporten startade.
[__LASTEXECUTION__]	Tidsstämpeln för föregående export — grunden för inkrementella frågor som WHERE ModifyDate > '[__LASTEXECUTION__]'.

Relativa offset som [__SCHEDULEDTIME_MINUS_7_DAYS__] stöds för rullande tidsfönster. I filnamnets suffix skrivs samma värden som [__SCHEDULEDTIME__], [__EXECUTIONTIME__] och [__LASTEXECUTION__].

F: Vad betyder "Missing Expected Files (Red Banner)"?

S: En röd banner indikerar att:

• Förväntade filtyper inte har levererats enligt schema
• INGEST-agenter har misslyckats eller inte körts
• Källsystem kan vara otillgängligt eller ha ändrat struktur
• Kontrollera INGEST Tasks-vyn för specifika felmeddelanden

F: Hur konfigurerar jag INGEST för Microsoft Teams och SharePoint?

S: Filer som ligger i en Teams-kanal lagras i det underliggande SharePoint-dokumentbiblioteket, så båda hämtas via Microsoft Graph-API:et:

1. Azure AD-uppsättning — registrera en applikation i Azure AD/Entra, notera Application (client) ID och Directory (tenant) ID, och skapa en client secret
2. API-behörigheter — ge Microsoft Graph application-behörigheterna (Sites.Read.Selected eller Sites.Read.All, samt Files.Read.All) och låt en Azure AD-administratör bevilja admin consent
3. Anslutning — posta en API-anslutning till /api/v3/ingest/connection/for/<SOURCESYSTEMNAME> med APIUrl: "https://graph.microsoft.com/v1.0", APIAuthMethod: "OAuth 2.0", APITokenUrl: "https://login.microsoft.com/<TENANT_ID>/oauth2/v2.0/token" och klientuppgifterna i APIConnectionProperties
4. Exportdefinition — peka på Graph-sökvägen, till exempel /sites/{site-id}/drives/{drive-id}/items/{item-id}/children, med ett filter som lastModifiedDateTime=[__SCHEDULEDTIME_MINUS_3_DAYS__]
5. Container — skapa en teams.yaml eller sharepoint.yaml där sourcetype sätts till teams respektive sharepoint, och kör containern simplitics1/simpleingestion

Lagra client secrets krypterade via AME:s krypterings-API — aldrig i klartext i en konfigurationsfil.

Data Lake Service (DLS)

F: Vad betyder olika zoner i DLS Trace?

S: DLS-zonerna representerar:

• Landing: Första landing för rådata från INGEST
• Raw Archive: Permanent arkivering för revision och återuppspelning
• Trusted: Standardiserat format. Avvikelser mot datakontraktet registreras här, de blockeras inte
• Published: Tabellformat optimerat för SQL-åtkomst
• Profile: Utökad metadata och dataprofileringsstatistik

F: Varför är räkningarna olika mellan zonerna?

S: Ingenting filtreras bort mellan zonerna, så ett underskott betyder att något fastnat — inte att något sorterats bort. Se Vad plattformen registrerar, och vad den stoppar.

De två undantagen är dupliceringshanteringen mellan Landing och Raw Archive, och tidsglappet mellan Trusted och Published, där en leverans helt enkelt kan vara opublicerad när fönstret stängs.

Landing, Raw Archive, Trusted och Profile ska stämma överens. Published kan ligga något lägre; en skillnad på upp till 10–20 poster är normal och i sig inget fel. Större avvikelser är värda att undersöka.

F: Hur aktiverar jag streaming för stora XML/JSON-filer?

S: En stor eller djupt nästlad XML- eller JSON-fil som läses in i minnet i ett stycke kan tömma serverns RAM och krascha bearbetningsworkern. Streaming löser det:

1. Identifiera den hierarkiska nivå där poster ska delas — typiskt det upprepade elementet, som <company> eller <order>
2. Sätt "useForSplittingRecords": 1 på den nivån i metadatans fileStructure
3. Använd API:et — inställningen finns inte i Config UI utan måste uppdateras via backend, till exempel /api/v3.2/sourcefiles/:sourceFilename

DLS strömmar då filen bit för bit från den nivån och nedåt, utelämnar föräldraelementen ovanför delningspunkten och skriver ut flera plattare poster. Minnesförbrukningen sjunker kraftigt och genomströmningen ökar. DWA:s SQL-generator upptäcker flaggan automatiskt och förenklar de efterföljande Published-frågorna.

F: Vad är hierarkiska ID:n (_HID) och granulära checksummor?

S: Båda genereras av Data Modifier för varje element i ett nästlat dokument, och båda finns för att göra nästlad data spårbar:

• _HID är en punktseparerad sökväg som 1.2.4.1 som beskriver elementets exakta position i källdokumentet. Den gör att en databasrad kan spåras tillbaka till sitt ursprung, och den fungerar som stabil intern join-nyckel när nästlade arrayer delas upp i separata tabeller — join-logiken behöver alltså inte förlita sig på affärsnycklar.
• Granulära checksummor beräknas på varje objektsnivå i stället för bara på dokumentroten. Det gör förändringsdetekteringen precis: en ändring i en enskild underliggande post markerar inte hela föräldrafilen som ändrad.

Data Warehouse Automation (DWA)

F: Vad är skillnaden mellan Ensemble-modellen och CORE-modellen?

S: DWA använder en modellarkitektur i två lager inom Integrated-lagret:

Modell	Syfte	Form
Ensemble / Intermediate	Agil, starkt normaliserad integration baserad på Anchor Modeling eller typade Data Vault-mönster	Varje attribut och relation i egen fysisk tabell, fullt historiserad, med direkt spårbarhet till __fileKey
CORE / Enterprise	En fysisk, konsoliderad kopia av ensemble-vyerna som representerar den integrerade verksamhetsmodellen	En rad per affärsnyckel — den senaste versionen — för snabb BI och nedströms rapportering

Ensemble-modellen svarar på "vad visste vi, och när?". CORE-modellen svarar snabbt på "vad gäller nu?". Se Data Warehouse Automation (DWA).

F: Vilka laddningsmönster finns för CORE?

S: Fem mönster styr hur CORE/Enterprise-modellen fylls på:

Mönster	Beteende
none	Lämnar data som en konsoliderad vy utan att materialisera en fysisk tabell (standard)
full	Trunkerar och laddar om all data vid varje körning
dayspan	Rullande fönster — fångar förändringar från en konfigurerbar tidsperiod, till exempel de senaste 7 dagarna
incremental	Fångar bara de senaste förändringarna, baserat på schemats körintervall
transaction	Lägger bara till nya poster, utan uppdateringar

F: Vad krävs för att DWA ska generera SQL?

S: Varje mappningsgrupp — arbetsenheten — måste innehålla minst en affärsnyckelmappning och en attributmappning. Saknas nyckelmappningen genererar DWA ingen SQL och ingen data laddas. Mappningssidan flaggar en omappad affärsnyckel och erbjuder att mappa den på plats. Detta är en av flera tysta felmoder. Per laddningstyp:

• Objektladdning: Fullständig nyckelmappning
• Attributladdning: Nyckelmappning + attributmappning
• Relationsladdning: Två kompletta nycklar från samma källa
• Alla mappningar måste ligga i samma mappningsgrupp, som också delar källfil, filtervillkor och sorteringsordning

F: Hur skapas relationer?

S: Relationer definieras i målmodellen, aldrig i det enskilda mappningsprogrammet. När en källfil fyller de kompletta affärsnycklarna för två relaterade modellobjekt inom samma mappningsgrupp genererar och kör DWA relationsladdningen automatiskt.

Villkoret är att den kompletta affärsnyckeln fylls för båda objekten. Om den inte gör det skapas ändå en relation — fast mot en falsk affärsnyckel, vilket innebär att ingen relaterad data blir tillgänglig. Se Tysta felmoder.

F: Hur startar jag om misslyckade DWA-uppgifter?

S: För att starta om uppgifter:

1. Identifiera misslyckade uppgifter (röda i lista/Gantt-diagram)
2. Markera relevanta uppgifter för specifikt schema och källfil
3. Använd "Restart Tasks" från DataOps-konsolen
4. Övervaka progress för att säkerställa framgångsrik omstart

F: Varför skapas onödiga DWA-scheman?

S: Detta kan hända när:

• **On file arrival-uppgifter skapas utan Core-modellberoenden
• Lösning: Stoppa schemat via API: POST /api/v3/master/schedule/{sourcefile}
• Sätt ValidTo-datum för att inaktivera schemat

DataOps och övervakning

F: Vilka är de dagliga kontrollrutinerna?

S: Sex kontroller, i den här ordningen: System Health, INGEST Tasks, DLS Trace, DWA Loading Tasks, DWA Additional Tasks, QPI Monitor.

Hela rutinen — vad varje kontroll letar efter, och vad du gör när en av dem slår ut — är dokumenterad på ett ställe: Den dagliga rundan.

Det som är värt att veta i förväg: varje sida i konsolen har en egen checklista som jämför konfigurerat mot utfört. Det är det snabbaste sättet att upptäcka arbete som aldrig startade alls, vilket ett mått på "inga fel" aldrig avslöjar.

F: Hur använder jag DataOps-konsolen effektivt?

S: DataOps-konsolen erbjuder:

• Dashboard-vy: Högnivåstatus över alla komponenter
• Runtime-statistik: Detaljerad prestanda och trender
• Uppgiftshantering: Omstart av misslyckade processer
• Aviseringshantering: Centraliserad notifikationshantering

En sida som rapporterar "no data for the selected time range" svarar oftast korrekt för ett tidsfönster som är för smalt — vidga det globala datumintervallet innan du antar att något gått fel.

Felsökning

F: Vad gör jag om hela systemet är nere?

S: Första stegen:

1. Stoppa och starta VM från molnportalen (vanligaste lösningen)
2. Om problemet kvarstår: SSH till servern
3. Kontrollera disken: df -h — en full /datadrive blockerar allt
4. Kontrollera Docker: docker ps -a (alla ska vara "Up")
5. Manuell omstart: kör docker compose down följt av docker compose up -d från /datadrive/configs för varje komponent i strikt ordning: UI → AME → DLS → DWA → INGEST

Ordningen spelar roll: varje tjänst är beroende av den föregående, och AME måste vara uppe innan DLS, DWA och INGEST kan hämta sina instruktioner.

F: Hur hanterar jag en degraderad System Health-status?

S: När System Health rapporterar System degraded:

1. Identifiera specifika misslyckade uppgifter/filer
2. Starta om de misslyckade komponenterna
3. Kontrollera loggar för grundorsaken
4. Dokumentera incidenten för framtida referens

F: Hur återställer jag avbrutna pipelines efter en krasch?

S: Arbeta framåt genom lagren och starta bara om det steg som inte blev klart:

1. Hitta det som aldrig blev klart — öppna jobbloggen i System Health och filtrera på status = INIT för att hitta processer som startade men aldrig rapporterade slutförande. Kontrollera måltabellerna med __fileKey för att se om data laddades delvis.
2. Granska DLS Trace — filtrera på lastSeenOn:
   • Fast i raw: markera raderna, öppna admin-konsolen och klicka på Load Trusted
   • Fast i landing: kontrollera filstorleken först. En mycket stor fil som orsakat en minneskrasch måste delas upp i mindre delar innan du kör om Load Raw.
   • Saknad Trusted-laddning (trustedNumberOfFiles = 0): filtrera på det antalet eller på specifik fileKey och klicka på Load Trusted
3. Starta om containrarna om de inte svarar — se startordningen ovan.

F: Hur löser jag ett Published-laddningsfel orsakat av radlängd i JSON i Azure Synapse?

S: Symptom: Published-laddningen misslyckas med ett fel som refererar till en gräns på 500 000 tecken i Synapse-funktionen OPENROWSET.

Orsak: stora nästlade JSON-uttag ackumulerar _hid- och _checksum-attribut genom djupa hierarkier, vilket kan trycka en enskild JSON-rad förbi Synapses hårda gräns för radlängd.

Åtgärd:

1. Öppna Azure Storage Explorer och navigera till trusted/temporary_files/<System>/<SourceFile>
2. Ladda ned de .json.gz-filer som skapats sedan den senaste lyckade laddningen
3. Kör det lokala städskriptet som delar upp de för långa JSON-raderna
4. Ladda upp de städade filerna till lagringens rotmapp igen och skriv över originalfilnamnen
5. Klicka på Restart på det misslyckade Published-jobbet i DataOps-konsolen

F: Vad betyder "Metadata Case Mismatch"?

S: Måldatabaserna — Snowflake, Databricks, SQL Server, Azure Synapse, Fabric och PostgreSQL — utvärderar fieldKey mot sökvägen i JSON-/XML-dokumentet med SQL:s JSON-operatorer, som kräver exakt matchning av versaler och gemener. Skiljer sig fieldKey eller path från källan på ett enda tecken hittar operatorn ingenting och kolumnen returnerar NULL.

• Håll fieldKey och path exakt matchade mot källan — de är skiftlägeskänsliga
• För en annan namnkonvention i måltabellerna (versaler, f_-prefix och liknande), använd fieldAlias och levelAlias tillsammans med de globala inställningarna columnPrefix och tableNameCasing

Prestanda och skalning

F: Hur skalar jag PDQ-plattformen för större datavolymer?

S: För skalning:

• DLS: Minimum 6 containers, skala workers baserat på kapacitet
• DWA: Minimum 4 containers, placera nära databasen
• INGEST: Distribuera agenter nära datakällor
• Överväg separata regioner för olika komponenter

F: Vad är bästa praxis för prestanda?

S: Prestandarekommendationer:

• Placera AME och DLS i samma region som repository-databasen
• Använd streaming för stora XML/JSON-filer
• Optimera nätverkslatens mellan komponenter
• Övervaka resursanvändning regelbundet via DataOps-konsolen