mars/confluence/additions/Oracle_External_Tables_Tolerance_Guide.md

# Oracle External Tables Tolerance Guide

## Podsumowanie Mechanizmów Tolerancji

Oracle External Tables mają zaskakująco wysoką tolerancję na różnice w strukturze plików CSV w porównaniu do definicji tabeli. To może prowadzić do nieoczekiwanych zachowań w systemach enterprise.

## 🎯 Kluczowe Mechanizmy

### 1. **Mapowanie Kolumn Po Nazwach (Nie Po Pozycji)**
```csv
-- Tabela: ID, NAME, STATUS
-- CSV 1: ID,NAME,STATUS           ✅ Standardowa kolejność
-- CSV 2: STATUS,NAME,ID           ✅ Inna kolejność - działa!
-- CSV 3: NAME,ID,STATUS           ✅ Również działa!
```

**Wniosek**: Oracle mapuje po nagłówkach, nie po kolejności kolumn.

### 2. **Brakujące Kolumny = NULL**
```csv
-- Tabela: ID, NAME, STATUS, AMOUNT  
-- CSV: ID,NAME                     ⚠️ STATUS i AMOUNT = NULL!
```

**Niebezpieczeństwo**: Plik z niepełną strukturą zostanie załadowany z NULL-ami.

### 3. **Dodatkowe Kolumny Są Ignorowane**
```csv
-- Tabela: ID, NAME, STATUS
-- CSV: ID,NAME,STATUS,EXTRA1,EXTRA2,BONUS  ✅ Nadmiarowe kolumny ignorowane
```

**Wniosek**: Oracle nie protestuje przeciw dodatkowym danym.

### 4. **Walidacja Typów Danych Jest Egzekwowana**
```csv
-- Tabela: ID(NUMBER), NAME(VARCHAR2), CREATED_DATE(DATE)
-- CSV: "ABC","John","not-a-date"    ❌ Błędy konwersji typów = FAILURE
```

**Wniosek**: Tutaj Oracle jest rygorystyczny!

## 📋 Praktyczne Przykłady

### Plik Demonstracyjny 1: Idealna Zgodność
**demo_perfect_match.csv**
```csv
ID,NAME,DESCRIPTION,CREATED_DATE,STATUS,AMOUNT
1,"Product A","Description A","2024-01-15","ACTIVE",100.50
2,"Product B","Description B","2024-01-16","INACTIVE",200.75
```
**Rezultat**: ✅ 100% sukces

### Plik Demonstracyjny 2: Brakujące Kolumny
**demo_missing_columns.csv**
```csv
ID,WRONG_COLUMN,INVALID_STRUCTURE
1,"Some Data","More Data"
2,"Other Data","Different Data"
```
**Rezultat**: ⚠️ Akceptowany z NULL-ami w brakujących kolumnach!

### Plik Demonstracyjny 3: Dodatkowe Kolumny
**demo_extra_columns.csv**
```csv
ID,NAME,DESCRIPTION,CREATED_DATE,STATUS,AMOUNT,EXTRA1,EXTRA2,BONUS_FIELD
1,"Product A","Description A","2024-01-15","ACTIVE",100.50,"Extra","More","Bonus"
```
**Rezultat**: ✅ Sukces - dodatkowe kolumny ignorowane

### Plik Demonstracyjny 4: Inna Kolejność
**demo_different_order.csv**
```csv
STATUS,AMOUNT,ID,NAME,DESCRIPTION,CREATED_DATE
"ACTIVE",100.50,1,"Product A","Description A","2024-01-15"
```
**Rezultat**: ✅ Sukces - mapowanie po nazwach

### Plik Demonstracyjny 5: Błędne Typy Danych
**demo_data_type_errors.csv**
```csv
ID,NAME,DESCRIPTION,CREATED_DATE,STATUS,AMOUNT
"NOT_NUMBER","Product A","Description A","INVALID_DATE","ACTIVE","NOT_AMOUNT"
```
**Rezultat**: ❌ Failure - błędy konwersji typów

## 🛡️ Implikacje Bezpieczeństwa i Biznesowe

