[DB-SIG] definition of .rowcount

[M.-A. Lemburg]

Michael Bayer wrote:
> Hey all -
> 
> Had a user today confused about the word "affected", when we describe the definition of cursor.rowcount.  Per pep-249:
> 
> .rowcount 
>           
>             This read-only attribute specifies the number of rows that
>             the last .execute*() produced (for DQL statements like
>             'select') or affected (for DML statements like 'update' or
>             'insert').
> 
> So as many of you know, MySQL has actually two options for how rowcount can be reported.  It can report the number of rows "found", that is, matched by the WHERE criterion of an UPDATE or DELETE statement, or it can report the number of rows that were actually updated or deleted, and here we're talking about an UPDATE that may or may not have had a net change in row value.   The Python MySQL drivers tend to default to the latter.    Every other database/DBAPI I've worked with only offers the former.
> 
> Question is, is there an intent behind the term "affected" here?   
> 
> If it is intentionally vague, could there be some more explicit phrasing to that effect, "by 'affected' we mean whatever the underlying driver interprets this to mean" or something along those lines ?  Or if it really means, "number of rows matched", should the word "affected" be altered here ?

It is not really vague. For SELECT statements it refers to the number
of rows matching the query and ready to be fetched. For UPDATE, DELETE
and other statements manipulating rows it refers to the number of rows
updated, deleted or inserted.

Whether or not rows that actually changed or all rows touched by
an UPDATE are counted is backend dependent. The latter is what
most databases return (if they return any value at all).

The term "affected" is a standard term used for describing the
row count.

See e.g. the ODBC API SQLRowCount:

http://msdn.microsoft.com/en-us/library/windows/desktop/ms711835%28v=vs.85%29.aspx

-- 
Marc-Andre Lemburg
eGenix.com

Professional Python Services directly from the Source
>>> Python/Zope Consulting and Support ...        http://www.egenix.com/
>>> mxODBC.Zope.Database.Adapter ...             http://zope.egenix.com/
>>> mxODBC, mxDateTime, mxTextTools ...        http://python.egenix.com/
________________________________________________________________________

::: Try our new mxODBC.Connect Python Database Interface for free ! ::::


   eGenix.com Software, Skills and Services GmbH  Pastor-Loeh-Str.48
    D-40764 Langenfeld, Germany. CEO Dipl.-Math. Marc-Andre Lemburg
           Registered at Amtsgericht Duesseldorf: HRB 46611
               http://www.egenix.com/company/contact/