Skip to main content

Parquedit

Sist endret

04.10.2026

Parquedit er en tjeneste som gir statistikere database-funksjonalitet over Parquet-filer. Formålet med tjenesten er å dekke lagringsbehovene knyttet til arbeid med manuell editering av data i SSB. Les mer om Prinsipper og retningslinjer for dataeditering i SSB.

Parquedit inkluderer IKKE et grafisk grensesnitt (GUI) for å gjøre manuelle endringer på data, kun en enkel Python-funksjon som oppdaterer informasjon i en rad i et datasett. Parquedit kan derimot benyttes som en underliggende lagringsløsning som oppdateres via GUI’er som Editeringsrammeverket eller andre løsninger.

ssb-parquedit er bygget på Ducklake og har følgende egenskaper:

Tjenesten lagrer data i statistikkteamets produktbøtte, mens metadata lagres i en sentral katalog på Dapla. Teamene kan benytte seg av Python-pakken ssb-parquedit for å jobbe med Parquedit-tabellen sine fra Dapla Lab.

  1. Installer pakken i prosjektet ditt:
Terminal
poetry add ssb-parquedit
  1. Opprett en klient og se data:
Notebook
from ssb_parquedit import ParquEdit

con = ParquEdit()
con.view(table_name="manuell_tabell", limit=5)
  1. Oppdater en rad med begrunnelse:
Notebook
row = con.view(table_name="manuell_tabell", where="enhet_id = '12345'")
rowid = row["rowid"].iloc[0]

con.edit(
    table_name="manuell_tabell",
    rowid=rowid,
    changes={"status": "GODKJENT"},
    change_event_reason="REVIEW",
    change_comment="Manuell kvalitetssikring",
)

Bruksområde

Parquedit er ment som et lagringsformat som kan benyttes under arbeidsprosessen for manuell og maskinell editering. Tjenesten forutsetter at brukeren ønsker å enten oppdatere en og en enhet etter manuelle vurderinger av en person, og støtter oppdateringer av tabellen etter maskinell editering. Tjenesten forutsetter også at oppdateringer skjer i en enkelttabell. Parquedit har ikke støtte for primary eller foreign nøkler.

Når arbeidsprosessen med manuell editering er gjennomført og data lagres i stabile datatilstander, så forutsetter systemet at teamet som eier dataene selv henter ut opplysninger fra Parquedit med logger som skal benyttes til kvalitetsrapporter og gi evnen til å gjenskape manuelle editeringer på et senere tidspunkt.

Forberedelser

For at et team skal kunne benytte seg av Parquedit må Teamansvarlig først aktivere tilgang i Dapla Ctrl. Det gjøres på følgende måte:

  1. Gå inn i Dapla Ctrl
  2. Åpne Instillinger på Teamsiden
  3. Under Parquedit velger du Aktiver tilgang

Etter dette kan teamets medlemmer opprette så mange Parquedit-tabeller de ønsker.

Et team som har aktivert tilgangen kan åpne en tjeneste i Dapla Lab. For at ParquEdit skal kunne benyttes sammen med andre løsninger som benytter Postgres, må man aktivere Parquedit-tilgang under Avansert når man setter opp tjenesten:

og installere Python-pakken ssb-parquedit i et ssb-project på følgende måte:

Terminal
poetry add ssb-parquedit

Anbefalt tabelloppsett

ssb-parquedit er hovedsakelig konstruert for manuell celleeditering i tabulære data der hver rad representerer én statistisk enhet (f.eks. ett foretak eller én person). Der det er mulig anbefaler vi derfor at strukturere Parquedit-tabellene som flate og brede tabeller. I de tilfellene dette ikke er ønskelig, så kan man også strukturere dataene på langform. Manuell editering av data på langform innebærer at brukeren selv må oppdatere alle radene som endres.

Under vises noen eksempler på ulike datastrukturer. Tabell 1 viser et eksempel der dataene er strukturert med en linje per bedrift som skal manuelt editeres, og hver kolonne er en egenskap eller måling ved bedriften. Hvis man oppretter en Parquedit-tabell med denne strukturen vil man kunne editere en og en virksomhet samtidig som Parquedit håndterer historikken og detaljerte logger over årsakskode og hvilken endring som ble gjort av hvem.