### Problemy
1. **Niekompletne dane akceptowane jako poprawne**
2. **Brak walidacji reguł biznesowych**
3. **Ciche pomijanie dodatkowych informacji**
4. **Nieoczekiwane NULL-e w krytycznych polach**

### Rozwiązania
1. **Walidacja na poziomie aplikacji** - nie polegaj tylko na External Tables
2. **NOT NULL constraints** na krytycznych polach
3. **Niestandardowa procedura VALIDATE_SOURCE_FILE_RECEIVED**
4. **Dokładne monitorowanie statusów plików**

## 🔧 Implementacja w Naszym Systemie

### Dlaczego Naprawa VALIDATION_FAILED Była Krytyczna

Bez poprawnej obsługi wyjątków w `VALIDATE_SOURCE_FILE_RECEIVED`:
- Pliki z niepełną strukturą przechodziły jako "READY_FOR_INGESTION"
- Brak śledzenia problemów walidacji
- Nieszczęsne dane w systemie produkcyjnym

### Nasza Naprawa
```sql
-- PRZED: Nieprawidłowe propagowanie wyjątków
WHEN OTHERS THEN 
    RAISE; -- ❌ Błędne!

-- PO: Prawidłowe zachowanie
WHEN OTHERS THEN
    COMMIT; -- Zapisz status VALIDATION_FAILED
    RAISE ENV_MANAGER.ERR_FILE_VALIDATION_FAILED; -- ✅ Poprawne!
```

### Rozszerzona Walidacja Constraint
```sql
-- Dodano 'VALIDATION_FAILED' do dozwolonych statusów
PROCESSING_STATUS IN ('RECEIVED', 'VALIDATED', 'READY_FOR_INGESTION', 
                     'INGESTED', 'ARCHIVED', 'ARCHIVED_AND_TRASHED', 
                     'ARCHIVED_AND_PURGED', 'VALIDATION_FAILED')
```

## 📊 Testowanie

### Pełny Test Demonstracyjny
Uruchom: `test_EXTERNAL_TABLE_COMPLETE_DEMO.sql`

Ten test pokazuje:
- 6 różnych scenariuszy tolerancji
- Dokładne rezultaty każdego przypadku  
- Praktyczne wnioski dla systemu enterprise

### Oczekiwane Rezultaty
```
✅ Perfect Match      → READY_FOR_INGESTION
⚠️ Missing Columns    → READY_FOR_INGESTION (z NULL-ami!)  
✅ Extra Columns      → READY_FOR_INGESTION
✅ Different Order    → READY_FOR_INGESTION
⚠️ Completely Wrong   → READY_FOR_INGESTION (wszystko NULL!)
❌ Data Type Errors   → VALIDATION_FAILED
```

## 💡 Najważniejsze Wnioski

1. **Oracle External Tables nie są "strict" w kwestii struktury**
2. **Walidacja typów danych działa, walidacja biznesowa - nie**
3. **Konieczne są dodatkowe mechanizmy kontroli jakości**
4. **Monitoring statusów plików jest absolutnie krytyczny**
5. **Nasze problemy z VALIDATION_FAILED były objawem szerszego problemu tolerancji**

## 🚨 Zalecenia Produkcyjne

### Obowiązkowe
- [ ] Zawsze implementuj walidację biznesową w aplikacji
- [ ] Monitoruj wszystkie statusy plików  
- [ ] Testuj z różnymi strukturami plików CSV
- [ ] Dokumentuj wszystkie dozwolone formaty

### Opcjonalne ale Zalecane
- [ ] Dodaj CHECK constraints dla kluczowych pól
- [ ] Implementuj pre-processing walidację nagłówków
- [ ] Stwórz katalog akceptowalnych struktur plików
- [ ] Dodaj alerty na nieoczekiwane NULL-e

---

*Ten dokument powstał w wyniku odkrycia i naprawy krytycznego błędu w procedurze `PROCESS_SOURCE_FILE` oraz dogłębnego zbadania mechanizmów tolerancji Oracle External Tables.*