sqlspec 0.13.1__py3-none-any.whl → 0.16.2__py3-none-any.whl

sqlspec/loader.py

@@ -9,49 +9,158 @@ import re
 import time
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
+from difflib import get_close_matches
 from pathlib import Path
 from typing import Any, Optional, Union
 
-from sqlspec.exceptions import SQLFileNotFoundError, SQLFileParseError
-from sqlspec.statement.sql import SQL
+from sqlspec.core.cache import CacheKey, get_cache_config, get_default_cache
+from sqlspec.core.parameters import ParameterStyleConfig, ParameterValidator
+from sqlspec.core.statement import SQL, StatementConfig
+from sqlspec.exceptions import SQLFileNotFoundError, SQLFileParseError, StorageOperationFailedError
 from sqlspec.storage import storage_registry
 from sqlspec.storage.registry import StorageRegistry
 from sqlspec.utils.correlation import CorrelationContext
 from sqlspec.utils.logging import get_logger
 
-__all__ = ("SQLFile", "SQLFileLoader")
+__all__ = ("CachedSQLFile", "NamedStatement", "SQLFile", "SQLFileLoader")
 
 logger = get_logger("loader")
 
 # Matches: -- name: query_name (supports hyphens and special suffixes)
 # We capture the name plus any trailing special characters
 QUERY_NAME_PATTERN = re.compile(r"^\s*--\s*name\s*:\s*([\w-]+[^\w\s]*)\s*$", re.MULTILINE | re.IGNORECASE)
-TRIM_TRAILING_SPECIAL_CHARS = re.compile(r"[^\w-]+$")
+TRIM_SPECIAL_CHARS = re.compile(r"[^\w-]")
+
+# Matches: -- dialect: dialect_name (optional dialect specification)
+DIALECT_PATTERN = re.compile(r"^\s*--\s*dialect\s*:\s*(?P<dialect>[a-zA-Z0-9_]+)\s*$", re.IGNORECASE | re.MULTILINE)
+
+# Supported SQL dialects (based on SQLGlot's available dialects)
+SUPPORTED_DIALECTS = {
+    # Core databases
+    "sqlite",
+    "postgresql",
+    "postgres",
+    "mysql",
+    "oracle",
+    "mssql",
+    "tsql",
+    # Cloud platforms
+    "bigquery",
+    "snowflake",
+    "redshift",
+    "athena",
+    "fabric",
+    # Analytics engines
+    "clickhouse",
+    "duckdb",
+    "databricks",
+    "spark",
+    "spark2",
+    "trino",
+    "presto",
+    # Specialized
+    "hive",
+    "drill",
+    "druid",
+    "materialize",
+    "teradata",
+    "dremio",
+    "doris",
+    "risingwave",
+    "singlestore",
+    "starrocks",
+    "tableau",
+    "exasol",
+    "dune",
+}
+
+# Dialect aliases for common variants
+DIALECT_ALIASES = {
+    "postgresql": "postgres",
+    "pg": "postgres",
+    "pgplsql": "postgres",
+    "plsql": "oracle",
+    "oracledb": "oracle",
+    "tsql": "mssql",
+}
+
 MIN_QUERY_PARTS = 3
 
 
 def _normalize_query_name(name: str) -> str:
     """Normalize query name to be a valid Python identifier.
 
-    - Strips trailing special characters (like $, !, etc from aiosql)
-    - Replaces hyphens with underscores
-
     Args:
         name: Raw query name from SQL file
 
     Returns:
         Normalized query name suitable as Python identifier
     """
