feat: re-export name mapping

crates/iceberg/src/spec/mapped_fields.rs

@@ -0,0 +1,165 @@
+// 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.
+
+//! Iceberg mapped fields.
+
+use std::collections::HashMap;
+
+use serde::{Deserialize, Serialize};
+
+use crate::spec::MappedField;
+use crate::Error;
+
+/// Utility mapping which contains field names to IDs and
+/// field IDs to the underlying [`MappedField`].
+#[derive(Debug, Serialize, Deserialize, PartialEq, Eq, Clone)]
+pub struct MappedFields {
+    fields: Vec<MappedField>,
+    name_to_id: HashMap<String, i32>,
+    id_to_field: HashMap<i32, MappedField>,
+}
+
+impl MappedFields {
+    /// Create a new [`MappedFields`].
+    ///
+    /// # Errors
+    ///
+    /// This will produce an error if the input fields contain either duplicate
+    /// names or field IDs.
+    pub fn try_new(fields: Vec<MappedField>) -> Result<Self, Error> {
+        let mut name_to_id = HashMap::new();
+        let mut id_to_field = HashMap::new();
+
+        for field in &fields {
+            if let Some(id) = field.field_id() {
+                if id_to_field.contains_key(&id) {
+                    return Err(Error::new(
+                        crate::ErrorKind::DataInvalid,
+                        format!("duplicate id '{id}' is not allowed"),
+                    ));
+                }
+
+                id_to_field.insert(id, field.clone());
+                for name in field.names() {
+                    if name_to_id.contains_key(name) {
+                        return Err(Error::new(
+                            crate::ErrorKind::DataInvalid,
+                            format!("duplicate name '{name}' is not allowed"),
+                        ));
+                    }
+                    name_to_id.insert(name.to_string(), id);
+                }
+            }
+        }
+
+        Ok(Self {
+            fields,
+            name_to_id,
+            id_to_field,
+        })
+    }
+
+    /// Get a reference to the underlying fields.
+    pub fn fields(&self) -> &[MappedField] {
+        &self.fields
+    }
+
+    /// Get a field, by name, returning its ID if it exists, otherwise `None`.
+    pub fn id(&self, field_name: &str) -> Option<i32> {
+        self.name_to_id.get(field_name).copied()
+    }
+
+    /// Get a field, by ID, returning the underlying [`MappedField`] if it exists,
+    /// otherwise `None`.
+    pub fn field(&self, id: i32) -> Option<&MappedField> {
+        self.id_to_field.get(&id)
+    }
+}
+
+#[cfg(test)]
+mod test {
+
+    use pretty_assertions::assert_eq;
+
+    use super::*;
+    use crate::ErrorKind;
+
+    #[test]
+    fn mapped_fields() {
+        let my_fields = vec![
+            MappedField::new(Some(1), vec!["field_one".to_string()], Vec::new()),
+            MappedField::new(
+                Some(2),
+                vec!["field_two".to_string(), "field_foo".to_string()],
+                Vec::new(),
+            ),
+        ];
+
+        let mapped_fields = MappedFields::try_new(my_fields).expect("valid mapped fields for test");
+
+        assert!(
+            mapped_fields.field(1000).is_none(),
+            "Field with ID '1000' was not inserted to the collection"
+        );
+        assert_eq!(
+            *mapped_fields.field(1).unwrap(),
+            MappedField::new(Some(1), vec!["field_one".to_string()], Vec::new()),
+        );
+        assert_eq!(
+            *mapped_fields.field(2).unwrap(),
+            MappedField::new(
+                Some(2),
+                vec!["field_two".to_string(), "field_foo".to_string()],
+                Vec::new(),
+            )
+        );
+
+        assert!(
+            mapped_fields.id("not_exist").is_none(),
+            "Field was not expected to exist in the collection"
+        );
+        assert_eq!(mapped_fields.id("field_two"), Some(2));
+        assert_eq!(
+            mapped_fields.id("field_foo"),
+            Some(2),
+            "Field with another name shares the same ID of '2'"
+        );
+        assert_eq!(mapped_fields.id("field_one"), Some(1));
+    }
+
+    #[test]
+    fn invalid_mapped_fields() {
+        let duplicate_ids = vec![
+            MappedField::new(Some(1), vec!["field_one".to_string()], Vec::new()),
+            MappedField::new(Some(1), vec!["field_two".to_string()], Vec::new()),
+        ];
+
+        assert_eq!(
+            MappedFields::try_new(duplicate_ids).unwrap_err().kind(),
+            ErrorKind::DataInvalid
+        );
+
+        let duplicate_names = vec![
+            MappedField::new(Some(1), vec!["field_one".to_string()], Vec::new()),
+            MappedField::new(Some(2), vec!["field_one".to_string()], Vec::new()),
+        ];
+        assert_eq!(
+            MappedFields::try_new(duplicate_names).unwrap_err().kind(),
+            ErrorKind::DataInvalid
+        );
+    }
+}