Tabell 1: Eksempel på anbefalt flat tabellstruktur i ssb-parquedit
orgnr foretak_navn kontakt_epost kontakt_tlf omsetning_nok ansatte_antall
987654321 Eksempel AS post@eksempel.no 22334455 14500000 12
123456789 Statistikk Drift hei@statistikk.no 99887766 3200000 3

Komplekse datatyper som  STRUCT og LIST, som vist i Tabell 2, støttes også av ssb-parquedit. Dette kan være nyttig i data som er hierarkiske av natur og hvor utflating vil generere svære mange variabler i datasettet. Nøstede felt kan editeres direkte med punktnotasjon og indekser (se «Editering av nøstede felt»).  get_edits()  logger kun det endrede underfeltet i  old_values  og  new_values , ikke hele kolonnen.

Tabell 2: Eksempel på struktur med nøstede typer (STRUCT og LIST)
orgnr foretak_navn kontakt (STRUCT) avdelinger (LIST)
987654321 Eksempel AS {'epost': 'post@eksempel.no', 'tlf': '22334455'} [{'avd_nr': 1, 'ansatte': 8}, {'avd_nr': 2, 'ansatte': 4}]
123456789 Statistikk Drift {'epost': 'hei@statistikk.no', 'tlf': '99887766'} [{'avd_nr': 1, 'ansatte': 3}]

Funksjonalitet

Under beskrives funksjonaliteten som tilbys av Parquedit. Vanlig funksjonalitet tilbys som funksjoner i Python-biblioteket ssb-parquedit.

Opprette kobling

For å jobbe med Parquedit-tabeller må man første opprette en kobling. Opprett en standardkobling på følgende måte:

Notebook
from ssb_parquedit import ParquEdit

con = ParquEdit()

Avanserte brukere kan også konfigurere sin egen kobling til Parquedit. Det beskrives nærmere senere.

Opprette ny tabell

Man kan opprette en ny Parquedit-tabell basert på følgende input:

  • Parquet-fil
  • Dataframe i minnet (Pandas, Polars, etc.)
  • json-skjema

Ved opprettelse av tabeller lages det automatisk en kolonne rowid som fungerer som en unik identifikator for hver rad innen en tabell. Hver rad i tabellen får dermed en unik rowid som brukes til å identifisere raden ved editering. rowid er et reservert kolonnenavn og kan ikke benyttes som kolonnenavn i tabeller som lastes inn.

Notebook
# Opprett fra eksisterende Parquet-fil i GCS (skjema utledes fra filen)
con.create_table(
    table_name="manuell_tabell_gcs",
    source="gs://my-bucket/path/to/file.parquet",
    product_name="eksempelprodukt",
    user_defined_id=["enhet_id", "aar"],
)
Notebook
import pandas as pd

df = pd.DataFrame(
    {
        "enhet_id": ["A1", "A2"],
        "aar": [2025, 2025],
        "status": ["NY", "NY"],
    }
)

con.create_table(
    table_name="manuell_tabell",
    source=df,
    product_name="eksempelprodukt",
    user_defined_id=["enhet_id", "aar"],
    fill=True,
)
Notebook
import pandas as pd
skjema = {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "orgnr": {"type": "integer"},
        "foretak_navn": {"type": "string"},
        # STRUCT
        "kontakt": {
            "type": "object",
            "properties": {
                "epost": {"type": "string"},
                "tlf": {"type": "string"},
            },
        },
        # LIST av enkle verdier
        "tags": {"type": "array", "items": {"type": "string"}},
        # LIST av STRUCT
        "avdelinger": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "avd_nr": {"type": "integer"},
                    "ansatte": {"type": "integer"},
                },
            },
        },
    },
    "required": ["orgnr"],
}

con.create_table(
    table_name="manuell_nostet",
    source=skjema,
    product_name="eksempelprodukt",
    user_defined_id=["orgnr"],
    fill=False,  # skjema inneholder ingen data
    )