-    # Strip trailing non-alphanumeric characters (excluding underscore) and replace hyphens
-    return TRIM_TRAILING_SPECIAL_CHARS.sub("", name).replace("-", "_")
+    return TRIM_SPECIAL_CHARS.sub("", name).replace("-", "_")
+
+
+def _normalize_dialect(dialect: str) -> str:
+    """Normalize dialect name with aliases.
+
+    Args:
+        dialect: Raw dialect name from SQL file
+
+    Returns:
+        Normalized dialect name
+    """
+    normalized = dialect.lower().strip()
+    return DIALECT_ALIASES.get(normalized, normalized)
+
+
+def _normalize_dialect_for_sqlglot(dialect: str) -> str:
+    """Normalize dialect name for SQLGlot compatibility.
+
+    Args:
+        dialect: Dialect name from SQL file or parameter
+
+    Returns:
+        SQLGlot-compatible dialect name
+    """
+    normalized = dialect.lower().strip()
+    return DIALECT_ALIASES.get(normalized, normalized)
+
+
+def _get_dialect_suggestions(invalid_dialect: str) -> "list[str]":
+    """Get dialect suggestions using fuzzy matching.
+
+    Args:
+        invalid_dialect: Invalid dialect name that was provided
+
+    Returns:
+        List of suggested dialect names (up to 3 suggestions)
+    """
+
+    return get_close_matches(invalid_dialect, SUPPORTED_DIALECTS, n=3, cutoff=0.6)
+
+
+class NamedStatement:
+    """Represents a parsed SQL statement with metadata.
+
+    Contains individual SQL statements extracted from files with their
+    normalized names, SQL content, optional dialect specifications,
+    and line position for error reporting.
+    """
+
+    __slots__ = ("dialect", "name", "sql", "start_line")
+
+    def __init__(self, name: str, sql: str, dialect: "Optional[str]" = None, start_line: int = 0) -> None:
+        self.name = name
+        self.sql = sql
+        self.dialect = dialect
+        self.start_line = start_line
 
 
 @dataclass
 class SQLFile:
     """Represents a loaded SQL file with metadata.
 
-    This class holds the SQL content along with metadata about the file
-    such as its location, timestamps, and content hash.
+    Contains SQL content and associated metadata including file location,
+    timestamps, and content hash.
     """
 
     content: str
@@ -74,26 +183,32 @@ class SQLFile:
         self.checksum = hashlib.md5(self.content.encode(), usedforsecurity=False).hexdigest()
 
 
-class SQLFileLoader:
-    """Loads and parses SQL files with aiosql-style named queries.
+class CachedSQLFile:
+    """Cached SQL file with parsed statements for efficient reloading.
+
+    Stored in the file cache to avoid re-parsing SQL files when their
+    content hasn't changed.
+    """
 
-    This class provides functionality to load SQL files containing
-    named queries (using -- name: syntax) and retrieve them by name.
+    __slots__ = ("parsed_statements", "sql_file", "statement_names")
 
-    Example:
-        ```python
-        # Initialize loader
-        loader = SQLFileLoader()
+    def __init__(self, sql_file: SQLFile, parsed_statements: "dict[str, NamedStatement]") -> None:
+        """Initialize cached SQL file.
 
-        # Load SQL files
-        loader.load_sql("queries/users.sql")
-        loader.load_sql(
-            "queries/products.sql", "queries/orders.sql"
-        )
+        Args:
+            sql_file: The original SQLFile with content and metadata.
+            parsed_statements: Named statements from the file.
+        """
+        self.sql_file = sql_file
+        self.parsed_statements = parsed_statements
+        self.statement_names = list(parsed_statements.keys())
 
-        # Get SQL by query name
-        sql = loader.get_sql("get_user_by_id", user_id=123)
-        ```
+
+class SQLFileLoader:
+    """Loads and parses SQL files with aiosql-style named queries.
+
+    Provides functionality to load SQL files containing named queries
+    (using -- name: syntax) and retrieve them by name.
     """
 
     def __init__(self, *, encoding: str = "utf-8", storage_registry: StorageRegistry = storage_registry) -> None:
@@ -105,10 +220,68 @@ class SQLFileLoader:
         """
         self.encoding = encoding
         self.storage_registry = storage_registry
