fix: correctly implement field projection with return_fields

- Move RETURN clause from query string to args list (fixes RediSearch syntax)
- Rename internal parameter from return_fields to projected_fields to avoid conflict with method name
- Return dictionaries instead of model instances when using field projection
- Add proper parsing for projected results that returns flat key-value pairs
- Add tests for both HashModel and JsonModel field projection
- Update validation to use model_fields instead of deprecated __fields__

This addresses all review comments from PR #633 and implements field projection correctly.

Author: bsbodden

.claude/settings.local.json

@@ -0,0 +1,25 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(gh pr checkout:*)",
+      "Bash(git rebase:*)",
+      "Bash(git stash:*)",
+      "Bash(make:*)",
+      "Bash(poetry lock:*)",
+      "Bash(poetry run pytest:*)",
+      "Bash(poetry run:*)",
+      "Bash(rm:*)",
+      "Bash(gh pr view:*)",
+      "Bash(gh api:*)",
+      "Bash(grep:*)",
+      "Bash(git add:*)",
+      "Bash(git push:*)",
+      "WebFetch(domain:github.com)",
+      "Bash(npm install:*)",
+      "Bash(cspell:*)",
+      "Bash(git commit:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

CLAUDE.md

@@ -0,0 +1,97 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Overview
+
+Redis OM Python is an object mapping library that provides declarative models for Redis data, built on Pydantic for validation and serialization. It supports both Redis Hash and JSON storage with automatic indexing via RediSearch.
+
+## Development Commands
+
+### Essential Commands
+```bash
+# Setup and dependencies
+make install              # Install all dependencies via Poetry
+make redis               # Start Redis Stack (6380) and Redis OSS (6381) containers
+
+# Code generation (CRITICAL - always run after modifying async code)
+make sync                # Generate sync code from async using unasync
+
+# Code quality
+make format              # Format with isort and black
+make lint                # Run flake8, mypy, and bandit
+make test                # Run full test suite against Redis Stack
+make test_oss            # Run tests against OSS Redis
+
+# Individual test commands
+poetry run pytest tests/test_hash_model.py::test_saves_model  # Run specific test
+poetry run pytest -n auto -vv ./tests/ ./tests_sync/          # Run all tests with parallelization
+```
+
+### Database Migrations
+```bash
+poetry run migrate       # Run schema migrations for index changes
+```
+
+## Architecture and Code Organization
+
+### Dual Async/Sync Architecture
+**CRITICAL**: This codebase uses a unique dual-implementation approach:
+- **Primary source**: `/aredis_om/` - All features implemented here first (async)
+- **Generated code**: `/redis_om/` - Automatically generated sync version
+- **Generation**: `make_sync.py` uses `unasync` to transform async → sync
+
+**Development Rule**: NEVER directly edit files in `/redis_om/`. Always modify `/aredis_om/` and run `make sync`.
+
+### Core Abstractions
+
+#### Model Hierarchy
+- `RedisModel` - Abstract base class
+- `HashModel` - Stores data as Redis Hashes (simple key-value)
+- `JsonModel` - Stores data as RedisJSON documents (nested structures)
+- `EmbeddedJsonModel` - For nested JSON models without separate storage
+
+#### Query System
+Expression-based queries using Django ORM-like syntax:
+```python
+results = await Customer.find(
+    (Customer.age > 18) & (Customer.country == "US")
+).all()
+```
+
+#### Field System
+Built on Pydantic fields with Redis-specific extensions:
+- `Field(index=True)` - Create secondary index
+- `Field(full_text_search=True)` - Enable text search
+- `VectorField` - For similarity search with embeddings
+
+### Key Implementation Patterns
+
+1. **Connection Management**: Uses `get_redis_connection()` from `connections.py`
+2. **Index Management**: Automatic RediSearch index creation via migration system
+3. **Query Resolution**: `QueryResolver` class handles expression tree → RediSearch query conversion
+4. **Type Validation**: All models use Pydantic v2 for validation
+
+## Important Constraints
+
+1. **Database 0 Only**: RediSearch indexes only work in Redis database 0
+2. **Module Requirements**: Advanced features require Redis Stack (RediSearch + RedisJSON)
+3. **Python Versions**: Supports Python 3.8-3.13, test across versions with tox
+4. **Async Testing**: Tests use `pytest-asyncio` with `asyncio_mode = strict`
+
+## Testing Approach
+
+- Separate test directories: `/tests/` (async) and `/tests_sync/` (sync)
+- Docker Compose provides test Redis instances
+- Use fixtures from `conftest.py` for Redis connections
+- Mark tests requiring Redis modules with appropriate decorators
+
+## Common Development Tasks
+
+When implementing new features:
+1. Implement in `/aredis_om/` first
+2. Run `make sync` to generate sync version
+3. Write tests in `/tests/` (async) 
+4. Run `make format` and `make lint`
+5. Run `make test` to verify
+6. Update type hints and ensure mypy passes

aredis_om/model/model.py

@@ -418,7 +418,7 @@ def __init__(
         limit: Optional[int] = None,
         page_size: int = DEFAULT_PAGE_SIZE,
         sort_fields: Optional[List[str]] = None,
-        return_fields: Optional[List[str]] = None,
+        projected_fields: Optional[List[str]] = None,
         nocontent: bool = False,
     ):
         if not has_redisearch(model.db()):
