[BUG] Link field query fails when document field named 'title' conflicts with Link's collection name property

[syedhabib39]

Describe the bug
When using a field named title in a Beanie document and referencing it through a Link in another document, querying the linked document's title field throws an AttributeError. The error occurs because Beanie appears to be conflicting with Python's built-in str.title() method, returning <built-in method title of ExpressionField object at 0x7e1098dd23d0> instead of the field value. According to the source code, in Link objects, title refers to its collection name, which creates a naming conflict when trying to access a document field also named title.

To Reproduce

from beanie import Document, Link
from typing import Optional

class Subject(Document):
    title: str

class Chapter(Document):
    title: str
    subject: Link[Subject]

# This query fails with AttributeError
data = await Chapter.find(Chapter.subject.title == 'sub1')

# Error: AttributeError: 'builtin_function_or_method' object has no attribute 'split'
# The error suggests that Chapter.subject.title is returning the built-in str.title() method
# instead of the actual field reference

[staticxterm]

I am not able to reproduce your issue about the string method. I get a completely different error when running a full script normally (with init_beanie and everything set up correctly) using Beanie v2, Pydantic v2 and running with Python 3.13.

What you're suggesting from your reproducer is not possible or currently not supported by Beanie.
Since "subject" is a link in the Chapter document/model, it must be resolved first. You cannot have a query like "Chapter.subject.title", because we do not know what the subject resolves to, without fetching that document first with fetch_links=True.
This is not even possible in the native mongosh syntax!
Take this ChatGPT generated list as a general rule of thumb when working with find() queries:

find() can:

• Match fields in the same document
• Use operators ($eq, $in, $expr, etc.)
• Use indexes

find() cannot:

