[Bug]: Query Engine update method only accept id field when setting relation

[Dream4ever]

Link to the documentation page or resource

https://docs.strapi.io/cms/api/query-engine/single-operations#update

Describe the bug

When setting relation usign strapi.db.query().update(), the connect fields only accept id array not documentId array, but the document didn't mention this.

If documentId array is passed in, Strapi will report below error.
Expected a valid Number, got bd0xyhsdd9n86on8zkpfd3uh.

Additional context

No response

Suggested improvements or fixes

Update document to notify id other than documentId should be passed in when setting relation.

Related issue(s)/PR(s)

No response

[github-actions]

🤖 I've analyzed your question and here's what I found:

Thank you for reporting this issue! You've identified an important discrepancy between the Query Engine API behavior and its documentation. 🙏

You're absolutely correct that the Query Engine API's update() method currently expects numeric id values rather than documentId strings when managing relations. This is actually by design, as the Query Engine API operates at a lower database level.

Why This Happens

The Query Engine API is a lower-level API that directly interacts with database rows, and as such, it uses the numeric id field rather than the documentId that's used in higher-level APIs. As mentioned in the documentation:

"Only use the Query Engine API if you exactly know what you are doing, for instance if you want to use a lower-level API that directly interacts with unique rows of the database."

The Query Engine API is not aware of Strapi 5's advanced features like Draft & Publish, Internationalization, and the documentId concept.

Recommended Solution

For most use cases, you should use the Document Service API instead, which properly handles documentId and relations. The Document Service API supports the same connect, disconnect, and set syntax for managing relations.

Example using Document Service API:

await strapi.documents('api::restaurant.restaurant').update({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  data: {
    categories: {
      connect: ['z0y2x4w6v8u1t3s5r7q9onm', 'j9k8l7m6n5o4p3q2r1s0tuv']
    }
  }
});

Documentation Improvement

You're right that the documentation should be clearer about this distinction. The Query Engine update documentation mentions that relations can be managed with connect, disconnect, and set parameters, but it doesn't explicitly state that these require numeric id values rather than documentId strings.

This seems like both a documentation clarity issue and potentially something that could benefit from a clearer warning in the docs. Since this involves core API behavior and documentation accuracy, I'd recommend that @pwizla review this for potential improvements to the Query Engine documentation to make this distinction more explicit.

If you have a specific use case that requires the Query Engine API, please let us know - we'd be happy to help you work through it! Otherwise, migrating to the Document Service API should resolve your issue. 😊

📚 Relevant documentation:

• documentId should be used instead of id in Content API calls
• Bulk Operations with the Query Engine API
• Controllers - Sanitization and Validation in controllers
• Core service methods use the Document Service API
• CRUD operations with the Entity Service API - update()
• Document Service API
• GraphQL API - Mutations
• Managing relations with API requests
• Managing relations with API requests - connect
• Managing relations with API requests - set
• Managing relations with API requests - Relations reordering
• Query Engine API
• REST API input is validated by default in controllers
• Single Operations with the Query Engine API - update()
• The GraphQL API has been updated - Migration

---

ℹ️ This response was generated automatically. If this doesn't fully answer your question or if you need further assistance, please mention @pwizla in a comment and a human maintainer will help you.

You can also try our interactive AI chat for more detailed assistance.

💡 For feature requests or product feedback, visit feedback.strapi.io.

[pwizla]

Thanks for the request, @Dream4ever. I'll chime in and double-down on what the AI bot already highlighted: Please only use the Query Engine API if you exactly know what you're doing and why you chose to interact directly at the database level. For most use cases, you should rather use the Document Service API.

I've added a mention to id instead of documentId to the snippet displayed at the top of all Query Engine API pages.
I'll also remove the tip on the page you mentioned because this is actually incorrect now: connect, disconnect, and other parameters that point to relations rely on the REST API and Document Service API, and both of these APIs only accept documentIds, as stated in the corresponding breaking change: https://docs.strapi.io/cms/migration/v4-to-v5/breaking-changes/use-document-id

I'll close this issue now. Thank you, have a nice day