@@ -443,10 +443,10 @@ def __init__(
         else:
             self.sort_fields = []
 
-        if return_fields:
-            self.return_fields = self.validate_return_fields(return_fields)
+        if projected_fields:
+            self.projected_fields = self.validate_projected_fields(projected_fields)
         else:
-            self.return_fields = []
+            self.projected_fields = []
 
         self._expression = None
         self._query: Optional[str] = None
@@ -505,18 +505,45 @@ def query(self):
                 if self._query.startswith("(") or self._query == "*"
                 else f"({self._query})"
             ) + f"=>[{self.knn}]"
-        if self.return_fields:
-            self._query += f" RETURN {','.join(self.return_fields)}"
+        # RETURN clause should be added to args, not to the query string
         return self._query
 
-    def validate_return_fields(self, return_fields: List[str]):
-        for field in return_fields:
-            if field not in self.model.__fields__:  # type: ignore
+    def validate_projected_fields(self, projected_fields: List[str]):
+        for field in projected_fields:
+            if field not in self.model.model_fields:  # type: ignore
                 raise QueryNotSupportedError(
                     f"You tried to return the field {field}, but that field "
                     f"does not exist on the model {self.model}"
                 )
-        return return_fields
+        return projected_fields
+
+    def _parse_projected_results(self, res: Any) -> List[Dict[str, Any]]:
+        """Parse results when using RETURN clause with specific fields."""
+
+        def to_string(s):
+            if isinstance(s, (str,)):
+                return s
+            elif isinstance(s, bytes):
+                return s.decode(errors="ignore")
+            else:
+                return s
+
+        docs = []
+        step = 2  # Because the result has content
+        offset = 1  # The first item is the count of total matches.
+
+        for i in range(1, len(res), step):
+            if res[i + offset] is None:
+                continue
+            # When using RETURN, we get flat key-value pairs
+            fields: Dict[str, str] = dict(
+                zip(
+                    map(to_string, res[i + offset][::2]),
+                    map(to_string, res[i + offset][1::2]),
+                )
+            )
+            docs.append(fields)
+        return docs
 
     @property
     def query_params(self):
@@ -899,6 +926,12 @@ async def execute(
         if self.nocontent:
             args.append("NOCONTENT")
 
+        # Add RETURN clause to the args list, not to the query string
+        if self.projected_fields:
+            args.extend(
+                ["RETURN", str(len(self.projected_fields))] + self.projected_fields
+            )
+
         if return_query_args:
             return self.model.Meta.index_name, args
 
@@ -912,7 +945,12 @@ async def execute(
         if return_raw_result:
             return raw_result
         count = raw_result[0]
-        results = self.model.from_redis(raw_result, self.knn)
+
+        # If we're using field projection, return dictionaries instead of model instances
+        if self.projected_fields:
+            results = self._parse_projected_results(raw_result)
+        else:
+            results = self.model.from_redis(raw_result, self.knn)
         self._model_cache += results
 
         if not exhaust_results:
@@ -966,11 +1004,11 @@ def sort_by(self, *fields: str):
         if not fields:
             return self
         return self.copy(sort_fields=list(fields))
-    
+
     def return_fields(self, *fields: str):
         if not fields:
             return self
-        return self.copy(return_fields=list(fields))
+        return self.copy(projected_fields=list(fields))
 
     async def update(self, use_transaction=True, **field_values):
         """
@@ -1546,9 +1584,7 @@ def find(
         *expressions: Union[Any, Expression],
         knn: Optional[KNNExpression] = None,
     ) -> FindQuery:
-        return FindQuery(
-            expressions=expressions, knn=knn, model=cls
-        )
+        return FindQuery(expressions=expressions, knn=knn, model=cls)
 
     @classmethod
     def from_redis(cls, res: Any, knn: Optional[KNNExpression] = None):

tests/test_hash_model.py

@@ -1133,6 +1133,23 @@ class Meta:
         ).first()
 
 
+@py_test_mark_asyncio
+async def test_return_specified_fields(members, m):
+    member1, member2, member3 = members
+    actual = (
+        await m.Member.find(
+            (m.Member.first_name == "Andrew") & (m.Member.last_name == "Brookins")
+            | (m.Member.last_name == "Smith")
+        )
+        .return_fields("first_name", "last_name")
+        .all()
+    )
+    assert actual == [
+        {"first_name": "Andrew", "last_name": "Brookins"},
+        {"first_name": "Andrew", "last_name": "Smith"},
+    ]
+
+
 @py_test_mark_asyncio
 async def test_can_search_on_multiple_fields_with_geo_filter(key_prefix, redis):
     class Location(HashModel, index=True):

tests/test_json_model.py

@@ -955,13 +955,18 @@ class TypeWithUuid(JsonModel, index=True):
 
     await item.save()
 
+
 @py_test_mark_asyncio
 async def test_return_specified_fields(members, m):
     member1, member2, member3 = members
-    actual = await m.Member.find(
-        (m.Member.first_name == "Andrew") & (m.Member.last_name == "Brookins")
-        | (m.Member.last_name == "Smith")
-    ).all()
+    actual = (
+        await m.Member.find(
+            (m.Member.first_name == "Andrew") & (m.Member.last_name == "Brookins")
+            | (m.Member.last_name == "Smith")
+        )
+        .return_fields("first_name", "last_name")
+        .all()
+    )
     assert actual == [
         {"first_name": "Andrew", "last_name": "Brookins"},
         {"first_name": "Andrew", "last_name": "Smith"},