Przejdź do treści
Biblioteka skilli
Dane i analityka · Budowanie i kod

schema-null-defaults

/schema-null-defaults

Obsługuje wartości NULL i ustawia wartości domyślne brakujących pól w kolekcjach i materializacjach, także przy błędach nullable primary key i lukach w danych źródłowych.

Repozytorium
agent-skills ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
24.09.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
1
Przestarzałość

Brak sygnałów. Repozytorium zmienione 24.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Obsługuje wartości NULL i ustawia wartości domyślne brakujących pól w kolekcjach i materializacjach, także przy błędach nullable primary key i lukach w danych źródłowych.

Wyzwalacze z opisu

NULL valuesdefault valuemissing fieldnullable primary key errorfill in missing data
Oryginalny opis (EN)

Handle NULL values and set default values for missing fields in collections and materializations. Use when fields need defaults, nullable primary key errors occur, or source data has gaps. Use when user says "NULL values", "default value", "missing field", "nullable primary key error", or "fill in missing data".

Jak działa

  1. When to Use
  2. Prerequisites
  3. Key Concepts
  4. Procedure
  5. Common Patterns
  6. Handling Explicit NULLs
  7. Troubleshooting
  8. Related Skills
Sekcje z nagłówków SKILL.md, w oryginale · 168 linii, 698 słów
Podgląd SKILL.md
---
name: schema-null-defaults
description: Handle NULL values and set default values for missing fields in collections and materializations. Use when fields need defaults, nullable primary key errors occur, or source data has gaps. Use when user says "NULL values", "default value", "missing field", "nullable primary key error", or "fill in missing data".
---

# Handle NULLs and Default Values

Handle NULL values and set default values for missing fields in materializations.

**Docs:** https://docs.estuary.dev/concepts/schemas/#default-annotations

## When to Use

- Need to provide default values for missing/optional fields
- Handling nullable primary key errors in materializations (`cannot materialize collection with nullable key field unless it has a default value annotation`)
- Ensuring consistent values when source data has gaps

## Prerequisites

- Existing collection to modify
- `flowctl` authenticated

## Key Concepts

- `default` applies only to **missing** fields, not to explicit `null` values. A field present with `null` stays `null`.
- `default` is read by materializations only — captures and derivations ignore it. Add defaults to the readSchema so auto-discover (which only touches writeSchema/connector-schema) can't overwrite them.

## Procedure

### Step 1: Pull Collection Specs

```bash
flowctl catalog pull-specs --name <tenant>/<collection-name>
```

### Step 2: Identify the Read Schema

Find the read schema file (e.g., `collection.read.schema.yaml`).

Typical structure for collections using schema inference:
```yaml
allOf:
  - $ref: flow://relaxed-write-schema
  - $ref: flow://inferred-schema
```

### Step 3: Add Default Values

Add `default` annotations at the top level of the readSchema, alongside `allOf`:

```yaml
allOf:
  - $ref: flow://relaxed-write-schema
  - $ref: flow://inferred-schema
properties:
  status:
    type: string
    default: "pending"
  count:
    type: integer
    default: 0
  is_active:
    type: boolean
    default: true
```

The `properties` block with defaults sits alongside the `allOf`, not inside it.

### Step 4: Publish Changes

```bash
flowctl catalog publish --source flow.yaml
```

## Common Patterns

### Default for Optional String Field

```yaml
allOf:
  - $ref: flow://relaxed-write-schema
  - $ref: flow://inferred-schema
properties:
  category:
    type:
      - string
      - "null"
    default: "uncategorized"
```

Note: Default only applies when field is missing. If value is explicitly `null`, it remains `null`.

### Nullable Primary Key with Default

The most common use case. SQL materializations reject key fields that are nullable unless they have a default. This often happens when the inferred schema doesn't mark the field as `required` (e.g., because it was absent in historical data).

```yaml
allOf:
  - $ref: flow://relaxed-write-schema
  - $ref: flow://inferred-schema
properties:
  year:
    default: 0
```

### Timestamp Default

```yaml
allOf:
  - $ref: flow://relaxed-write-schema
  - $ref: flow://inferred-schema
properties:
  created_at:
    type: string
    format: date-time
    default: "1970-01-01T00:00:00Z"
```

## Handling Explicit NULLs

`default` doesn't replace explicit `null` values, only missing fields. If you can't fix the source data, use a SQL derivation to replace nulls and materialize the derived collection instead:

```yaml
collections:
  tenant/derived/collection:
    schema: schema.yaml      # schema + key for the derived collection
    key: [/id]
    derive:
      using:
        sqlite: {}
      transforms:
        - name: replaceNulls
          source: tenant/source/collection
          shuffle: any
          lambda: SELECT COALESCE($status, 'unknown') AS status, $id AS id;
```

## Troubleshooting

### Default Not Applied

- Check if field is **missing** vs explicitly **null**
- Defaults only apply to missing fields
- Verify default is in **readSchema**, not just writeSchema
- Defaults are only used by materializations — ignored by captures and derivations

### Nullable PK Error in Materialization

```
cannot materialize collection 'X' with nullable key field 'Y' unless it has a default value annotation
```

- Add `default` annotation to the key field in readSchema (alongside `allOf`, not inside it)
- This can happen even if the field looks non-nullable in the current schema — the inferred schema may have seen it as nullable historically
- Alternatives: collection reset (`reset: true`) to re-infer from scratch, or add the field to `required` in the readSchema

### Schema Validation Errors After Adding Default

- Ensure default value matches the field's type
- For typed fields, default must be valid: `default: 0` for integer, not `default: "0"`

### Existing NULL Data Causing Issues

- Defaults don't transform existing null values
- Use a derivation to replace nulls (see "Handling Explicit NULLs" above)
- Or perform a Dataflow reset after fixing source data

## Related Skills

- `schema-field-selection` — Control which nullable fields materialize
- `schema-define-fields` — Define fields in the readSchema (pruned fields, type refinement, etc.). Note: that skill adds new field definitions as a third entry inside `allOf:`, while this skill places `properties:` as a peer of `allOf:`. Both are valid JSON Schema (sibling keywords are AND'd at the same level). The peer-`properties` pattern is convenient for annotation-only changes like `default`; the third-`allOf` pattern is preferred when introducing new field structure.

Wersje

W bazie nie ma innych skilli o nazwie schema-null-defaults.

Migawka bazy z 13.11.2026 · wersja paczki 3d45aacfed64 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 95csharp-nullable-types
    Opisuje typy nullable w C# (referencyjne i wartościowe), adnotacje oraz wzorce obsługi wartości null dla bezpieczeństwa kodu.
  • 90absent-values
    Ujednolica obsługę brakujących wartości: opcjonalnych pól, propsów i kolumn, undefined, null, optional, nullable i default, według zasady Esposter jednej formy braku.
  • 100fp-option-ref
    Podaje skrócone odniesienie do typu Option w fp-ts, przy obsłudze wartości nullable i opcjonalnych danych oraz unikaniu sprawdzania null.
  • 100fp-option-ref
    Podaje skrócone odniesienie do typu Option w fp-ts, przy obsłudze wartości nullable i opcjonalnych danych oraz unikaniu sprawdzania null.
  • 91csharp-nullable-types
    Wspiera typy referencyjne dopuszczające null w C#, wzorce bezpieczeństwa null i strategie migracji.
  • 100dart-null-safety
    Wyjaśnia null safety w Dart: typy dopuszczające null, promocję typów, late, operator ?? i naprawę typowych błędów z null.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.