-        # Instance-level storage for loaded queries and files
-        self._queries: dict[str, str] = {}
+        self._queries: dict[str, NamedStatement] = {}
         self._files: dict[str, SQLFile] = {}
-        self._query_to_file: dict[str, str] = {}  # Maps query name to file path
+        self._query_to_file: dict[str, str] = {}
+
+    def _raise_file_not_found(self, path: str) -> None:
+        """Raise SQLFileNotFoundError for nonexistent file.
+
+        Args:
+            path: File path that was not found.
+
+        Raises:
+            SQLFileNotFoundError: Always raised.
+        """
+        raise SQLFileNotFoundError(path)
+
+    def _generate_file_cache_key(self, path: Union[str, Path]) -> str:
+        """Generate cache key for a file path.
+
+        Args:
+            path: File path to generate key for.
+
+        Returns:
+            Cache key string for the file.
+        """
+        path_str = str(path)
+        path_hash = hashlib.md5(path_str.encode(), usedforsecurity=False).hexdigest()
+        return f"file:{path_hash[:16]}"
+
+    def _calculate_file_checksum(self, path: Union[str, Path]) -> str:
+        """Calculate checksum for file content validation.
+
+        Args:
+            path: File path to calculate checksum for.
+
+        Returns:
+            MD5 checksum of file content.
+
+        Raises:
+            SQLFileParseError: If file cannot be read.
+        """
+        try:
+            content = self._read_file_content(path)
+            return hashlib.md5(content.encode(), usedforsecurity=False).hexdigest()
+        except Exception as e:
+            raise SQLFileParseError(str(path), str(path), e) from e
+
+    def _is_file_unchanged(self, path: Union[str, Path], cached_file: CachedSQLFile) -> bool:
+        """Check if file has changed since caching.
+
+        Args:
+            path: File path to check.
+            cached_file: Cached file data.
+
+        Returns:
+            True if file is unchanged, False otherwise.
+        """
+        try:
+            current_checksum = self._calculate_file_checksum(path)
+        except Exception:
+            return False
+        else:
+            return current_checksum == cached_file.sql_file.checksum
 
     def _read_file_content(self, path: Union[str, Path]) -> str:
         """Read file content using storage backend.
@@ -120,8 +293,10 @@ class SQLFileLoader:
             File content as string.
 
         Raises:
-            SQLFileParseError: If file cannot be read.
+            SQLFileNotFoundError: If file does not exist.
+            SQLFileParseError: If file cannot be read or parsed.
         """
+
         path_str = str(path)
 
         try:
@@ -129,6 +304,10 @@ class SQLFileLoader:
             return backend.read_text(path_str, encoding=self.encoding)
         except KeyError as e:
             raise SQLFileNotFoundError(path_str) from e
+        except StorageOperationFailedError as e:
+            if "not found" in str(e).lower() or "no such file" in str(e).lower():
+                raise SQLFileNotFoundError(path_str) from e
+            raise SQLFileParseError(path_str, path_str, e) from e
         except Exception as e:
             raise SQLFileParseError(path_str, path_str, e) from e
 
@@ -142,46 +321,91 @@ class SQLFileLoader:
                 first_sql_line_index = i
                 break
         if first_sql_line_index == -1:
-            return ""  # All comments or empty
+            return ""
         return "\n".join(lines[first_sql_line_index:]).strip()
 
     @staticmethod
