docs: add comments for UpdateResult

[movahhedi]

Closes #988.
References #428, #431.

Based on:

kysely/src/driver/database-connection.ts

Lines 23 to 34 in deea8e2

	/**
	* This is defined for insert, update, delete and merge queries and contains
	* the number of rows the query inserted/updated/deleted.
	*/
	readonly numAffectedRows?: bigint
	/**
	* This is defined for update queries and contains the number of rows
	* the query changed.
	* This is optional and only provided by some drivers like node-mysql2.
	*/
	readonly numChangedRows?: bigint

[vercel]

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	May 29, 2024 11:53am

[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.