[SQL-CVS] r4307 - SQLObject/trunk/docs

[<sub...@co...>]

Author: phd
Date: Thu Dec 16 20:05:14 2010
New Revision: 4307

Log:
Fast mass-insertion using sqlbuilder.Insert.

Modified:
   SQLObject/trunk/docs/FAQ.txt
   SQLObject/trunk/docs/SQLBuilder.txt

Modified: SQLObject/trunk/docs/FAQ.txt
==============================================================================
--- SQLObject/trunk/docs/FAQ.txt	Thu Dec 16 19:43:02 2010	(r4306)
+++ SQLObject/trunk/docs/FAQ.txt	Thu Dec 16 20:05:14 2010	(r4307)
@@ -551,6 +551,22 @@
 
 You can use a lower-level machinery available in SQLBuilder_.
 
+How to do mass-insertion?
+-------------------------
+
+Mass-insertion using high-level API in SQLObject is slow. There are many
+reasons for that. First, on creation SQLObject instances pass all values
+through validators/converters which is convenient but takes time.
+Second, after an INSERT query SQLObject executes a SELECT query to get
+back autogenerated values (id and timestamps). Third, there is caching
+and cache maintaining. Most of this is unnecessary for mass-insertion,
+hence high-level API is unsuitable.
+
+Less convenient (no validators) but much faster API is Insert_ from
+SQLBuilder_.
+
+.. _Insert: SQLBuilder.html#insert
+
 How can I specify the MySQL engine to use, or tweak other SQL-engine specific features?
 ---------------------------------------------------------------------------------------
 

Modified: SQLObject/trunk/docs/SQLBuilder.txt
==============================================================================
--- SQLObject/trunk/docs/SQLBuilder.txt	Thu Dec 16 19:43:02 2010	(r4306)
+++ SQLObject/trunk/docs/SQLBuilder.txt	Thu Dec 16 20:05:14 2010	(r4307)
@@ -2,6 +2,8 @@
 SQLBuilder
 ``````````
 
+.. contents::
+
 A number of variables from SQLBuilder are included with ``from
 sqlobject import *`` -- see the `relevant SQLObject documentation`_
 for more.  Its functionality is also available through the special
@@ -168,6 +170,10 @@
     >> query = connection.sqlrepr(insert)
     >> connection.query(query)
 
+Instances of the class work fast and thus are suitable for
+mass-insertion. If one needs to populate a database with SQLObject
+running a lot of INSERT queries this class is the way to go.
+
 Nested SQL statements (subqueries)
 ==================================