-    def _parse_sql_content(content: str, file_path: str) -> dict[str, str]:
-        """Parse SQL content and extract named queries."""
-        queries: dict[str, str] = {}
-        matches = list(QUERY_NAME_PATTERN.finditer(content))
-        if not matches:
+    def _parse_sql_content(content: str, file_path: str) -> "dict[str, NamedStatement]":
+        """Parse SQL content and extract named statements with dialect specifications.
+
+        Args:
+            content: Raw SQL file content to parse
+            file_path: File path for error reporting
+
+        Returns:
+            Dictionary mapping normalized statement names to NamedStatement objects
+
+        Raises:
+            SQLFileParseError: If no named statements found, duplicate names exist,
+                              or invalid dialect names are specified
+        """
+        statements: dict[str, NamedStatement] = {}
+        content.splitlines()
+
+        name_matches = list(QUERY_NAME_PATTERN.finditer(content))
+        if not name_matches:
             raise SQLFileParseError(
-                file_path, file_path, ValueError("No named SQL statements found (-- name: query_name)")
+                file_path, file_path, ValueError("No named SQL statements found (-- name: statement_name)")
             )
 
-        for i, match in enumerate(matches):
-            raw_query_name = match.group(1).strip()
+        for i, match in enumerate(name_matches):
+            raw_statement_name = match.group(1).strip()
+            statement_start_line = content[: match.start()].count("\n")
+
             start_pos = match.end()
-            end_pos = matches[i + 1].start() if i + 1 < len(matches) else len(content)
+            end_pos = name_matches[i + 1].start() if i + 1 < len(name_matches) else len(content)
 
-            sql_text = content[start_pos:end_pos].strip()
-            if not raw_query_name or not sql_text:
+            statement_section = content[start_pos:end_pos].strip()
+            if not raw_statement_name or not statement_section:
                 continue
 
-            clean_sql = SQLFileLoader._strip_leading_comments(sql_text)
+            dialect = None
+            statement_sql = statement_section
+
+            section_lines = [line.strip() for line in statement_section.split("\n") if line.strip()]
+            if section_lines:
+                first_line = section_lines[0]
+                dialect_match = DIALECT_PATTERN.match(first_line)
+                if dialect_match:
+                    declared_dialect = dialect_match.group("dialect").lower()
+
+                    normalized_dialect = _normalize_dialect(declared_dialect)
+
+                    if normalized_dialect not in SUPPORTED_DIALECTS:
+                        suggestions = _get_dialect_suggestions(normalized_dialect)
+                        warning_msg = f"Unknown dialect '{declared_dialect}' at line {statement_start_line + 1}"
+                        if suggestions:
+                            warning_msg += f". Did you mean: {', '.join(suggestions)}?"
+                        warning_msg += (
+                            f". Supported dialects: {', '.join(sorted(SUPPORTED_DIALECTS))}. Using dialect as-is."
+                        )
+                        logger.warning(warning_msg)
+                        dialect = declared_dialect.lower()
+                    else:
+                        dialect = normalized_dialect
+                    remaining_lines = section_lines[1:]
+                    statement_sql = "\n".join(remaining_lines)
+
+            clean_sql = SQLFileLoader._strip_leading_comments(statement_sql)
             if clean_sql:
-                query_name = _normalize_query_name(raw_query_name)
-                if query_name in queries:
-                    raise SQLFileParseError(file_path, file_path, ValueError(f"Duplicate query name: {raw_query_name}"))
-                queries[query_name] = clean_sql
+                normalized_name = _normalize_query_name(raw_statement_name)
+                if normalized_name in statements:
+                    raise SQLFileParseError(
+                        file_path, file_path, ValueError(f"Duplicate statement name: {raw_statement_name}")
+                    )
+
+                statements[normalized_name] = NamedStatement(
+                    name=normalized_name, sql=clean_sql, dialect=dialect, start_line=statement_start_line
+                )
 
-        if not queries:
-            raise SQLFileParseError(file_path, file_path, ValueError("No valid SQL queries found after parsing"))
+        if not statements:
+            raise SQLFileParseError(file_path, file_path, ValueError("No valid SQL statements found after parsing"))
 
-        return queries
+        return statements
 
     def load_sql(self, *paths: Union[str, Path]) -> None:
         """Load SQL files and parse named queries.
 
-        Supports both individual files and directories. When loading directories,
-        automatically namespaces queries based on subdirectory structure.
-
         Args:
             *paths: One or more file paths or directory paths to load.
         """