df = pd.DataFrame(
    {
        "orgnr": [987654321, 123456789],
        "foretak_navn": ["Eksempel AS", "Statistikk Drift"],
        "kontakt": [
            {"epost": "post@eksempel.no", "tlf": "22334455"},
            {"epost": "hei@statistikk.no", "tlf": "99887766"},
        ],
        "tags": [["ny", "stor"], ["liten"]],
        "avdelinger": [
            [{"avd_nr": 1, "ansatte": 8}, {"avd_nr": 2, "ansatte": 4}],
            [{"avd_nr": 1, "ansatte": 3}],
        ],
    }
)
con.insert_data("manuell_nostet", df)

Følgende argumenter må oppgis ved opprettelse av ny tabell:

table_name er det navnet på tabellen du ønsker å opprette. Siden et team kan ha flere tabeller, er det dette navnet som benyttes senere for å referere til tabellen. Tabellnavn må være lowercase, starte med bokstav eller underscore, kun inneholde lowercase-bokstaver, tall og underscore, og være maks 20 tegn.

source er kilden (Parquet, Dataframe eller json-skjema) som skal benyttes til å opprette tabellen.

product_name er obligatorisk og lagres som en kommentar på tabellen.

user_defined_id er en liste med kolonner som til sammen unikt identifiserer en rad, tilsvarende en primærnøkkel.

fill er et boolsk argument som angir om tabellen skal fylles med eksisterende data fra kilden ved opprettelse.

Partisjonert tabeller

Notebook
# Opprett partisjonert tabell og fyll med data
con.create_table(
    table_name="manuell_tabell_partisjonert",
    source=df,
    product_name="eksempelprodukt",
    part_columns=["aar"],
    user_defined_id=["enhet_id"],
    fill=True,
)

Laste data

Last inn data i en eksisterende tabell

Notebook
con.insert_data(
    table_name="manuell_tabell",
    source=df,
)

Lese data

Notebook
# Hent alle rader (pandas DataFrame)
df = con.view(table_name="manuell_tabell")

# Filter og velg kolonner
utvalg = con.view(
    table_name="manuell_tabell",
    where="aar = 2025",
    columns=["enhet_id", "status", "verdi"],
    order_by="enhet_id ASC",
)
Notebook
# Alle rader (returnerer pandas DataFrame som standard)
result = con.view("manuell_tabell")

# Filtrering med WHERE-betingelse
result = con.view("manuell_tabell", where="aar = 2025")
result = con.view("manuell_tabell", where="enhet_id = 'A1' AND aar >= 2025")

# Velg spesifikke kolonner
result = con.view("manuell_tabell", columns=["enhet_id", "aar"])

# Sorter resultater
result = con.view("manuell_tabell", order_by="aar DESC")

# Returner som polars eller pyarrow
result = con.view("manuell_tabell", output_format="polars")
result = con.view("manuell_tabell", output_format="pyarrow")

Editering

En vanlig flyt er:

  1. Finn riktig rad og les ut rowid.
  2. Kall edit() med nye verdier for raden identifisert med rowid.
  3. Oppgi årsak (change_event_reason) og kommentar (change_comment).
Notebook
# 1) Finn raden som skal endres
rad = con.view(
    table_name="manuell_tabell",
    where="enhet_id = 'A1' AND aar = 2025",
)
rowid = rad["rowid"].iloc[0]

# 2) Oppdater verdier på raden
con.edit(
    table_name="manuell_tabell",
    rowid=rowid,
    changes={"status": "KORRIGERT"},
    change_event_reason="REVIEW",
    change_comment="Endret etter intern kontroll",
)

Editering av nøstede felt

For nøstede felt i en STRUCT kan man bruke punktnotasjon for å spesifisere underfeltet som skal endres. For lister kan man bruke indekser for å oppdatere spesifikke elementer.

Eksemplene under bruker tabellen manuell_nostet fra opprettelse av tabell fra json-skjema, med kontakt (STRUCT), tags (LIST) og avdelinger (LIST av STRUCT).