crates/iceberg/src/spec/mod.rs

@@ -20,6 +20,7 @@
 mod datatypes;
 mod manifest;
 mod manifest_list;
+mod mapped_fields;
 mod name_mapping;
 mod partition;
 mod schema;
@@ -37,6 +38,8 @@ mod view_version;
 pub use datatypes::*;
 pub use manifest::*;
 pub use manifest_list::*;
+pub use mapped_fields::*;
+pub use name_mapping::*;
 pub use partition::*;
 pub use schema::*;
 pub use snapshot::*;

crates/iceberg/src/spec/name_mapping.rs

@@ -20,11 +20,26 @@
 use serde::{Deserialize, Serialize};
 use serde_with::{serde_as, DefaultOnNull};
 
+/// Property name for name mapping.
+pub const DEFAULT_SCHEMA_NAME_MAPPING: &str = "schema.name-mapping.default";
+
 /// Iceberg fallback field name to ID mapping.
 #[derive(Debug, Serialize, Deserialize, PartialEq, Eq, Clone)]
 #[serde(transparent)]
 pub struct NameMapping {
-    pub root: Vec<MappedField>,
+    root: Vec<MappedField>,
+}
+
+impl NameMapping {
+    /// Create a new [`NameMapping`] given a collection of mapped fields.
+    pub fn new(fields: Vec<MappedField>) -> NameMapping {
+        Self { root: fields }
+    }
+
+    /// Get a reference to fields which are to be mapped from name to field ID.
+    pub fn root(&self) -> &[MappedField] {
+        &self.root
+    }
 }
 
 /// Maps field names to IDs.
@@ -33,12 +48,38 @@ pub struct NameMapping {
 #[serde(rename_all = "kebab-case")]
 pub struct MappedField {
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub field_id: Option<i32>,
-    pub names: Vec<String>,
+    field_id: Option<i32>,
+    names: Vec<String>,
     #[serde(default)]
     #[serde(skip_serializing_if = "Vec::is_empty")]
     #[serde_as(deserialize_as = "DefaultOnNull")]
-    pub fields: Vec<MappedField>,
+    fields: Vec<MappedField>,
+}
+
+impl MappedField {
+    /// Create a new [`MappedField`].
+    pub fn new(field_id: Option<i32>, names: Vec<String>, fields: Vec<MappedField>) -> Self {
+        Self {
+            field_id,
+            names,
+            fields,
+        }
+    }
+
+    /// Iceberg field ID when a field's name is present within `names`.
+    pub fn field_id(&self) -> Option<i32> {
+        self.field_id
+    }
+
+    /// Get a reference to names for a mapped field.
+    pub fn names(&self) -> &[String] {
+        &self.names
+    }
+
+    /// Get a reference to the field mapping for any child fields.
+    pub fn fields(&self) -> &[MappedField] {
+        &self.fields
+    }
 }
 
 #[cfg(test)]