Merge branch 'develop'

2026-02-11 21:32:47 +01:00
parent 26aba08759 f8213b76ab
commit f4e9fb9cb2
27 changed files with 8496 additions and 141 deletions
--- a/confluence/additions/DATA_EXPORTER_pMaxFileSize_Analysis.md
+++ b/confluence/additions/DATA_EXPORTER_pMaxFileSize_Analysis.md
@@ -0,0 +1,205 @@
+# Analiza parametru pMaxFileSize dla DATA_EXPORTER.EXPORT_TABLE_DATA_TO_CSV_BY_DATE
+
+## Pytanie
+Jaki maksymalnie można ustawić parametr `pMaxFileSize` przy `pParallelDegree => 1` w procedurze `CT_MRDS.DATA_EXPORTER.EXPORT_TABLE_DATA_TO_CSV_BY_DATE`?
+
+## Odpowiedź
+
+### Limity Oracle DBMS_CLOUD.EXPORT_DATA
+
+**UWAGA**: Komentarz w kodzie źródłowym (`DATA_EXPORTER.pkb`, linia 444-449) zawiera **BŁĘDNĄ** informację o maksymalnym limicie 1GB.
+
+```sql
+-- Oracle maxfilesize: min 10MB (10485760), max 1GB (1073741824), default 10MB  -- NIEPRAWIDŁOWE!
+-- NOTE: maxfilesize must be NUMBER (bytes), not string like '1000M'
+-- Using 100MB (104857600) to avoid PGA memory issues with large files
+```
+
+**Rzeczywiste limity Oracle** (zweryfikowane testami 2026-02-05):
+- **Minimum**: 10 MB (10,485,760 bajtów)
+- **Maksimum**: **4,294,967,295 bajtów** (4 GB - 1 bajt) = **2^32 - 1** (unsigned 32-bit integer max)
+- **Wartość = 4GB** (4,294,967,296): ORA-01426 numeric overflow
+
+### Test Environment
+
+- **Oracle Database**: Oracle AI Database 26ai Enterprise Edition Release 23.26.1.1.0
+- **PGA Configuration**:
+  - pga_aggregate_target: 3000M (3GB)
+  - pga_aggregate_limit: 6000M (6GB) - hard limit
+- **Test Dataset**: OU_CSDB.LEGACY_DEBT table (1,014,078 rows)
+- **OCI Object Storage**: eu-frankfurt-1 region
+
+### Wartości graniczne
+
+| Parametr | Wartość (bajty) | Wartość (MB/GB) | Status |
+|----------|----------------|-----------------|---------|
+| **Minimum** | 10,485,760 | 10 MB | Oracle minimum |
+| **Aktualny standard** | 104,857,600 | 100 MB | Używane w kodzie |
+| **Zalecane bezpieczne (parallel)** | 524,288,000 | 500 MB | Dla pParallelDegree > 1 |
+| **Zalecane bezpieczne (sequential)** | 1,073,741,824 | 1 GB | Dla pParallelDegree = 1 |
+| **Maksimum Oracle** | **4,294,967,295** | **~4 GB** | **2^32 - 1 (unsigned 32-bit max)** |
+| **Błąd numeric overflow** | 4,294,967,296 | 4 GB | ORA-01426 (dokładnie 2^32) |
+
+### Odpowiedź na pytanie
+
+**Maksymalna wartość pMaxFileSize przy pParallelDegree => 1:**
+```sql
+pMaxFileSize => 1073741824  -- 1 GB (1,073,741,824 bajtów)
+```
+
+## Przykład użycia z maksymalną wartością
+
+```sql
+BEGIN
+    CT_MRDS.DATA_EXPORTER.EXPORT_TABLE_DATA_TO_CSV_BY_DATE(
+        pSchemaName => 'OU_CSDB',
+        pTableName => 'LEGACY_DEBT',
+        pKeyColumnName => 'A_ETL_LOAD_SET_FK',
+        pBucketArea => 'DATA',
+        pFolderName => 'ODS/CSDB/CSDB_DEBT',
+        pMinDate => DATE '2024-01-01',
+        pMaxDate => SYSDATE,
+        pParallelDegree => 1,              -- Sequential processing
+        pTemplateTableName => 'CT_ET_TEMPLATES.CSDB_DEBT',
+        pMaxFileSize => 1073741824         -- 1GB - MAXIMUM możliwa wartość
+    );
+END;
+/
+```
+
+## Rekomendacje
+
+### Dla pParallelDegree => 1 (przetwarzanie sekwencyjne)
+
+1. **Maksimum bezwzględne**: 1 GB (1,073,741,824 bajtów)
+   - To jest twardy limit Oracle DBMS_CLOUD.EXPORT_DATA
+   - Wartości powyżej 1GB spowodują błąd Oracle
+
+2. **Zalecane wartości w zależności od scenariusza**:
+   - **Małe tabele** (< 1M rekordów): 100 MB (104,857,600) - aktualny standard
+   - **Średnie tabele** (1-10M rekordów): 250 MB (262,144,000)
+   - **Duże tabele** (> 10M rekordów): 500 MB (524,288,000)
+   - **Bardzo duże tabele** z dużą ilością RAM: 1 GB (1,073,741,824)
+
+3. **Kwestie pamięciowe (PGA)**:
+   - W komentarzu kodu widoczne jest ostrzeżenie: "avoid PGA memory issues"
+   - Przy `pParallelDegree => 1` (brak równoległości), ryzyko błędu ORA-04036 jest niższe
+   - Można bezpiecznie używać wyższych wartości niż przy przetwarzaniu równoległym
+
+### Dla pParallelDegree > 1 (przetwarzanie równoległe)
+
+- **Maksimum techniczne**: nadal 1 GB
+- **Zalecane**: 100-200 MB z powodu pamięci PGA
+- **Aktualny standard**: 100 MB (bezpieczna wartość)
+
+## Różnice względem przetwarzania równoległego
+
+| Aspekt | pParallelDegree = 1 | pParallelDegree > 1 |
+|--------|---------------------|---------------------|
+| **Maksimum Oracle** | 1 GB | 1 GB |
+| **Zalecane max** | 500 MB - 1 GB | 100-200 MB |
+| **Ryzyko ORA-04036** | Niskie | Wysokie (wiele procesów) |
+| **Użycie PGA** | Pojedynczy proces | Wielokrotne procesy |
+
+## Skrypty testowe
+
+Przygotowano dwa skrypty testowe:
+
+### 1. Pełny test (7 scenariuszy)
+**Plik**: `MARS_Packages/tests/test_maxfilesize_parameter.sql`
+- Test z wartościami: 10MB, 100MB, 250MB, 500MB, 750MB, 1GB, 1.5GB
+- Automatyczne czyszczenie testowych plików
+- Szczegółowe logowanie wyników
+
+### 2. Szybki test (maksimum)
+**Plik**: `MARS_Packages/tests/test_maxfilesize_quick.sql`
+- Jednorazowy test z maksymalną wartością 1GB
+- Szybka weryfikacja poprawności konfiguracji
+
+### Uruchomienie testów
+
+```powershell
+# Pełny test wszystkich wartości
+Get-Content "MARS_Packages\tests\test_maxfilesize_parameter.sql" | sql "CT_MRDS/Cloudpass#34@ggmichalski_high"
+
+# Szybki test maksymalnej wartości
+Get-Content "MARS_Packages\tests\test_maxfilesize_quick.sql" | sql "CT_MRDS/Cloudpass#34@ggmichalski_high"
+```
+
+## Wnioski (zaktualizowane 2026-02-05)
+
+1. **Maksymalna wartość Oracle** dla `pMaxFileSize` wynosi **4,294,967,295 bajtów** (4 GB - 1 bajt)
+   - To jest **2^32 - 1** = maksymalna wartość unsigned 32-bit integer
+   - Wartość >= 4,294,967,296 (dokładnie 4GB) powoduje ORA-01426 numeric overflow
+   - **Komentarz w kodzie źródłowym o limicie 1GB jest NIEPRAWIDŁOWY**
+
+2. **Zalecana wartość dla pParallelDegree = 1** (sequential): **1-2 GB**
+   - Niskie ry~4GB można używać dla bardzo dużych tabel (teoretycznie)cyjnym
+   - Maksimum 3GB można używać dla bardzo dużych tabel
+
+3. **Zalecana wartość dla pParallelDegree > 1** (parallel): **100-500 MB**
+   - Wysokie ryzyko ORA-04036 przy wielu wątkach i dużych wartościach
+   - Aktualny standard 100MB jest bezpieczny ale konserwatywny
+
+4. **Weryfikacja testowa** (2026-02-05):
+   - 1GB (1,073,741,824): ✅ DZIAŁA
+   - 2GB (2,147,483,648): ✅ DZIAŁA 
+   - 3GB (3,221,225,472): ✅ DZIAŁA
+   - 3.5GB (3,758,096,384): ✅ DZIAŁA
+   - 3.9GB (4,187,593,113): ✅ DZIAŁA
+   - 3.99GB (4,284,481,126): ✅ DZIAŁA
+   - **4GB - 1 bajt (4,294,967,295)**: ✅ DZIAŁA - **MAKSIMUM ORACLE** (2^32 - 1)
+   - **4GB (4,294,967,296)**: ❌ ORA-01426 numeric overflow (2^32)
+   - 5GB+: ❌ ORA-01426 numeric overflow
+
+5. **Test z pojedynczym wątkiem** (2026-02-05):
+   - pMaxFileSize = 4,294,967,295, pParallelDegree = 1, 60 partycji
+   - Result: ❌ ORA-04036 (PGA memory exceeded - limit 6GB)
+   - Wniosek: Parametr jest akceptowany, ale sekwencyjne przetwarzanie wielu partycji przekracza limit PGA
+   - **Dla 60+ partycji używaj pParallelDegree=4 zamiast 1**
+
+## Kod źródłowy - fragment kluczowy
+
+Z pliku `DATA_EXPORTER.pkb`, procedura `EXPORT_SINGLE_PARTITION`:
+
+```sql
+-- Use json_object() for CSV export with maxfilesize in bytes (Oracle requirement)
+-- Oracle maxfilesize: min 10MB (10485760), max 1GB (1073741824), default 10MB
+-- NOTE: maxfilesize must be NUMBER (bytes), not string like '1000M'
+-- Using 100MB (104857600) to avoid PGA memory issues with large files
+DBMS_CLOUD.EXPORT_DATA(
+    credential_name => pCredentialName,
+    file_uri_list   => vUri,
+    query           => vQuery,
+    format          => json_object(
+        'type' VALUE 'CSV',
+        'header' VALUE true,
+        'quote' VALUE CHR(34),
+        'delimiter' VALUE ',',
+        'escape' VALUE true,
+        'recorddelimiter' VALUE CHR(13)||CHR(10),
+        'maxfilesize' VALUE pMaxFileSize  -- Dynamic maxfilesize in bytes
+    )
+);
+```
+ (1,073,741,824): ✅ Sukces
+- Test 2GB (2,147,483,648): ✅ Sukces - komentarz w kodzie BŁĘDNY
+- Test 3GB (3,221,225,472): ✅ Sukces
+- Test 3.5GB (3,758,096,384): ✅ Sukces
+- Test 3.75GB (4,026,531,840): ✅ Sukces
+- Test 3.9GB (4,187,593,113): ✅ Sukces
+- Test 3.99GB (4,284,481,126): ✅ Sukces
+- Test **4GB - 1 bajt (4,294,967,295)**: ✅ Sukces - **MAKSIMUM = 2^32 - 1**
+- Test 4GB (4,294,967,296): ❌ ORA-01426 numeric overflow (dokładnie 2^32)
+- Test 5GB+: ❌ ORA-01426 numeric overflow
+- Test **4GB-1 + parallel=1 + 60 partycji**: ❌ ORA-04036 PGA memory exceeded
+
+**Konkluzja**: Komentarz w `DATA_EXPORTER.pkb` o maksymalnym limicie 1GB był nieprawidłowy. Rzeczywiste maksimum Oracle DBMS_CLOUD.EXPORT_DATA to **4,294,967,295 bajtów** (4 GB - 1 bajt), co odpowiada maksymalnej wartości **unsigned 32-bit integer (2^32 - 1)**. Jednakże, **w środowisku Autonomous Database z limitami PGA** (pga_aggregate_limit=6GB), sekwencyjne przetwarzanie dużej liczby partycji (60+) może przekroczyć limit pamięci nawet z poprawną wartością parametru
+- Test 3GB: ✅ Sukces - rzeczywiste maksimum Oracle
+- Test 4GB: ❌ ORA-01426 numeric overflow
+- Test 5GB+: ❌ ORA-01426 numeric overflow
+
+**Konkluzja**: Komentarz w `DATA_EXPORTER.pkb` o maksymalnym limicie 1GB był nieprawidłowy. Rzeczywiste maksimum Oracle DBMS_CLOUD.EXPORT_DATA to **3 GB**.
+
+### 2026-02-04 - Analiza początkowa
+Pierwsza wersja dokumentacji oparta na komentarzach w kodzie źródłowym.
--- a/confluence/additions/pMaxFileSize_Final_Summary.md
+++ b/confluence/additions/pMaxFileSize_Final_Summary.md
@@ -0,0 +1,135 @@
+# pMaxFileSize Testing - Final Summary
+
+## Objective
+Find the maximum practical value for `pMaxFileSize` parameter in DATA_EXPORTER package.
+
+## Test Results
+
+### Successful Tests
+
+#### Test 1: pMaxFileSize=400MB with pParallelDegree=12
+- **Data Volume**: 240x multiplication (~6.24M rows, 4.05GB)
+- **Duration**: 7m 51s
+- **Files Generated**: 12 files (11×400MB + 1×394.46MB = 4.68GB total)
+- **Status**: ✅ SUCCESS
+- **Key Finding**: File splitting works perfectly at 400MB limit
+
+#### Test 2: pMaxFileSize=1GB with pParallelDegree=10
+- **Data Volume**: 300x multiplication (~7.8M rows, 5.07GB)
+- **Duration**: 9m 47s
+- **Files Generated**: 6 files (5×1GB + 1×873.11MB = 5.85GB total)
+- **Status**: ✅ SUCCESS
+- **Key Finding**: 1GB files work with moderate parallelism
+
+### Failed Tests
+
+#### Test 3: pMaxFileSize=400MB with pParallelDegree=16
+- **Error**: ORA-04036 PGA exceeded
+- **Conclusion**: Too many concurrent threads (16×78 partitions)
+
+#### Test 4: pMaxFileSize=1GB with pParallelDegree=1
+- **Data Attempts**: 320x, 300x, 240x, 200x
+- **Error**: ORA-65114 space usage in container too high
+- **Conclusion**: Large data volumes exceed Autonomous DB storage limits for temp tables
+
+## Key Discoveries
+
+### 1. pMaxFileSize ≠ PGA Buffer Size
+**CRITICAL**: File size limit does NOT create proportional memory buffers.
+- ✅ `pParallelDegree=10 × pMaxFileSize=1GB` = SUCCESS
+- ❌ `pParallelDegree=16 × pMaxFileSize=400MB` = FAILURE
+
+**Conclusion**: Number of concurrent threads (parallelism) impacts PGA more than individual file size.
+
+### 2. Parallelism is Primary PGA Driver
+- Higher parallelism = more PGA consumption
+- Lower parallelism allows larger file sizes
+- Sweet spot: pParallelDegree=10-12 for large exports
+
+### 3. Storage Container Limits
+Autonomous Database has strict storage limits for temporary tables:
+- 240x multiplication succeeded with pParallelDegree=12
+- Same 240x multiplication FAILED when tested alone (container cleanup needed)
+- 300x+ multiplication consistently hits ORA-65114 storage limit
+
+### 4. File Splitting Mechanism Works Perfectly
+- Files split at exact pMaxFileSize limit (within ±0.01MB)
+- Example: 11 files @ 400.00MB + 1 file @ 394.46MB
+- Hive-style partitioning maintained correctly
+
+## Theoretical Maximum
+
+### From Oracle Documentation
+- **Maximum file size**: 2^32-1 bytes (~4GB) - limited by VARCHAR2 file naming
+- **Practical limit**: Depends on PGA configuration and data volume
+
+### From Testing
+| pParallelDegree | pMaxFileSize | Status | Notes |
+|-----------------|--------------|---------|-------|
+| 16 | 400MB | ❌ | PGA exceeded |
+| 12 | 400MB | ✅ | Perfect |
+| 10 | 1GB | ✅ | Perfect |
+| 1 | 1GB | ❌ | Data volume too large for temp table creation |
+
+**Tested Maximum**: **1GB with pParallelDegree=10**
+
+**Untested Range**: 1GB-4GB (blocked by storage limits for test data creation)
+
+## Production Recommendations
+
+### Conservative (Safest)
+```sql
+pParallelDegree => 8
+pMaxFileSize => 209715200  -- 200MB
+```
+- Minimal PGA risk
+- Fast enough for most use cases
+- Works with high partition counts
+
+### Balanced (Recommended)
+```sql
+pParallelDegree => 10
+pMaxFileSize => 419430400  -- 400MB
+```
+- Good balance of speed and safety
+- Proven successful in testing
+- Handles large datasets well
+
+### Performance (Maximum Tested)
+```sql
+pParallelDegree => 10
+pMaxFileSize => 1073741824  -- 1GB
+```
+- Maximum tested configuration
+- Best for very large single-partition exports
+- Requires monitoring of PGA usage
+
+### NOT Recommended
+```sql
+pParallelDegree > 12  -- Risks PGA exceeded errors
+pMaxFileSize > 1GB     -- Untested, may hit limits
+```
+
+## Technical Constraints
+
+### PGA Configuration (ggmichalski database)
+- `pga_aggregate_target`: 3GB (soft limit)
+- `pga_aggregate_limit`: 6GB (hard limit - triggers ORA-04036)
+
+### Query Processing PGA Usage
+- Large datasets with DATE transformations consume significant PGA
+- Query processing memory usage is independent of output file size
+- Example: 8.3M rows with TO_CHAR() operations exceeded 6GB PGA
+
+### Storage Limits
+- ORA-65114: Space usage in container too high
+- Affects temp table creation with large UNION ALL chains
+- Cleanup required between large test data creates
+
+## Conclusion
+
+**Maximum Practical pMaxFileSize**: **1GB** (with pParallelDegree=10)
+
+**Optimal Production Configuration**: **400MB** (with pParallelDegree=10-12)
+
+**Key Insight**: **Parallelism matters more than file size** for PGA management. Lower parallelism allows larger files without hitting memory limits.