@@ -203,9 +427,11 @@ class SQLFileLoader:
                     path_obj = Path(path)
                     if path_obj.is_dir():
                         loaded_count += self._load_directory(path_obj)
-                    else:
+                    elif path_obj.exists():
                         self._load_single_file(path_obj, None)
                         loaded_count += 1
+                    elif path_obj.suffix:
+                        self._raise_file_not_found(str(path))
 
             duration = time.perf_counter() - start_time
             new_queries = len(self._queries) - query_count_before
@@ -250,23 +476,77 @@ class SQLFileLoader:
         return len(sql_files)
 
     def _load_single_file(self, file_path: Union[str, Path], namespace: Optional[str]) -> None:
-        """Load a single SQL file with optional namespace.
+        """Load a single SQL file with optional namespace and caching.
 
         Args:
-            file_path: Path to the SQL file (can be string for URIs or Path for local files).
+            file_path: Path to the SQL file.
             namespace: Optional namespace prefix for queries.
         """
         path_str = str(file_path)
 
         if path_str in self._files:
-            return  # Already loaded
+            return
+
+        cache_config = get_cache_config()
+        if not cache_config.compiled_cache_enabled:
+            self._load_file_without_cache(file_path, namespace)
+            return
+
+        cache_key_str = self._generate_file_cache_key(file_path)
+        cache_key = CacheKey((cache_key_str,))
+        unified_cache = get_default_cache()
+        cached_file = unified_cache.get(cache_key)
+
+        if (
+            cached_file is not None
+            and isinstance(cached_file, CachedSQLFile)
+            and self._is_file_unchanged(file_path, cached_file)
+        ):
+            self._files[path_str] = cached_file.sql_file
+            for name, statement in cached_file.parsed_statements.items():
+                namespaced_name = f"{namespace}.{name}" if namespace else name
+                if namespaced_name in self._queries:
+                    existing_file = self._query_to_file.get(namespaced_name, "unknown")
+                    if existing_file != path_str:
+                        raise SQLFileParseError(
+                            path_str,
+                            path_str,
+                            ValueError(f"Query name '{namespaced_name}' already exists in file: {existing_file}"),
+                        )
+                self._queries[namespaced_name] = statement
+                self._query_to_file[namespaced_name] = path_str
+            return
+
+        self._load_file_without_cache(file_path, namespace)
+
+        if path_str in self._files:
+            sql_file = self._files[path_str]
+            file_statements: dict[str, NamedStatement] = {}
+            for query_name, query_path in self._query_to_file.items():
+                if query_path == path_str:
+                    stored_name = query_name
+                    if namespace and query_name.startswith(f"{namespace}."):
+                        stored_name = query_name[len(namespace) + 1 :]
+                    file_statements[stored_name] = self._queries[query_name]
+
+            cached_file_data = CachedSQLFile(sql_file=sql_file, parsed_statements=file_statements)
+            unified_cache.put(cache_key, cached_file_data)
+
+    def _load_file_without_cache(self, file_path: Union[str, Path], namespace: Optional[str]) -> None:
+        """Load a single SQL file without caching.
+
+        Args:
+            file_path: Path to the SQL file.
+            namespace: Optional namespace prefix for queries.
+        """
+        path_str = str(file_path)
 
         content = self._read_file_content(file_path)
         sql_file = SQLFile(content=content, path=path_str)
         self._files[path_str] = sql_file
 
-        queries = self._parse_sql_content(content, path_str)
-        for name, sql in queries.items():
+        statements = self._parse_sql_content(content, path_str)
+        for name, statement in statements.items():
             namespaced_name = f"{namespace}.{name}" if namespace else name
             if namespaced_name in self._queries:
                 existing_file = self._query_to_file.get(namespaced_name, "unknown")
@@ -276,15 +556,16 @@ class SQLFileLoader:
                         path_str,
                         ValueError(f"Query name '{namespaced_name}' already exists in file: {existing_file}"),
                     )
-            self._queries[namespaced_name] = sql
+            self._queries[namespaced_name] = statement
             self._query_to_file[namespaced_name] = path_str
 
-    def add_named_sql(self, name: str, sql: str) -> None:
+    def add_named_sql(self, name: str, sql: str, dialect: "Optional[str]" = None) -> None:
         """Add a named SQL query directly without loading from a file.
 
         Args:
             name: Name for the SQL query.
             sql: Raw SQL content.
