feat(rust/sedona-raster-gdal): add RS_MetaData (#833)

## Summary
- add `RS_MetaData` backed by the GDAL dataset provider
- expose raster dimensions, transform, srid, band count, and GDAL block size metadata
- keep the change limited to the incremental metadata surface on top of the current GDAL raster work

## Dependency
- Depends on #831 (`RS_FromPath`)
- This branch currently includes the parent `RS_FromPath` commit because GitHub upstream PRs cannot target a fork-only base branch.
- Please review/merge this after #831, or compare this PR commit-by-commit with that dependency in mind.

## Testing
- `cargo test -p sedona-raster-gdal`
- `cargo clippy -p sedona-raster-gdal -- -D warnings`
- `cargo test -p sedona-gdal`

Author: Kontinuation

Cargo.lock

@@ -0,0 +1,53 @@
+---
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+title: RS_MetaData
+description: Returns raster metadata as a struct.
+kernels:
+  - returns: struct
+    args: [raster]
+---
+
+## Description
+
+`RS_MetaData()` returns a struct containing:
+
+- `upperLeftX`, `upperLeftY`: origin of the raster geotransform
+- `gridWidth`, `gridHeight`: raster dimensions in pixels
+- `scaleX`, `scaleY`: pixel scale
+- `skewX`, `skewY`: geotransform skew terms
+- `srid`: raster SRID if available, otherwise `0`
+- `numSampleDimensions`: band count
+- `tileWidth`, `tileHeight`: GDAL block size derived tile dimensions
+
+For rasters with no bands, `tileWidth` and `tileHeight` are `0`.
+
+## Examples
+
+```sql
+SELECT RS_MetaData(RS_Example());
+```
+
+```sql
+SELECT meta."gridWidth", meta."gridHeight"
+FROM (
+  SELECT RS_MetaData(
+    RS_FromPath('https://download.osgeo.org/geotiff/samples/gdal_eg/cea.tif')
+  ) AS meta
+) q;
+```

docs/reference/sql/rs_metadata.qmd

@@ -43,6 +43,7 @@ sedona-expr = { workspace = true }
 sedona-functions = { workspace = true }
 sedona-gdal = { workspace = true }
 sedona-raster = { workspace = true }
+sedona-raster-functions = { workspace = true }
 sedona-schema = { workspace = true }
 tokio = { workspace = true }
 
@@ -57,3 +58,8 @@ tokio = { workspace = true, features = ["rt-multi-thread", "macros"] }
 harness = false
 name = "rs_frompath"
 path = "benches/rs_frompath.rs"
+
+[[bench]]
+harness = false
+name = "rs_metadata"
+path = "benches/rs_metadata.rs"

rust/sedona-raster-gdal/Cargo.toml

@@ -0,0 +1,99 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Benchmarks for RS_MetaData UDF.
+
+use std::{hint::black_box, sync::Arc};
+
+use arrow_array::{ArrayRef, StringArray};
+use arrow_schema::DataType;
+use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};
+use datafusion_expr::ScalarUDF;
+use sedona_schema::datatypes::{SedonaType, RASTER};
+use sedona_testing::{data::test_raster, testers::ScalarUdfTester};
+
+const SMALL_RASTER_FIXTURES: &[&str] = &[
+    "test1.tiff",
+    "test2.tif",
+    "test3.tif",
+    "test4.tiff",
+    "test5.tiff",
+];
+
+fn raster_path_array(names: &[&str], rows: usize) -> ArrayRef {
+    assert!(
+        !names.is_empty(),
+        "benchmark fixture list must not be empty"
+    );
+
+    let paths = names
+        .iter()
+        .map(|name| test_raster(name).unwrap())
+        .collect::<Vec<_>>();
+
+    let values = (0..rows)
+        .map(|index| paths[index % paths.len()].as_str())
+        .collect::<Vec<_>>();
+
+    Arc::new(StringArray::from(values))
+}
+
+fn build_raster_input(names: &[&str], rows: usize) -> ArrayRef {
+    let frompath_udf: ScalarUDF = sedona_raster_gdal::rs_frompath_udf().into();
+    let frompath_tester =
+        ScalarUdfTester::new(frompath_udf, vec![SedonaType::Arrow(DataType::Utf8)]);
+    frompath_tester
+        .invoke_array(raster_path_array(names, rows))
+        .unwrap()
+}
+
+fn bench_rs_metadata(c: &mut Criterion) {
+    let udf: ScalarUDF = sedona_raster_gdal::rs_metadata_udf().into();
+    let tester = ScalarUdfTester::new(udf, vec![RASTER]);
+
+    let single_small = build_raster_input(&["test4.tiff"], 1);
+    let mixed_small = build_raster_input(SMALL_RASTER_FIXTURES, SMALL_RASTER_FIXTURES.len());
+    let batched_small = build_raster_input(SMALL_RASTER_FIXTURES, 256);
+
+    let mut group = c.benchmark_group("rs_metadata");
+
+    group.throughput(Throughput::Elements(single_small.len() as u64));
+    group.bench_with_input(
+        BenchmarkId::new("fixtures", "single_small"),
+        &single_small,
+        |b, input| b.iter(|| black_box(tester.invoke_array(input.clone()).unwrap())),
+    );
+
+    group.throughput(Throughput::Elements(mixed_small.len() as u64));
+    group.bench_with_input(
+        BenchmarkId::new("fixtures", "mixed_small"),
+        &mixed_small,
+        |b, input| b.iter(|| black_box(tester.invoke_array(input.clone()).unwrap())),
+    );
+
+    group.throughput(Throughput::Elements(batched_small.len() as u64));
+    group.bench_with_input(
+        BenchmarkId::new("fixtures", "batched_small"),
+        &batched_small,
+        |b, input| b.iter(|| black_box(tester.invoke_array(input.clone()).unwrap())),
+    );
+
+    group.finish();
+}
+
+criterion_group!(benches, bench_rs_metadata);
+criterion_main!(benches);

rust/sedona-raster-gdal/benches/rs_metadata.rs

@@ -34,6 +34,7 @@ mod gdal_dataset_provider;
 
 mod raster_loader;
 mod rs_frompath;
+mod rs_metadata;
 mod source_uri;
 mod utils;
 
@@ -44,6 +45,7 @@ pub use gdal_common::{
 };
 pub use raster_loader::{GdalLoader, GDAL_FORMAT};
 pub use rs_frompath::rs_frompath_udf;
+pub use rs_metadata::rs_metadata_udf;
 pub use utils::{
     append_as_indb_raster, append_as_outdb_raster, append_nd_from_dataset, dataset_to_indb_raster,
     gdal_dataset_to_nd_raster,

rust/sedona-raster-gdal/src/lib.rs

@@ -21,5 +21,6 @@ use sedona_expr::function_set::FunctionSet;
 pub fn default_function_set() -> FunctionSet {
     let mut function_set = FunctionSet::new();
     function_set.insert_scalar_udf(crate::rs_frompath::rs_frompath_udf());
+    function_set.insert_scalar_udf(crate::rs_metadata::rs_metadata_udf());
     function_set
 }