Notebook
rowid = con.view(
    table_name="manuell_nostet",
    where="orgnr = 987654321",
)["rowid"].iloc[0]

# Oppdater et underfelt i en STRUCT
con.edit(
    table_name="manuell_nostet",
    rowid=rowid,
    changes={"kontakt.epost": "ny@eksempel.no"},
    change_event_reason="REVIEW",
    change_comment="Oppdatert e-postadresse",
)

# Oppdater et element i en LIST
con.edit(
    table_name="manuell_nostet",
    rowid=rowid,
    changes={"tags[0]": "middels"},
    change_event_reason="REVIEW",
    change_comment="Oppdatert første tag",
)

# Oppdater et underfelt i et element i en LIST av STRUCT
con.edit(
    table_name="manuell_nostet",
    rowid=rowid,
    changes={"avdelinger[0].ansatte": 10},
    change_event_reason="REVIEW",
    change_comment="Oppdatert antall ansatte i første avdeling",
)

changes er en ordbok (dict) med par på formen {kolonnenavn: ny_verdi}.

Gyldige verdier for change_event_reason er:

  • OTHER_SOURCE
  • REVIEW
  • OWNER
  • MARGINAL_UNIT
  • DUPLICATE
  • OTHER

Regelbasert editering med update_where()

Hvis du vil endre flere rader på en gang, kan du bruke update_where(). Funksjonen oppdaterer alle rader som matcher en where-betingelse (SQL uten selve WHERE-nøkkelordet), uten at du først må finne rowid. Samme changes brukes på alle matchende rader, og man oppgir change_event_reason og change_comment som ved edit(). Alle endringene logges som én transaksjon (ett snapshot) i endringshistorikken.

Notebook
con.update_where(
    table_name="manuell_tabell",
    where="aar = 2025 AND status = 'UTKAST'",
    changes={"status": "KONTROLLERT"},
    change_event_reason="REVIEW",
    change_comment="Satt status etter intern kontroll",
)
Note

where bruker samme syntaks som i view() og delete_row(), f.eks. "population < 100000" eller "id IN (1, 2)".

Masseeoppdatering med update_bulk()

Hvis ulike rader skal få ulike verdier, f.eks. etter maskinell editering, kan du bruke update_bulk(). Du oppgir en dictionary der nøkkelen er rowid og verdien er en dictionary med kolonner og nye verdier. Alle endringene utføres i én transaksjon (rulles tilbake ved feil) og logges som ett snapshot i endringshistorikken, inkludert bruker, berørte rader og kolonner. Funksjonen støtter foreløpig ikke oppdatering av Struct-typer eller List-er med dot-notasjon. Hvis disse ønskes masseoppdaterte må man erstatte hele Struct/list inkludert de nye verdiene. Masseoppdateringer kan generere mye inlinede data i basen og mange små parquet-filer pr tabell, så det anbefales å kjøre metodene flush_inlined_data() og merge_adjacent_files() med jevne mellomrom for å holde ytelsen stabil.

Notebook
con.update_bulk(
    table_name="manuell_tabell",
    changes={
        1: {"status": "KONTROLLERT", "belop": 100},
        2: {"status": "KONTROLLERT"},
        },
    change_event_reason="REVIEW",
    change_comment="Satt status og beløp etter intern kontroll",
    script_id="github.com/statisticsnorway/dapla_ffunk/src/editing/imputation.py@5bb8b73897eb7e26c0b7031b8e7955f0e9bbccd1",
    script_info="threshold=18, dry_run=False",
)
Note

script_id identifiserer skriptet som gjorde oppdateringen, og er en lenke til GitHub-repoet (filsti) sammen med commit-SHA. script_info inneholder tilleggsinformasjon, f.eks. parametere som ble brukt i kjøringen.

Sletting av rader

For å slette rader fra en tabell kaller man delete_row() med where for å identifisere raden(e) som skal fjernes.

Notebook
con.delete_row(
    table_name="manuell_tabell",
    where="enhet_id = 'A1' AND aar = 2025",
    change_event_reason="REVIEW",
    change_comment="Slettet etter intern kontroll")