+            dialect: Optional dialect for the SQL statement.
 
         Raises:
             ValueError: If query name already exists.
@@ -294,74 +575,100 @@ class SQLFileLoader:
             msg = f"Query name '{name}' already exists (source: {existing_source})"
             raise ValueError(msg)
 
-        self._queries[name] = sql.strip()
+        if dialect is not None:
+            normalized_dialect = _normalize_dialect(dialect)
+            if normalized_dialect not in SUPPORTED_DIALECTS:
+                suggestions = _get_dialect_suggestions(normalized_dialect)
+                warning_msg = f"Unknown dialect '{dialect}'"
+                if suggestions:
+                    warning_msg += f". Did you mean: {', '.join(suggestions)}?"
+                warning_msg += f". Supported dialects: {', '.join(sorted(SUPPORTED_DIALECTS))}. Using dialect as-is."
+                logger.warning(warning_msg)
+                dialect = dialect.lower()
+            else:
+                dialect = normalized_dialect
+
+        statement = NamedStatement(name=name, sql=sql.strip(), dialect=dialect, start_line=0)
+        self._queries[name] = statement
         self._query_to_file[name] = "<directly added>"
 
-    def get_sql(self, name: str, parameters: "Optional[Any]" = None, **kwargs: "Any") -> "SQL":
-        """Get a SQL object by query name.
+    def get_sql(
+        self, name: str, parameters: "Optional[Any]" = None, dialect: "Optional[str]" = None, **kwargs: "Any"
+    ) -> "SQL":
+        """Get a SQL object by statement name with dialect support.
 
         Args:
-            name: Name of the query (from -- name: in SQL file).
-                  Hyphens in names are automatically converted to underscores.
-            parameters: Parameters for the SQL query (aiosql-compatible).
+            name: Name of the statement (from -- name: in SQL file).
+                  Hyphens in names are converted to underscores.
+            parameters: Parameters for the SQL statement.
+            dialect: Optional dialect override.
             **kwargs: Additional parameters to pass to the SQL object.
 
         Returns:
             SQL object ready for execution.
 
         Raises:
