docs: add comments for `UpdateResult`

[movahhedi]

Closes #988. References #428, #431.

Based on: https://github.com/kysely-org/kysely/blob/deea8e22aae3dc4e142f055b6ec4d9a50a402bda/src/driver/database-connection.ts#L23-L34

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
kysely	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 18, 2024 11:34am

[movahhedi]

Although I've written the comment, I haven't yet truly understood what "Changed Rows" means. I've seen these words:

• Matched rows
• Affected rows
• Updated rows
• Changed rows

What do each mean? Can we make the comment any better?

Correct me if I'm wrong:

• Matched rows: Rows that match the condition[s] of any query.
• Affected rows: Rows that have been affected (inserted, updated [even if not changed], or deleted) by an INSERT/UPDATE/DELETE query.
• Updated rows: Rows affected by an UPDATE query, even if the content of it hasn't changed after the execution of the query.
• Changed rows: Rows affected by an UPDATE query that had their content changed.

[igalklebanov]

• Matched rows: Rows that match the condition[s] of any query.

No such concept.

• Affected rows: Rows that have been affected (inserted, updated [even if not changed], or deleted) by an INSERT/UPDATE/DELETE query.

Kind of. It varies per query kind, at least in MySQL. https://dev.mysql.com/doc/c-api/8.0/en/mysql-affected-rows.html

• Updated rows: Rows affected by an UPDATE query, even if the content of it hasn't changed after the execution of the query.

No such concept outside of Kysely. It is the affected rows value under a different, friendlier, and fitting to context, name.

• Changed rows: Rows affected by an UPDATE query that had their content changed.

I'm not sure this is only relevant to UPDATE. Might be also relevant to INSERT INTO ... ON DUPLICATE KEY UPDATE. And yes, it counts only the rows that actually had column values change.