Transformation og opbygning af JSON-objekter med jq

JSON fra den virkelige verden er ofte indlejret. jq lader dig tilgå indlejrede stier i en objektkonstruktion og flader samtidig strukturen ud.

Brug prikstienotation i konstruktørens værdiudtryk:

• { city: .address.city }
• { lat: .location.coords.lat }

Eksemplet nedenfor tager en dybt indlejret brugerpost og producerer en flad opsummering, der egner sig til en CSV-overskriftsrække eller brødteksten i en API-anmodning.

map(expr) svarer i jq til en løkke, der kører for hvert element: Den anvender expr på hvert element i et input-array og returnerer et nyt array med samme længde.

Vigtige punkter:

• map(expr) er en kortform for [.[] | expr]
• Udtrykket indeni kan være et hvilket som helst jq-filter — herunder konstruktion af objekter
• Kombinér med select() for at filtrere før omformningen

Uddraget behandler en liste over ordrer og beholder kun de felter, der er nødvendige for en forsendelsesoversigt.

I map kan du beregne nye værdier, konvertere typer og kombinere felter — ikke kun kopiere dem. Almindelige mønstre omfatter:

• Tekstinterpolation: "\(.first) \(.last)"
• Aritmetik: (.price * 1.2 | round) for et tillæg på 20 %
• Betingelser: if .score >= 90 then "A" else "B" end

Eksemplet nedenfor udvider en liste over medarbejdere ved at tilføje et beregnet fullName og en seniority-etiket baseret på års erfaring.

to_entries konverterer et JSON-objekt til et array af par på formen {key, value}. Det giver adgang til array-operationer (map, select, sort) på et objekts felter — noget, du ikke kan gøre direkte på et objekt.

Eksempel på omformning:

• Input: {"a": 1, "b": 2}
• Output: [{"key": "a", "value": 1}, {"key": "b", "value": 2}]

Den omvendte operation er from_entries, som omdanner arrayet tilbage til et objekt. Tilsammen udgør de idiomet to_entries | map(...) | from_entries til omformninger på objektniveau.

En af de mest praktiske anvendelser af to_entries er at filtrere dynamisk, hvilke nøgler der skal beholdes eller fjernes, baseret på selve nøglens navn — noget, som objektkonstruktion ikke kan gøre, når du ikke kender nøglenavnene på forhånd.

Mønster:

• to_entries | map(select(.key | test("regex"))) | from_entries
• to_entries | map(select(.key != "secret")) | from_entries

Uddraget nedenfor fjerner alle nøgler, der begynder med en understregning (interne/private felter), før et konfigurationsobjekt videresendes til en ekstern tjeneste.

Objektkonstruktion omdøber nøgler, når du kender deres navne, mens du skriver koden. to_entries lader dig omdøbe nøgler programmatisk — for eksempel konvertere camelCase til snake_case eller tilføje et præfiks.

I map opdaterer du feltet .key for hvert element og sender derefter resultatet videre til from_entries:

• map(.key |= gsub("(?<=[a-z])(?=[A-Z])"; "_") | .key |= ascii_downcase) — camelCase til snake_case
• map(.key |= "app_" + .) — tilføj et præfiks til hver nøgle

Eksemplet giver alle miljøvariabelnavne præfikset APP_ for at placere dem i et navnerum, før de indsættes i en container.

Mønsteret to_entries | map(...) | from_entries er så almindeligt, at jq har en kortform: with_entries(expr).

Det er præcis det samme, men mere kompakt:

• with_entries(.value |= . * 2) — fordobl alle numeriske værdier
• with_entries(select(.value != null)) — fjern nøgler med null-værdier
• with_entries(.key |= ascii_upcase) — skriv alle nøgler med store bogstaver

Uddraget fjerner alle nøgler, hvis værdi er null eller en tom tekststreng — et almindeligt oprydningstrin, før en PATCH-anmodning sendes til en REST-API.

Virkelige omformninger kæder flere jq-operationer sammen. En typisk filterkæde til klargøring af en API-payload kan:

1. Filtrere input-arrayet med map(select(...))
2. Ændre strukturen for hvert element med objektkonstruktion
3. Tilføje beregnede felter
4. Sortere resultatet

Eksemplet nedenfor læser en liste over servermålinger, beholder kun servere med højt CPU-forbrug og producerer en kompakt alarm-payload, der er klar til at blive sendt med POST til en webhook.

jq kan flette input og konstruere objekter, der henter data fra flere JSON-kilder, ved hjælp af additionsoperatoren + og variabelbinding med as $var.

Nyttige mønstre:

• obj1 + obj2 — flet to objekter (værdien på højre side vinder ved konflikter mellem nøgler)
• --argjson — videregiv et andet JSON-dokument som en variabel
• $ENV — læs miljøvariabler direkte i jq

Uddraget fletter en grundkonfiguration med miljøspecifikke tilsidesættelser — et almindeligt mønster til håndtering af konfiguration for 12-factor-applikationer i shell-scripts.

Du har gennemgået de vigtigste teknikker til at ændre strukturen i JSON med jq:

• Objektkonstruktion {} — opbyg nye objekter ved at vælge, omdøbe og beregne felter fra et input
• map(expr) — anvend en hvilken som helst omformning på hvert element i et array, herunder indlejret objektkonstruktion og select() til filtrering
• to_entries / from_entries — konverter et objekt til et array af {key, value}-par, så du kan udføre array-operationer på nøgler og værdier, og konverter derefter tilbage
• with_entries(expr) — den kompakte kortform for den fulde to_entries → map → from_entries-filterkæde
• Fletning af objekter med + og --argjson til payloads fra flere kilder

Disse byggesten kan kombineres: filtrer med select, ændr strukturen med objektkonstruktion, udvid med beregnede felter, og kæd det hele sammen i ét læsbart jq-udtryk. Når du mestrer disse mønstre, kan du håndtere stort set enhver JSON-payload direkte i shellen uden at skrive et dedikeret script i Python eller Node.