added return_fields function, attempting to optionally limit fields r…

[sav-norem]

Summary

Implements field projection capabilities for Redis OM queries, allowing users to retrieve only specific fields from models instead of
loading complete objects. This feature improves performance and reduces memory usage when working with large models or when only subset
of fields are needed.

New Features

.values() Method - Dictionary Results

Returns query results as dictionaries containing only the specified fields:

# Get specific fields as dictionaries
customers = Customer.find().values("first_name", "email")
# Returns: [{"first_name": "John", "email": "[email protected]"}]

# Get all fields as dictionaries
customers = Customer.find().values()
# Returns full objects as dictionaries

.only() Method - Partial Model Instances

Returns partial model instances that contain only the specified fields:

  # Get partial model instances
  customers = Customer.find().only("first_name", "email")
  for customer in customers:
      print(customer.first_name)  # ✓ Works - field was loaded
      print(customer.age)         # ✗ Raises AttributeError - field not loaded

Advanced Features

Nested Field Access

Both methods support accessing nested fields using double underscore notation:

  # Access nested JSON fields
  customers = Customer.find().values("name", "address__city", "address__zipcode")
  # Returns: [{"name": "John", "address__city": "NYC", "address__zipcode": "10001"}]

Type Conversion

• .values() performs automatic type conversion (strings to integers, dates, etc.)
• .only() maintains proper model field types and validation

Performance Optimizations

• HashModel: Uses HMGET for efficient retrieval of specific hash fields
• JsonModel: Uses JSON.GET with JSONPath expressions for efficient nested field extraction

Implementation Details

Core Changes

• aredis_om/model/model.py: Added query builder methods and field projection logic
• docs/models.md: Documentation with examples

Query Builder Integration

Both methods integrate seamlessly with existing query operations:

Customer.find(Customer.age > 25).sort_by("name").values("name", "email").all()
Customer.find().only("first_name").first()

Error Handling

• Validates field names at query time
• Provides clear error messages for invalid or non-existent fields
• .only() raises AttributeError when accessing non-loaded fields

Breaking Changes

None - this is an additive feature that maintains full backward compatibility.

Documentation

• Complete usage examples in docs/models.md
• Covers basic usage, advanced features, and performance considerations
• Includes nested field access patterns and best practices

Fixes #568

[DennyD17]

Please add also exclude keyword, it'll be convenient

[DennyD17]

Are u going to finish it guys?

[DennyD17]

I tried to do it, and I found two main problems here:

1. All fields that will not be returned must be Optional or have a default value. If not there will be an Exception here --- https://github.com/redis/redis-om-python/blob/main/aredis_om/model/model.py#L1473. It will not be clear for user. This can be validated in FindQuery init, but I don't have an idea, how to check it.
2. Here is a problem with dict fields and embedded model --- it will be returned as JSON, and we will have a validation issue again.

address
Input should be a valid dictionary or object to extract fields from [type=model_attributes_type, input_value='{"pk":"01JM7319T5SP7A6YR...e":"11111","note":null}', input_type=str]

[bsbodden]

Looks good to me... now 😉

[bsbodden]

LGTM!

[abrookins]

Refactored this feature to become a new only(*fields) and values(*fields) pair, following patterns from the Django ORM.

Stale review