feat(core): Add support for _file column (#1824)

## Which issue does this PR close?


- Closes #1766.

## What changes are included in this PR?

Integrates virtual field handling for the `_file` metadata column into
`RecordBatchTransformer` using a pre-computed constants map, eliminating
post-processing and duplicate lookups.

## Key Changes

**New `metadata_columns.rs` module**: Centralized utilities for metadata
columns
- Constants: `RESERVED_FIELD_ID_FILE`, `RESERVED_COL_NAME_FILE`
- Helper functions: `get_metadata_column_name()`,
`get_metadata_field_id()`, `is_metadata_field()`,
`is_metadata_column_name()`

**Enhanced `RecordBatchTransformer`**:
- Added `constant_fields: HashMap<i32, (DataType, PrimitiveLiteral)>` -
pre-computed during initialization
- New `with_constant()` method - computes Arrow type once during setup
- Updated to use pre-computed types and values (avoids duplicate
lookups)
- Handles `DataType::RunEndEncoded` for constant strings (memory
efficient)

**Simplified `reader.rs`**:
- Pass full `project_field_ids` (including virtual) to
RecordBatchTransformer
- Single `with_constant()` call to register `_file` column
- Removed post-processing loop

**Updated `scan/mod.rs`**:
- Use `is_metadata_column_name()` and `get_metadata_field_id()` instead
of hardcoded checks
## Are these changes tested?

Yes, comprehensive tests have been added to verify the functionality:

### New Tests (7 tests added)

#### Table Scan API Tests (7 tests)

1. **`test_select_with_file_column`** - Verifies basic functionality of
selecting `_file` with regular columns
2. **`test_select_file_column_position`** - Verifies column ordering is
preserved
3. **`test_select_file_column_only`** - Tests selecting only the `_file`
column
4. **`test_file_column_with_multiple_files`** - Tests multiple data
files scenario
5. **`test_file_column_at_start`** - Tests `_file` at position 0
6. **`test_file_column_at_end`** - Tests `_file` at the last position
7. **`test_select_with_repeated_column_names`** - Tests repeated column
selection

Author: gbrgr

crates/iceberg/src/arrow/reader.rs

@@ -54,6 +54,7 @@ use crate::expr::visitors::page_index_evaluator::PageIndexEvaluator;
 use crate::expr::visitors::row_group_metrics_evaluator::RowGroupMetricsEvaluator;
 use crate::expr::{BoundPredicate, BoundReference};
 use crate::io::{FileIO, FileMetadata, FileRead};
+use crate::metadata_columns::{RESERVED_FIELD_ID_FILE, is_metadata_field};
 use crate::scan::{ArrowRecordBatchStream, FileScanTask, FileScanTaskStream};
 use crate::spec::{Datum, NameMapping, NestedField, PrimitiveType, Schema, Type};
 use crate::utils::available_parallelism;
@@ -250,12 +251,20 @@ impl ArrowReader {
             initial_stream_builder
         };
 
+        // Filter out metadata fields for Parquet projection (they don't exist in files)
+        let project_field_ids_without_metadata: Vec<i32> = task
+            .project_field_ids
+            .iter()
+            .filter(|&&id| !is_metadata_field(id))
+            .copied()
+            .collect();
+
         // Create projection mask based on field IDs
         // - If file has embedded IDs: field-ID-based projection (missing_field_ids=false)
         // - If name mapping applied: field-ID-based projection (missing_field_ids=true but IDs now match)
         // - If fallback IDs: position-based projection (missing_field_ids=true)
         let projection_mask = Self::get_arrow_projection_mask(
-            &task.project_field_ids,
+            &project_field_ids_without_metadata,
             &task.schema,
             record_batch_stream_builder.parquet_schema(),
             record_batch_stream_builder.schema(),
@@ -266,16 +275,23 @@ impl ArrowReader {
             record_batch_stream_builder.with_projection(projection_mask.clone());
 
         // RecordBatchTransformer performs any transformations required on the RecordBatches
-        // that come back from the file, such as type promotion, default column insertion
-        // and column re-ordering.
+        // that come back from the file, such as type promotion, default column insertion,
+        // column re-ordering, partition constants, and virtual field addition (like _file)
         let mut record_batch_transformer_builder =
             RecordBatchTransformerBuilder::new(task.schema_ref(), task.project_field_ids());
 
+        // Add the _file metadata column if it's in the projected fields
+        if task.project_field_ids().contains(&RESERVED_FIELD_ID_FILE) {
+            let file_datum = Datum::string(task.data_file_path.clone());
+            record_batch_transformer_builder =
+                record_batch_transformer_builder.with_constant(RESERVED_FIELD_ID_FILE, file_datum);
+        }
+
         if let (Some(partition_spec), Some(partition_data)) =
             (task.partition_spec.clone(), task.partition.clone())
         {
             record_batch_transformer_builder =
-                record_batch_transformer_builder.with_partition(partition_spec, partition_data);
+                record_batch_transformer_builder.with_partition(partition_spec, partition_data)?;
         }
 
         let mut record_batch_transformer = record_batch_transformer_builder.build();
@@ -416,7 +432,10 @@ impl ArrowReader {
             record_batch_stream_builder
                 .build()?
                 .map(move |batch| match batch {
-                    Ok(batch) => record_batch_transformer.process_record_batch(batch),
+                    Ok(batch) => {
+                        // Process the record batch (type promotion, column reordering, virtual fields, etc.)
+                        record_batch_transformer.process_record_batch(batch)
+                    }
                     Err(err) => Err(err.into()),
                 });