-            SQLFileNotFoundError: If query name not found.
+            SQLFileNotFoundError: If statement name not found.
         """
         correlation_id = CorrelationContext.get()
 
-        # Normalize query name for lookup
         safe_name = _normalize_query_name(name)
 
-        logger.debug(
-            "Retrieving SQL query: %s",
-            name,
-            extra={
-                "query_name": name,
-                "safe_name": safe_name,
-                "has_parameters": parameters is not None,
-                "correlation_id": correlation_id,
-            },
-        )
-
         if safe_name not in self._queries:
             available = ", ".join(sorted(self._queries.keys())) if self._queries else "none"
             logger.error(
-                "Query not found: %s",
+                "Statement not found: %s",
                 name,
                 extra={
-                    "query_name": name,
+                    "statement_name": name,
                     "safe_name": safe_name,
-                    "available_queries": len(self._queries),
+                    "available_statements": len(self._queries),
                     "correlation_id": correlation_id,
                 },
             )
-            raise SQLFileNotFoundError(name, path=f"Query '{name}' not found. Available queries: {available}")
+            raise SQLFileNotFoundError(name, path=f"Statement '{name}' not found. Available statements: {available}")
+
+        parsed_statement = self._queries[safe_name]
+
+        effective_dialect = dialect or parsed_statement.dialect
+
+        if dialect is not None:
+            normalized_dialect = _normalize_dialect(dialect)
+            if normalized_dialect not in SUPPORTED_DIALECTS:
+                suggestions = _get_dialect_suggestions(normalized_dialect)
+                warning_msg = f"Unknown dialect '{dialect}'"
+                if suggestions:
+                    warning_msg += f". Did you mean: {', '.join(suggestions)}?"
+                warning_msg += f". Supported dialects: {', '.join(sorted(SUPPORTED_DIALECTS))}. Using dialect as-is."
+                logger.warning(warning_msg)
+                effective_dialect = dialect.lower()
+            else:
+                effective_dialect = normalized_dialect
 
         sql_kwargs = dict(kwargs)
         if parameters is not None:
             sql_kwargs["parameters"] = parameters
 
-        source_file = self._query_to_file.get(safe_name, "unknown")
-
-        logger.debug(
-            "Found query %s from %s",
-            name,
-            source_file,
-            extra={
-                "query_name": name,
-                "safe_name": safe_name,
-                "source_file": source_file,
-                "sql_length": len(self._queries[safe_name]),
-                "correlation_id": correlation_id,
-            },
-        )
+        sqlglot_dialect = None
+        if effective_dialect:
+            sqlglot_dialect = _normalize_dialect_for_sqlglot(effective_dialect)
+
+        if not effective_dialect and "statement_config" not in sql_kwargs:
+            validator = ParameterValidator()
+            param_info = validator.extract_parameters(parsed_statement.sql)
+            if param_info:
+                styles = {p.style for p in param_info}
+                if styles:
+                    detected_style = next(iter(styles))
+                    sql_kwargs["statement_config"] = StatementConfig(
+                        parameter_config=ParameterStyleConfig(
+                            default_parameter_style=detected_style,
+                            supported_parameter_styles=styles,
+                            preserve_parameter_format=True,
+                        )
+                    )
 
-        return SQL(self._queries[safe_name], **sql_kwargs)
+        return SQL(parsed_statement.sql, dialect=sqlglot_dialect, **sql_kwargs)
 
     def get_file(self, path: Union[str, Path]) -> "Optional[SQLFile]":
         """Get a loaded SQLFile object by path.
@@ -375,7 +682,7 @@ class SQLFileLoader:
         return self._files.get(str(path))
 
     def get_file_for_query(self, name: str) -> "Optional[SQLFile]":
-        """Get the SQLFile object that contains a query.
+        """Get the SQLFile object containing a query.
 
         Args:
             name: Query name (hyphens are converted to underscores).
@@ -409,7 +716,7 @@ class SQLFileLoader:
         """Check if a query exists.
 
         Args:
-            name: Query name to check (hyphens are converted to underscores).
+            name: Query name to check.
 
         Returns:
             True if query exists.
@@ -423,11 +730,23 @@ class SQLFileLoader:
         self._queries.clear()
         self._query_to_file.clear()
 
+        cache_config = get_cache_config()
+        if cache_config.compiled_cache_enabled:
+            unified_cache = get_default_cache()
+            unified_cache.clear()
+
+    def clear_file_cache(self) -> None:
+        """Clear the file cache only, keeping loaded queries."""
+        cache_config = get_cache_config()
+        if cache_config.compiled_cache_enabled:
+            unified_cache = get_default_cache()
+            unified_cache.clear()
+
     def get_query_text(self, name: str) -> str:
         """Get raw SQL text for a query.
 
         Args:
-            name: Query name (hyphens are converted to underscores).
+            name: Query name.
 
         Returns:
             Raw SQL text.
@@ -438,4 +757,4 @@ class SQLFileLoader:
         safe_name = _normalize_query_name(name)
         if safe_name not in self._queries:
             raise SQLFileNotFoundError(name)
-        return self._queries[safe_name]
+        return self._queries[safe_name].sql