Support nested query

Author: Peng Ren

README.md

@@ -137,11 +137,23 @@ while users:
 ### SELECT Statements
 - Field selection: `SELECT name, age FROM users`
 - Wildcards: `SELECT * FROM products`
+- **Nested fields**: `SELECT profile.name, profile.age FROM users`
+- **Array access**: `SELECT items[0], items[1].name FROM orders`
 
 ### WHERE Clauses
 - Equality: `WHERE name = 'John'`
 - Comparisons: `WHERE age > 25`, `WHERE price <= 100.0`
 - Logical operators: `WHERE age > 18 AND status = 'active'`
+- **Nested field filtering**: `WHERE profile.status = 'active'`
+- **Array filtering**: `WHERE items[0].price > 100`
+
+### Nested Field Support
+- **Single-level**: `profile.name`, `settings.theme`
+- **Multi-level**: `account.profile.name`, `config.database.host`
+- **Array access**: `items[0].name`, `orders[1].total`
+- **Complex queries**: `WHERE customer.profile.age > 18 AND orders[0].status = 'paid'`
+
+> **Note**: Avoid SQL reserved words (`user`, `data`, `value`, `count`, etc.) as unquoted field names. Use alternatives or bracket notation for arrays.
 
 ### Sorting and Limiting
 - ORDER BY: `ORDER BY name ASC, age DESC`

pymongosql/result_set.py

@@ -2,6 +2,7 @@
 import logging
 from typing import Any, Dict, List, Optional, Sequence, Tuple
 
+import jmespath
 from pymongo.cursor import Cursor as MongoCursor
 from pymongo.errors import PyMongoError
 
@@ -125,14 +126,32 @@ def _process_document(self, doc: Dict[str, Any]) -> Dict[str, Any]:
         processed = {}
         for field_name, include_flag in self._execution_plan.projection_stage.items():
             if include_flag == 1:  # Field is included in projection
-                if field_name in doc:
-                    processed[field_name] = doc[field_name]
-                elif field_name != "_id":  # _id might be excluded by MongoDB
-                    # Field not found, set to None
-                    processed[field_name] = None
+                # Use jmespath to handle nested field access (dot notation and array indexing)
+                value = self._get_nested_value(doc, field_name)
+                processed[field_name] = value
 
         return processed
 
+    def _get_nested_value(self, doc: Dict[str, Any], field_path: str) -> Any:
+        """Extract nested field value from document using JMESPath
+
+        Supports:
+            - Simple fields: "name" -> doc["name"]
+            - Nested fields: "profile.bio" -> doc["profile"]["bio"]
+            - Array indexing: "address.coordinates[1]" -> doc["address"]["coordinates"][1]
+            - Wildcards: "items[*].name" -> [item["name"] for item in items]
+        """
+        try:
+            # Optimization: for simple field names without dots/brackets, use direct access
+            if "." not in field_path and "[" not in field_path:
+                return doc.get(field_path)
+
+            # Use jmespath for complex paths
+            return jmespath.search(field_path, doc)
+        except Exception as e:
+            _logger.debug(f"Error extracting field '{field_path}': {e}")
+            return None
+
     def _dict_to_sequence(self, doc: Dict[str, Any]) -> Tuple[Any, ...]:
         """Convert document dictionary to sequence according to column order"""
         if self._column_names is None:

pymongosql/sql/handler.py