• Join collections
• Resolve DBRefs
  (Beanie's fetch_links=True syntax does allow for this very simple use case)
• Access fields in another collection
• Execute lookups of any kind
  (Beanie's fetch_links=True does allow for basic lookups available on links, but only to resolve them, not to do some other field comparisons on the resolved documents all in the same query!)

I guess if anything these are improvements to the current Links handling and Find query handling with regards to Links.

[syedhabib39]

Thank you for the detailed explanation and for attempting to reproduce the issue.

I appreciate the clarification about Beanie's Link handling limitations. You're absolutely right that direct querying through links like Chapter.subject.title isn't supported in standard MongoDB find() operations without proper resolution.

However, I wanted to confirm that after changing the field name from title to name (to avoid the Beanie Link conflict), the query now works as expected:

QBank.chapter.subject.name == 'sub1'

This works in our dev/staging environment with:

• Python 3.14
• Beanie 2.0.1
• Pydantic v2

We are using this directly with Beanie's find() query along with fetch_links=True, and it works perfectly after the field rename. The fetch_links=True parameter properly resolves the nested links (chapter → subject) before the field comparison is made.

Example of our working query:

results = await QBank.find(
    QBank.chapter.subject.name == 'sub1',
    fetch_links=True
).to_list()

Additionally, we also use this pattern in our aggregation pipelines where:

First performs $lookup to resolve the chapter reference then performs another $lookup to resolve the subject reference from the chapter only then performs field matching on the resolved subject.name.

The original issue with title was specifically about the Beanie Link class having a title attribute that conflicted with our model field. Renaming to name resolved that conflict and everything works as expected with the latest versions in both find() queries with fetch_links=True and aggregation pipelines.

Thanks again for your time investigating this!

[staticxterm]

Please provide a minimally reproducible example that would trigger the error you're describing otherwise there's nothing for us to go on here.
For example, the configuration you mention:

This works in our dev/staging environment with:

Python 3.14
Beanie 2.0.1
Pydantic v2

should not even be possible since Beanie v2.0.1 explicitly does not support Python 3.14:

beanie/pyproject.toml

Line 10 in b090d6c

requires-python = ">=3.9,<3.14"

[syedhabib39]

Now I get the different error Error 'bool' object has no attribute 'items'

Working Example Code
I've attached a complete working example that demonstrates both the bug with title and the solution with name:

"""
Working Example: Beanie Link Field Name Conflict Resolution

Environment:
- Python 3.14
- Beanie 2.0.1
- Pydantic v2
"""

import asyncio
from beanie import Document, Link, init_beanie
from pymongo import AsyncMongoClient


# ============================================================================
# PROBLEMATIC MODELS (Using 'title' field - causes conflict)
# ============================================================================

class SubjectWithTitle(Document):
    title: str
    
    class Settings:
        name = "subject_with_title"


class ChapterWithTitle(Document):
    title: str
    subject: Link[SubjectWithTitle]
    
    class Settings:
        name = "chapter_with_title"


# ============================================================================
# WORKING MODELS (Using 'name' field - no conflict)
# ============================================================================

class Subject(Document):
    name: str  # Changed from 'title' to 'name'
    
    class Settings:
        name = "subject"


class Chapter(Document):
    name: str  # Changed from 'title' to 'name'
    subject: Link[Subject]
    
    class Settings:
        name = "chapter"


# ============================================================================
# MAIN EXAMPLE
# ============================================================================

async def main():
    # Initialize MongoDB connection
    client = AsyncMongoClient("mongodb://localhost:27017")
    database = client.test_db
    
    # Initialize Beanie with all document models
    await init_beanie(
        database=database,
        document_models=[
            SubjectWithTitle,
            ChapterWithTitle,
            Subject,
            Chapter
        ]
    )
    
    print('\n')
    print('=' * 80)
    print("Trying with field `title`")
    print('=' * 80)
    
    # Clean up existing data
    await SubjectWithTitle.delete_all()
    await ChapterWithTitle.delete_all()
    
    # Create test data with 'title' field
    subject_with_title = SubjectWithTitle(title="Mathematics")
    await subject_with_title.insert()
    
    chapter_with_title = ChapterWithTitle(
        title="Algebra",
        subject=subject_with_title
    )
    await chapter_with_title.insert()
    
    print("\nQuerying: Chapter.find()")
    results = await ChapterWithTitle.find(fetch_links=True).to_list()
    print(f"✅ Results: {results}")
    
    try:
        print("\nQuerying: Chapter.subject.title == 'Mathematics'")
        results = await ChapterWithTitle.find(
            ChapterWithTitle.subject.title == "Mathematics",
            fetch_links=True
        ).to_list()
        print(f"✅ Results: {results}")
    except Exception as e:
        print(f'❌ Error: {e}')
    
    print('\n')
    print('=' * 80)
    print('Trying with field `name`')
    print('=' * 80)
    
    # Clean up existing data
    await Subject.delete_all()
    await Chapter.delete_all()
    
    # Create test data with 'name' field
    subject1 = Subject(name="Mathematics")
    await subject1.insert()
    
    chapter1 = Chapter(name="Algebra", subject=subject1)
    await chapter1.insert()
    
    # Query using the 'name' field (THIS WORKS!)
    print("\nQuerying: Chapter.subject.name == 'Mathematics'")
    chapters = await Chapter.find(
        Chapter.subject.name == "Mathematics",
        fetch_links=True
    ).to_list()
    
    print(f"✅ Found {len(chapters)} chapters: {chapters}")
    
    # Cleanup
    await client.close()


if __name__ == "__main__":
    asyncio.run(main())

Expected Output:

================================================================================
Trying with field `title`
================================================================================

Querying: Chapter.find()
✅ Results: [ChapterWithTitle(...)]

Querying: Chapter.subject.title == 'Mathematics'
❌ Error 'bool' object has no attribute 'items'

================================================================================
Trying with field `name`
================================================================================

Querying: Chapter.subject.name == 'Mathematics'
✅ Found 1 chapters: [Chapter(...)]

This demonstrates that the title field causes a conflict with Beanie's Link class, but renaming to name resolves the issue completely.

Thanks again for your time investigating this!

[staticxterm]

Thanks @syedhabib39 for the reproducer script - this seems to be an issue indeed.

[chanakyan-arivumani]

I was able to reproduce the issue with the example given by @syedhabib39. Here are my findings

Root cause
Verified on Beanie 2.1.0, Python 3.12.13, MongoDB 7.0.
ExpressionField inherits from 'str'. Python's MRO resolves str.title (and ~40 other 'str' methods — upper, lower, strip, split, encode, format, replace, count, etc.) before getattr is consulted, so any linked-document field with one of these names is silently shadowed.

results = await ChapterWithTitle.find( ChapterWithTitle.subject.title == "Mathematics", fetch_links=True ).to_list()

Here, ChapterWithTitle.subject.title returns the bound str.title method and not a field accessor. Then ChapterWithTitle.subject.title == "Mathematics" evaluates to False (method != string), which gets passed into find() as if it were a query expression which then throws 'bool' object has no attribute 'items'

Proposed fix
At model-init time, detect collisions between declared field names and 'str' methods, then override only those specific methods on the per-model ExpressionField subclass. Targeted, no overhead on non-colliding fields, no breaking changes.
As extra protection: detect when a query expression resolves to a non-dict/non-Expression type and raise a clear error pointing at the field name. This eliminates the cryptic stack trace regardless of the root fix.

Happy to open a PR. Any preference on the per-model subclass naming, or thoughts before I start?

[Aun-shahid]

Ran into this and dug in a bit. It reproduces on main (aa290b5), and it is not specific to title.

ExpressionField subclasses str, so __getattr__ only runs when normal attribute lookup fails. That means any field name matching a str attribute resolves to the string method instead of the field, and there are 47 of those. title, count, index, format, find, join, split, replace, strip, lower and upper are all plausible schema field names.

class Subject(Document):
    title: str
    count: int = 0
    name: str = "ok"

class Chapter(Document):
    title: str
    subject: Link[Subject]

Chapter.subject.name    # ExpressionField('subject.name')   ok
Chapter.subject.title   # <built-in method title>           broken
Chapter.subject.count   # <built-in method count>           broken

On current main the query fails with AttributeError: 'bool' object has no attribute 'items' rather than the error in the original report, but the cause is the same. Chapter.subject.title == 'sub1' compares a bound method against a string, gets False, and that bool ends up being handled as the query.

I have a fix that adds __getattribute__ to ExpressionField so model fields take priority over inherited str attributes, falling through to normal lookup otherwise. It fixes the cases above, leaves str behaviour alone when the resolved model has no field by that name, and the existing link and field tests pass (158 of them).

One thing I would like your call on before opening a PR. Beanie calls str methods on these objects internally, key.replace("._id", ".$id") in odm/utils/relations.py and key.split(".") in odm/utils/parsing.py. With the override in place, a model with a field named replace or split would break those call sites. Doing this properly means switching them to the unbound form, str.replace(key, ...) and str.split(key, ...), so internal calls never dispatch through the override.

Happy to send that as a single PR. If you would rather solve the shadowing another way, let me know and I will go with that instead.