feat: implement case-insensitive support

crates/lance-graph/src/case_insensitive.rs

@@ -0,0 +1,377 @@
+//! Case-insensitive string utilities
+//!
+//! We use case-insensitive identifiers throughout to provide a SQL-like,
+//! forgiving user experience.
+//!
+//! All identifiers (labels, properties, relationships) are case-insensitive,
+//! meaning `Person`, `PERSON`, and `person` all refer to the same entity.
+
+use std::collections::HashMap;
+use std::hash::{Hash, Hasher};
+
+/// A string wrapper that performs case-insensitive comparisons and hashing.
+///
+/// Internally stores the lowercase version for efficient comparison.
+/// This is the core building block for case-insensitive identifier handling.
+///
+/// # Examples
+///
+/// ```
+/// use lance_graph::case_insensitive::CaseInsensitiveStr;
+///
+/// let a = CaseInsensitiveStr::new("Person");
+/// let b = CaseInsensitiveStr::new("person");
+/// let c = CaseInsensitiveStr::new("PERSON");
+///
+/// assert_eq!(a, b);
+/// assert_eq!(b, c);
+/// ```
+#[derive(Debug, Clone)]
+pub struct CaseInsensitiveStr {
+    normalized: String, // Always lowercase
+}
+
+impl CaseInsensitiveStr {
+    /// Create a new case-insensitive string from any string-like type.
+    ///
+    /// The input is immediately converted to lowercase for storage.
+    pub fn new(s: impl Into<String>) -> Self {
+        Self {
+            normalized: s.into().to_lowercase(),
+        }
+    }
+
+    /// Get the normalized (lowercase) string representation.
+    pub fn as_str(&self) -> &str {
+        &self.normalized
+    }
+}
+
+impl PartialEq for CaseInsensitiveStr {
+    fn eq(&self, other: &Self) -> bool {
+        self.normalized == other.normalized
+    }
+}
+
+impl Eq for CaseInsensitiveStr {}
+
+impl Hash for CaseInsensitiveStr {
+    fn hash<H: Hasher>(&self, state: &mut H) {
+        self.normalized.hash(state);
+    }
+}
+
+impl From<&str> for CaseInsensitiveStr {
+    fn from(s: &str) -> Self {
+        Self::new(s)
+    }
+}
+
+impl From<String> for CaseInsensitiveStr {
+    fn from(s: String) -> Self {
+        Self::new(s)
+    }
+}
+
+impl AsRef<str> for CaseInsensitiveStr {
+    fn as_ref(&self) -> &str {
+        &self.normalized
+    }
+}
+
+/// Case-insensitive HashMap type alias for convenience
+///
+/// Use this type when you need a HashMap that performs case-insensitive
+/// key lookups throughout the system.
+pub type CaseInsensitiveMap<V> = HashMap<CaseInsensitiveStr, V>;
+
+/// Create a qualified column name for internal DataFusion operations.
+///
+/// Returns format: `alias__property` (e.g., "p__name").
+/// Both alias and property are normalized to lowercase for case-insensitive behavior.
+///
+/// This is the central utility for creating qualified column names throughout
+/// the codebase. All join keys, scan projections, and expression translations
+/// should use this function to ensure consistent case-insensitive behavior.
+///
+/// # Examples
+///
+/// ```
+/// use lance_graph::case_insensitive::qualify_column;
+///
+/// assert_eq!(qualify_column("Person", "Name"), "person__name");
+/// assert_eq!(qualify_column("p", "fullName"), "p__fullname");
+/// ```
+#[inline]
+pub fn qualify_column(alias: &str, property: &str) -> String {
+    format!("{}__{}", alias.to_lowercase(), property.to_lowercase())
+}
+
+/// Helper trait for case-insensitive lookups on standard HashMap<String, V>
+///
+/// This trait provides extension methods for performing case-insensitive
+/// lookups on existing String-keyed HashMaps without requiring migration
+/// to CaseInsensitiveMap.
+///
+/// # Performance
+///
+/// - **Best case**: O(1) when exact case matches (uses HashMap's fast path)
+/// - **Worst case**: O(n) when case differs (iterates all keys to find match)
+///
+/// **For hot paths** (executed per-row or frequently), store normalized (lowercase)
+/// keys in the HashMap to guarantee O(1) lookups. This trait is most appropriate for:
+/// - Small HashMaps (< 100 entries)
+/// - Cold paths (planning phase, executed once per query)
+/// - Cases where preserving original case in keys is important
+///
+/// See `SemanticAnalyzer::variables` for an example of the optimized pattern where
+/// keys are normalized to lowercase on insertion, ensuring all lookups hit the O(1) fast path.
+///
+/// # Examples
+///
+/// ```
+/// use std::collections::HashMap;
+/// use lance_graph::case_insensitive::CaseInsensitiveLookup;
+///
+/// let mut map = HashMap::new();
+/// map.insert("Person".to_string(), 1);
+///
+/// assert_eq!(map.get_ci("person"), Some(&1));
+/// assert_eq!(map.get_ci("PERSON"), Some(&1));
+/// assert_eq!(map.get_ci("Person"), Some(&1));
+/// ```
+pub trait CaseInsensitiveLookup<V> {
+    /// Get a value with case-insensitive key lookup.
+    ///
+    /// Returns `Some(&V)` if a key matches (case-insensitively), `None` otherwise.
+    fn get_ci(&self, key: &str) -> Option<&V>;
+
+    /// Check if a key exists with case-insensitive lookup.
+    fn contains_key_ci(&self, key: &str) -> bool;
+
+    /// Get a mutable reference with case-insensitive key lookup.
+    fn get_mut_ci(&mut self, key: &str) -> Option<&mut V>;
+}
+
+impl<V> CaseInsensitiveLookup<V> for HashMap<String, V> {
+    fn get_ci(&self, key: &str) -> Option<&V> {
+        // Try exact match first (fast path for common case)
+        if let Some(v) = self.get(key) {
+            return Some(v);
+        }
+        // Fall back to case-insensitive search
+        let key_lower = key.to_lowercase();
+        self.iter()
+            .find(|(k, _)| k.to_lowercase() == key_lower)
+            .map(|(_, v)| v)
+    }
+
+    fn contains_key_ci(&self, key: &str) -> bool {
+        self.get_ci(key).is_some()
+    }
+
+    fn get_mut_ci(&mut self, key: &str) -> Option<&mut V> {
+        // Find the actual key first
+        let key_lower = key.to_lowercase();
+        let actual_key = self.keys().find(|k| k.to_lowercase() == key_lower).cloned();
+
+        // Then get mutable reference using the actual key
+        actual_key.and_then(|k| self.get_mut(&k))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_case_insensitive_str_equality() {
+        let a = CaseInsensitiveStr::new("Person");
+        let b = CaseInsensitiveStr::new("person");
+        let c = CaseInsensitiveStr::new("PERSON");
+        let d = CaseInsensitiveStr::new("PeRsOn");
+
+        assert_eq!(a, b);
+        assert_eq!(b, c);
+        assert_eq!(a, c);
+        assert_eq!(c, d);
+    }
+
+    #[test]
+    fn test_case_insensitive_str_inequality() {
+        let a = CaseInsensitiveStr::new("Person");
+        let b = CaseInsensitiveStr::new("Company");
+
+        assert_ne!(a, b);
+    }
+
+    #[test]
+    fn test_case_insensitive_str_hash() {
+        use std::collections::HashSet;
+
+        let mut set = HashSet::new();
+        set.insert(CaseInsensitiveStr::new("Person"));
+
+        // All variations should be found
+        assert!(set.contains(&CaseInsensitiveStr::new("person")));
+        assert!(set.contains(&CaseInsensitiveStr::new("PERSON")));
+        assert!(set.contains(&CaseInsensitiveStr::new("Person")));
+
+        // Different value should not be found
+        assert!(!set.contains(&CaseInsensitiveStr::new("Company")));
+    }
+
+    #[test]
+    fn test_case_insensitive_map() {
+        let mut map: CaseInsensitiveMap<i32> = HashMap::new();
+        map.insert(CaseInsensitiveStr::new("Person"), 1);
+        map.insert(CaseInsensitiveStr::new("Company"), 2);
+
+        // Test various cases
+        assert_eq!(map.get(&CaseInsensitiveStr::new("person")), Some(&1));
+        assert_eq!(map.get(&CaseInsensitiveStr::new("PERSON")), Some(&1));
+        assert_eq!(map.get(&CaseInsensitiveStr::new("Person")), Some(&1));
+        assert_eq!(map.get(&CaseInsensitiveStr::new("PeRsOn")), Some(&1));
+
+        assert_eq!(map.get(&CaseInsensitiveStr::new("company")), Some(&2));
+        assert_eq!(map.get(&CaseInsensitiveStr::new("COMPANY")), Some(&2));
+
+        assert_eq!(map.get(&CaseInsensitiveStr::new("Unknown")), None);
+    }
+
+    #[test]
+    fn test_case_insensitive_lookup_trait() {
+        let mut map = HashMap::new();
+        map.insert("Person".to_string(), 1);
+        map.insert("Company".to_string(), 2);
+        map.insert("fullName".to_string(), 3);
+
+        // Test get_ci
+        assert_eq!(map.get_ci("person"), Some(&1));
+        assert_eq!(map.get_ci("PERSON"), Some(&1));
+        assert_eq!(map.get_ci("Person"), Some(&1));
+        assert_eq!(map.get_ci("PeRsOn"), Some(&1));
+
+        assert_eq!(map.get_ci("company"), Some(&2));
+        assert_eq!(map.get_ci("COMPANY"), Some(&2));
+
+        assert_eq!(map.get_ci("fullname"), Some(&3));
+        assert_eq!(map.get_ci("FULLNAME"), Some(&3));
+        assert_eq!(map.get_ci("FullName"), Some(&3));
+
+        assert_eq!(map.get_ci("Unknown"), None);
+
+        // Test contains_key_ci
+        assert!(map.contains_key_ci("person"));
+        assert!(map.contains_key_ci("COMPANY"));
+        assert!(map.contains_key_ci("FullName"));
+        assert!(!map.contains_key_ci("Unknown"));
+    }
+
+    #[test]
+    fn test_case_insensitive_lookup_exact_match_fast_path() {
+        let mut map = HashMap::new();
+        map.insert("Person".to_string(), 1);
+
+        // Exact match should use fast path
+        assert_eq!(map.get_ci("Person"), Some(&1));
+
+        // Case variations should still work
+        assert_eq!(map.get_ci("person"), Some(&1));
+        assert_eq!(map.get_ci("PERSON"), Some(&1));
+    }
+
+    #[test]
+    fn test_case_insensitive_str_as_str() {
+        let s = CaseInsensitiveStr::new("Person");
+        assert_eq!(s.as_str(), "person"); // Stored as lowercase
+    }
+
+    #[test]
+    fn test_case_insensitive_str_from_string() {
+        let s = String::from("Person");
+        let ci_str: CaseInsensitiveStr = s.into();
+        assert_eq!(ci_str.as_str(), "person");
+    }
+
+    #[test]
+    fn test_case_insensitive_str_from_str() {
+        let ci_str: CaseInsensitiveStr = "Person".into();
+        assert_eq!(ci_str.as_str(), "person");
+    }
+
+    #[test]
+    fn test_case_insensitive_map_insertion_deduplication() {
+        let mut map: CaseInsensitiveMap<i32> = HashMap::new();
+
+        // Insert with different cases - should overwrite
+        map.insert(CaseInsensitiveStr::new("Person"), 1);
+        map.insert(CaseInsensitiveStr::new("person"), 2);
+        map.insert(CaseInsensitiveStr::new("PERSON"), 3);
+
+        // Should have only one entry with the latest value
+        assert_eq!(map.len(), 1);
+        assert_eq!(map.get(&CaseInsensitiveStr::new("person")), Some(&3));
+    }
+
+    #[test]
+    fn test_get_mut_ci() {
+        let mut map = HashMap::new();
+        map.insert("Person".to_string(), 1);
+        map.insert("Company".to_string(), 2);
+
+        // Test mutable access with different cases
+        if let Some(v) = map.get_mut_ci("person") {
+            *v = 10;
+        }
+        assert_eq!(map.get_ci("Person"), Some(&10));
+
+        if let Some(v) = map.get_mut_ci("COMPANY") {
+            *v = 20;
+        }
+        assert_eq!(map.get_ci("company"), Some(&20));
+
+        // Non-existent key
+        assert!(map.get_mut_ci("Unknown").is_none());
+    }
+
+    #[test]
+    fn test_property_name_normalization() {
+        // Test realistic property names from Issue #105
+        let mut map = HashMap::new();
+        map.insert("fullName".to_string(), 1);
+        map.insert("isActive".to_string(), 2);
+        map.insert("numFollowers".to_string(), 3);
+
+        // All variations should work
+        assert_eq!(map.get_ci("fullname"), Some(&1));
+        assert_eq!(map.get_ci("FULLNAME"), Some(&1));
+        assert_eq!(map.get_ci("FullName"), Some(&1));
+
+        assert_eq!(map.get_ci("isactive"), Some(&2));
+        assert_eq!(map.get_ci("ISACTIVE"), Some(&2));
+        assert_eq!(map.get_ci("IsActive"), Some(&2));
+
+        assert_eq!(map.get_ci("numfollowers"), Some(&3));
+        assert_eq!(map.get_ci("NUMFOLLOWERS"), Some(&3));
+        assert_eq!(map.get_ci("NumFollowers"), Some(&3));
+    }
+
+    #[test]
+    fn test_qualify_column() {
+        use super::qualify_column;
+
+        // Basic usage
+        assert_eq!(qualify_column("p", "name"), "p__name");
+        assert_eq!(qualify_column("person", "age"), "person__age");
+
+        // Case normalization
+        assert_eq!(qualify_column("P", "Name"), "p__name");
+        assert_eq!(qualify_column("PERSON", "AGE"), "person__age");
+        assert_eq!(qualify_column("Person", "fullName"), "person__fullname");
+
+        // Mixed case
+        assert_eq!(qualify_column("MyVar", "IsActive"), "myvar__isactive");
+        assert_eq!(qualify_column("a", "NumFollowers"), "a__numfollowers");
+    }
+}