@@ -893,7 +893,7 @@ def handle_visitor(self, ctx: PartiQLParser.SelectItemsContext, parse_result: "P
         return projection
 
     def _extract_field_and_alias(self, item) -> Tuple[str, Optional[str]]:
-        """Extract field name and alias from projection item context"""
+        """Extract field name and alias from projection item context with nested field support"""
         if not hasattr(item, "children") or not item.children:
             return str(item), None
 

requirements.txt

@@ -1,2 +1,3 @@
 antlr4-python3-runtime>=4.13.0
 pymongo>=4.15.0
+jmespath>=1.0.0

tests/test_cursor.py

@@ -138,6 +138,28 @@ def test_execute_complex_query(self, conn):
             for row in rows:
                 assert len(row) >= 2  # Should have at least name and email
 
+    def test_execute_nested_fields_query(self, conn):
+        """Test executing query with nested field access"""
+        sql = "SELECT profile.bio, address.city, address.coordinates FROM users WHERE salary >= 100000"
+
+        cursor = conn.cursor()
+        result = cursor.execute(sql)
+        assert result == cursor
+        assert isinstance(cursor.result_set, ResultSet)
+
+        # Get results - test nested field functionality
+        rows = cursor.result_set.fetchall()
+        assert isinstance(rows, list)
+        assert len(rows) == 4
+
+        # Verify that nested fields are properly projected
+        if cursor.result_set.description:
+            col_names = [desc[0] for desc in cursor.result_set.description]
+            # Should include nested field names in projection
+            assert "profile.bio" in col_names
+            assert "address.city" in col_names
+            assert "address.coordinates" in col_names
+
     def test_execute_parser_error(self, conn):
         """Test executing query with parser errors"""
         sql = "INVALID SQL SYNTAX"

tests/test_sql_parser.py tests/test_sql_parser_general.pytests/test_sql_parser.py renamed to tests/test_sql_parser_general.py

@@ -5,7 +5,7 @@
 from pymongosql.sql.parser import SQLParser
 
 
-class TestSQLParser:
+class TestSQLParserGeneral:
     """Comprehensive test suite for SQL parser from simple to complex queries"""
 
     def test_simple_select_all(self):

tests/test_sql_parser_nested_fields.py

@@ -0,0 +1,193 @@
+# -*- coding: utf-8 -*-
+"""
+Comprehensive tests for nested field support in PyMongoSQL
+"""
+import pytest
+
+from pymongosql.error import SqlSyntaxError
+from pymongosql.sql.parser import SQLParser
+
+
+class TestSQLParserNestedFields:
+    """Test suite for nested field querying functionality"""
+
+    def test_basic_single_level_nesting_select(self):
+        """Test basic single-level nested fields in SELECT"""
+        sql = "SELECT c.a, c.b FROM collection"
+        parser = SQLParser(sql)
+
+        assert not parser.has_errors, f"Parser errors: {parser.errors}"
+
+        execution_plan = parser.get_execution_plan()
+        assert execution_plan.collection == "collection"
+        assert execution_plan.projection_stage == {"c.a": 1, "c.b": 1}
+        assert execution_plan.filter_stage == {}
+
+    def test_basic_single_level_nesting_where(self):
+        """Test basic single-level nested fields in WHERE clause"""
+        sql = "SELECT * FROM users WHERE profile.status = 'active'"
+        parser = SQLParser(sql)
+
+        assert not parser.has_errors, f"Parser errors: {parser.errors}"
+
+        execution_plan = parser.get_execution_plan()
+        assert execution_plan.collection == "users"
+        assert execution_plan.filter_stage == {"profile.status": "active"}
+
+    def test_multi_level_nesting_non_reserved_words(self):
+        """Test multi-level nested fields with non-reserved words"""
+        sql = "SELECT account.profile.name FROM users WHERE account.settings.theme = 'dark'"
+        parser = SQLParser(sql)
+
+        assert not parser.has_errors, f"Parser errors: {parser.errors}"
+
+        execution_plan = parser.get_execution_plan()
+        assert execution_plan.collection == "users"
+        assert execution_plan.projection_stage == {"account.profile.name": 1}
+        assert execution_plan.filter_stage == {"account.settings.theme": "dark"}
+
+    def test_array_bracket_notation_select(self):
+        """Test array access using bracket notation in SELECT"""
+        sql = "SELECT items[0], items[1].name FROM orders"
+        parser = SQLParser(sql)
+
+        assert not parser.has_errors, f"Parser errors: {parser.errors}"
+
+        execution_plan = parser.get_execution_plan()
+        assert execution_plan.collection == "orders"
+        assert execution_plan.projection_stage == {"items[0]": 1, "items[1].name": 1}
+
+    def test_array_bracket_notation_where(self):
+        """Test array access using bracket notation in WHERE"""
+        sql = "SELECT * FROM orders WHERE items[0].price > 100"
+        parser = SQLParser(sql)
+
+        assert not parser.has_errors, f"Parser errors: {parser.errors}"
+
+        execution_plan = parser.get_execution_plan()
+        assert execution_plan.collection == "orders"
+        assert execution_plan.filter_stage == {"items[0].price": {"$gt": 100}}
+
+    def test_quoted_reserved_words(self):
+        """Test using quoted reserved words as field names - currently limited support"""
+        # Note: This test documents current limitations with quoted identifiers in complex paths
+        sql = 'SELECT "user" FROM collection'  # Simplified test that works
+        parser = SQLParser(sql)
+
+        assert not parser.has_errors, f"Parser errors: {parser.errors}"
+
+        execution_plan = parser.get_execution_plan()
+        assert execution_plan.collection == "collection"
+        assert execution_plan.projection_stage == {'"user"': 1}
+
+    def test_complex_nested_query(self):
+        """Test complex query with multiple nested field types"""
+        sql = """
+        SELECT
+            customer.profile.name,
+            orders[0].total,
+            settings.preferences.theme
+        FROM transactions
+        WHERE customer.profile.age > 18
+          AND orders[0].status = 'completed'
+          AND settings.notifications = true
+        """
+        parser = SQLParser(sql)
+
+        assert not parser.has_errors, f"Parser errors: {parser.errors}"
+
+        execution_plan = parser.get_execution_plan()
+        assert execution_plan.collection == "transactions"
+
+        expected_projection = {"customer.profile.name": 1, "orders[0].total": 1, "settings.preferences.theme": 1}
+        assert execution_plan.projection_stage == expected_projection
+
+        # The filter should be a combination of conditions
+        expected_filter = {
+            "$and": [
+                {"customer.profile.age": {"$gt": 18}},
+                {"orders[0].status": "completed"},
+                {"settings.notifications": True},
+            ]
+        }
+        assert execution_plan.filter_stage == expected_filter
+
+    def test_reserved_word_user_fails(self):
+        """Test that unquoted 'user' keyword fails"""
+        sql = "SELECT user.profile.name FROM users"
+
+        with pytest.raises(SqlSyntaxError) as exc_info:
+            parser = SQLParser(sql)
+            parser.get_execution_plan()
+
+        assert "no viable alternative" in str(exc_info.value)
+
+    def test_reserved_word_value_fails(self):
+        """Test that unquoted 'value' keyword fails"""
+        sql = "SELECT data.value FROM items"
+
+        with pytest.raises(SqlSyntaxError) as exc_info:
+            parser = SQLParser(sql)
+            parser.get_execution_plan()
+
+        assert "no viable alternative" in str(exc_info.value)
+
+    def test_numeric_dot_notation_fails(self):
+        """Test that numeric dot notation fails"""
+        sql = "SELECT c.0.name FROM collection"
+
+        with pytest.raises(SqlSyntaxError) as exc_info:
+            parser = SQLParser(sql)
+            parser.get_execution_plan()
+
+        assert "mismatched input" in str(exc_info.value)
+
+    def test_nested_with_comparison_operators(self):
+        """Test nested fields with various comparison operators"""
+        # Test supported comparison operators with non-reserved field names
+        test_cases = [
+            ("profile.age > 18", {"profile.age": {"$gt": 18}}),
+            ("settings.total < 100", {"settings.total": {"$lt": 100}}),  # Changed from 'count' (reserved)
+            ("status.active = true", {"status.active": True}),
+            ("config.name != 'default'", {"config.name": {"$ne": "default"}}),
+        ]
+
+        for where_clause, expected_filter in test_cases:
+            sql = f"SELECT * FROM collection WHERE {where_clause}"
+            parser = SQLParser(sql)
+
+            assert not parser.has_errors, f"Parser errors for '{where_clause}': {parser.errors}"
+
+            execution_plan = parser.get_execution_plan()
+            assert execution_plan.filter_stage == expected_filter
+
+    def test_nested_with_logical_operators(self):
+        """Test nested fields with logical operators"""
+        sql = """
+        SELECT * FROM users
+        WHERE profile.age > 18
+          AND settings.active = true
+          OR profile.vip = true
+        """
+        parser = SQLParser(sql)
+
+        assert not parser.has_errors, f"Parser errors: {parser.errors}"
+
+        execution_plan = parser.get_execution_plan()
+        # The exact structure depends on operator precedence handling
+        assert "profile.age" in str(execution_plan.filter_stage)
+        assert "settings.active" in str(execution_plan.filter_stage)
+        assert "profile.vip" in str(execution_plan.filter_stage)
+
+    def test_nested_with_aliases(self):
+        """Test nested fields with column aliases"""
+        sql = "SELECT profile.name AS fullname, settings.theme AS ui_theme FROM users"
+        parser = SQLParser(sql)
+
+        assert not parser.has_errors, f"Parser errors: {parser.errors}"
+
+        execution_plan = parser.get_execution_plan()
+        assert execution_plan.collection == "users"
+        # Note: Current implementation uses original field names in projection
+        # Aliases are handled at the result processing level
+        assert execution_plan.projection_stage == {"profile.name": 1, "settings.theme": 1}