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)

-- 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

-- 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

-- 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

-- 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

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

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

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

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

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

-- 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

-- Dodano 'VALIDATION_FAILED' do dozwolonych statusów
PROCESSING_STATUS IN ('RECEIVED', 'VALIDATED', 'READY_FOR_INGESTION', 
                     'INGESTED', 'ARCHIVED', '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.