Sletting av rader krever at man oppgir både change_event_reason og change_comment for å dokumentere hvorfor raden(e) ble fjernet. Gyldige verdier for change_event_reason er:

  • OTHER_SOURCE
  • REVIEW
  • OWNER
  • MARGINAL_UNIT
  • DUPLICATE
  • OTHER

Sletting av flere rader logges som en hendelse i endringsloggen. get_edits() vil vise hvor mange rader som ble påvirket og hvilken where-betingelse som ble brukt.

Endringshistorikk

Bruk get_edits() for å hente historikk over manuelle endringer.

Notebook
# Endringer for en tabell
logg = con.get_edits(table_name="manuell_tabell")

# Alternativt alle tabeller
alle_endringer = con.get_edits()

Dette gir blant annet:

  • hvem som gjorde endringen
  • tidspunkt for endringen
  • begrunnelse og kommentar
  • gamle og nye verdier
  • endringstype (UPDATE/DELETE)
  • where-betingelsen som ble brukt ved sletting av rad(er)
  • hvor mange rader som ble påvirket av endringen

Timetravel

time_travel() – Tar ut en tabell slik den så ut på et bestemt tidspunkt, bruker DuckLakes timetravelfunksjon. Godtar de samme argumentene som view() (where, limit, offset, columns, order_by og output_format). at_time angir tidspunktet for timetravel på formatet YYYY-MM-DD HH:MM:SS

Notebook
# Timetravel for en tabell
tabell_paa_tidspunkt = con.time_travel(
    table_name="manuell_tabell",
    at_time="2026-09-26 00:00:00",
    where="aar=2025"
)

Backup

CautionViktig: Brukere må selv ta backup av Parquedit-tabeller

I første versjon av ssb-parquedit tas det ikke en sentral backup av enkelttabeller. Det vil si at hvis en tabell blir ødelagt, så kan den ikke gjenskapes. Derfor anbefaler vi at brukerne eksporterer teamets tabeller med jevne mellomrom slik at den kan gjennopprettes ved behov med funksjonen export_catalog(). Det er også anbefalt å eksportere endringshistorikken med jevne mellomrom med funksjonen ´get_edits()´.

Liste tabeller

Liste ut alle tabeller som tilhører teamet:

Notebook
tabeller = con.list_tables()

Antall rader i en tabell

Notebook
con.count(table_name="manuell_tabell")

Sjekk av eksistens

Notebook
con.exists(table_name="manuell_tabell")

Vedlikehold

Slette tabell

Gjør følgende for å fjerne tabellen fra den sentrale katalogen, slette editeringshistorikk og filene i teamets bøtte:

Notebook
con.drop_table("manuell_tabell", cleanup=True)

Hvis man ønsker å beholde editeringshistorikk og selve datafilene i produktbøtta, legger man til cleanup=False på denne måten:

Notebook
con.drop_table("manuell_tabell", cleanup=False)

Flush av inlinede data

Flush av inlinede data materialiserer inlinede rader til Parquet-filer for en tabell. Dette er en vedlikeholdsoperasjon for arbeidsflyter med hyppige, små skriveoperasjoner, og bidrar til å holde lagringsstrukturen effektiv og spørreytelsen stabil. Operasjonen endrer ikke tabellverdiene, kun hvordan dataene er fysisk lagret. Operasjonen er trygg å kjøre gjentatte ganger: Å kjøre den når det ikke er noe ventende har ingen effekt.

Notebook
# Flusher inlinede data for tabellen 'manuell_tabell'
con.flush_inlined_table(table_name="manuell_tabell")

Merge adjacent files

Å slå sammen tilstøtende filer komprimerer en tabells små Parquet-filer til færre, større filer. Dette er et vedlikeholdssteg for tabeller som mottar mange små skriveoperasjoner, som forbedrer skanneeffektiviteten og reduserer overhead ved filhåndtering. Operasjonen bevarer tabelldata og historikksemantikk, og endrer kun det fysiske fillayoutet. Operasjonen er trygg å kjøre gjentatte ganger: Å kjøre den når ingenting kan slås sammen har ingen effekt.

