fix(query): refuse a nested path on an attribute that holds no nested values

[abnegate]

Problem

Filter and Select treat any dotted attribute as a relationship path and validate only its first segment. On a plain attribute, equal('name.x', [...]) or select(['name.x']) passes validation and reaches the adapter, which names a column that does not exist:

• MySQL/MariaDB raise 1054 and PostgreSQL 42703, which surface as NotFound('Attribute not found'). Appwrite (fix(databases): answer bad query input with 4xx, not 500 or warnings appwrite/appwrite#14538) answers that as 404 table_not_found on the documents/rows list and 500 on /users.
• MongoDB silently matches nothing.

Which shapes reach the engine today, with a string attribute s:

Shape	Before	After
equal('s.x') (and every filter, count)	accepted, engine error	refused
select(['s.x'])	accepted, engine error	refused
orderAsc('s.x')	refused	unchanged
aggregate / groupBy('s.x')	refused (exact schema keys only)	unchanged
equal('o.x') on an object, equal('rel.name') on a relationship, alias.column on a join	accepted	unchanged

Fix

A dotted path passes only when its base is a relationship or object attribute, or a join alias. Otherwise the validator refuses it (Cannot query nested attribute on: s / Cannot select nested attribute on: s), so find/count throw QueryException before the adapter runs. Schemaless adapters (no DefinedAttributes) keep accepting any path. An aggregation select keeps its existing ungrouped-select message.

Tests

• Unit: FilterTest (plain attribute refused; relationship, object and schemaless accepted), SelectTest (plain refused, object accepted). DocumentQueriesTest::test_valid_queries asserted select(['price.relation']) on a double was valid; it now asserts the refusal. The new refusal cases fail without the fix.
• E2E: DocumentTests::testNestedPathOnAPlainAttributeIsAnInvalidQuery runs filter, count and select on every adapter with defined attributes (MariaDB, MySQL, Postgres, SQLite, MongoDB, and the shared-table/pool/mirror variants). Without the fix, the SQL adapters throw NotFound and MongoDB returns an empty page.
• Pint and both PHPStan configs pass locally. Locally the unit suite fails only SwooleAbsentTest (no Redis extension) and BaseAdapterStateTest::testAKeyThePatternEngineCannotFilterIsAnError, both outside this change.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Queries can no longer filter or select nested paths on plain attributes when attribute support is enabled. Nested paths on relationship and object attributes remain supported.
  • Invalid nested queries now return a clear error identifying the attribute that cannot be queried.

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 48 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: utopia-php/database/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: b2187988-277f-42bf-97ff-5c0fcb1c44e6

📥 Commits

Reviewing files that changed from the base of the PR and between f114457 and 384369e.

📒 Files selected for processing: 1

• tests/e2e/Adapter/Scopes/DocumentTests.php

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: utopia-php/database/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: a8512c0c-0119-4a4f-835a-b716f4622819

📥 Commits

Reviewing files that changed from the base of the PR and between 0555ec9 and f114457.

📒 Files selected for processing: 6

• src/Database/Validator/Query/Filter.php
• src/Database/Validator/Query/Select.php
• tests/e2e/Adapter/Scopes/DocumentTests.php
• tests/unit/Validator/DocumentQueriesTest.php
• tests/unit/Validator/Query/FilterTest.php
• tests/unit/Validator/Query/SelectTest.php

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

Query validation now rejects nested filter and selection paths when the base schema attribute is plain. Relationship and object attributes remain nestable. Filters allow nested paths when defined-attribute support is disabled.

Changes: Nested Path Validation

Layer / File(s)	Summary
Filter path validation src/Database/Validator/Query/Filter.php, tests/unit/Validator/Query/FilterTest.php	Filter validation rejects nested paths under plain attributes when attribute support is enabled. Tests cover plain, relationship, and object attributes, and the disabled-support case.
Selection path validation src/Database/Validator/Query/Select.php, tests/unit/Validator/Query/SelectTest.php, tests/unit/Validator/DocumentQueriesTest.php, tests/e2e/Adapter/Scopes/DocumentTests.php	Selection validation rejects nested paths under plain attributes and accepts object attributes. Unit and end-to-end tests cover nested selection and query behavior.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~15 minutes

Change: Bug fix

Suggested reviewers: fogelito

Merge Risk: ⚪ Minimal · up to f1144

The changed validation rejects invalid nested paths before they reach adapters. No actionable merge-blocking issue remains from the reviewed changes.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 18.75% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 16 functions across 6 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: rejecting nested paths on attributes that cannot contain nested values.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}