Notebook
# Slår sammen tilstøtende filer for tabellen 'manuell_tabell'
con.merge_adjacent_files(table_name="manuell_tabell")

Eksporter katalog

export_catalog() tar sikkerhetskopi av DuckLake-metadatakatalogen. Den flusher og slår sammen inlinede data for alle tabeller, og kopierer deretter alle tabeller fra det PostgreSQL-baserte katalogskjemaet inn i en DuckDB-fil, som lastes opp til GCS. Returnerer hele GCS-stien (inkludert filnavn) til den eksporterte sikkerhetskopien.

Notebook
# Eksporter med standard sti ({data_path}/catalog-export)
con.export_catalog()

# Eksporter til en egendefinert GCS-sti
con.export_catalog(export_path="gs://bucket/backups")

Importer katalog

import_catalog() gjenoppretter DuckLake-metadatakatalogen fra en sikkerhetskopifil produsert av export_catalog(). For hver tabell som finnes i sikkerhetskopien, blir eksisterende rader i katalogen slettet og erstattet med de sikkerhetskopierte radene.

Notebook
# Gjenopprett katalogen fra en sikkerhetskopifil
con.import_catalog(backup_file_path="gs://bucket/backups/20250101_120000_my_schema.duckdb")

Avansert

Sette opp lokal tilkobling

Opprett en ParquEdit-instans støttet av en persistent lokal SQLite-katalog. Nyttig for lokal utvikling og testing uten tilgang til GCS eller PostgreSQL. Katalogen og datafilene lagres på path og består mellom økter. Mappen opprettes hvis den ikke allerede finnes.

Notebook
con = ParquEdit().local(path="/home/onyxia/work/")

Få tilgang til den underliggende DuckDB-tilkoblingen

ParquEdit pakker inn en DuckDBConnection, som eksponerer den underliggende duckdb.DuckDBPyConnection via .raw-egenskapen. Dette er nyttig når man integrerer med biblioteker som krever en nativ DuckDB-tilkobling, som Ibis.

Notebook
import ibis
from ssb_parquedit import ParquEdit

con = ParquEdit()
raw = con._get_connection().raw  # duckdb.DuckDBPyConnection

ibis_conn = ibis.duckdb.connect(conn=raw)
table = ibis_conn.table("manuell_tabell")

Merk:

  • _get_connection() er en intern metode. Den underliggende tilkoblingen deler tilstand med ParquEdit — å lukke den ene påvirker den andre. Ikke lukk den underliggende tilkoblingen manuelt mens ParquEdit fortsatt er i bruk.
  • Ved bruk av den underliggende tilkoblingen er det brukerens ansvar å oppgi den informasjonen som ParquEdit-metodene ellers gir. F.eks. ved oppretting og redigering av tabeller.

Gjenopprette en lokal katalogsikkerhetskopi med GCS-data

ParquEdit.local_with_gcs_data() kobler til en lokal DuckDB-katalogfil (f.eks. en produsert av export_catalog()), mens selve Parquet-dataene fortsatt ligger på GCS. Nyttig for å inspisere eller gjenopprette fra en DuckLake-katalogsikkerhetskopi uten behov for en aktiv PostgreSQL-tilkobling. Må brukes i DaplaLab for å få tilgang til GCS-bøtter.

Notebook
con = ParquEdit.local_with_gcs_data(catalog_path="localcopy.duckdb")

Konfigurere logging

ssb-parquedit bruker Pythons standard logging-modul. Hver intern modul har sin egen logger via logging.getLogger(__name__), så biblioteket konfigurerer ikke selv noen handlers — initialiser logging i din egen applikasjon før du bruker ParquEdit:

Notebook
import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)-8s %(name)s: %(message)s",
)

from ssb_parquedit import ParquEdit

con = ParquEdit()

For å se mer detaljert output (f.eks. for feilsøking), sett nivået til logging.DEBUG, eventuelt bare for ssb_parquedits egne loggere:

Notebook
logging.getLogger("ssb_parquedit").setLevel(logging.DEBUG)