ABatch represents a set of datamodification operations to be performed on tables in a database. Use of aBatch does not require creating an explicitSnapshot orTransaction. Untilcommit() is called on aBatch,no changes are propagated to the back-end.

Use Batch via BatchCheckout

Database.batch() creates aBatchCheckoutinstance to use as a context manager to handle creating and committing aBatch. TheBatchCheckout will automatically callcommit() if thewith block exitswithout raising an exception.

from google.cloud.spanner importKeySetclient =spanner.Client()instance =client.instance(INSTANCE_NAME)database = instance.database(DATABASE_NAME)to_delete = KeySet(keys=[    ('bharney@example.com',)    ('nonesuch@example.com',)])with database.batch() as batch:    batch.insert(        'citizens', columns=['email', 'first_name', 'last_name', 'age'],        values=[            ['phred@exammple.com', 'Phred', 'Phlyntstone', 32],            ['bharney@example.com', 'Bharney', 'Rhubble', 31],        ])    batch.update(        'citizens', columns=['email', 'age'],        values=[            ['phred@exammple.com', 33],            ['bharney@example.com', 32],        ])    ...    batch.delete('citizens', to_delete)

Inserting records using a Batch

Batch.insert() adds one or more new records to a table. This fails ifany of the records already exist.

batch.insert(    'citizens', columns=['email', 'first_name', 'last_name', 'age'],    values=[        ['phred@exammple.com', 'Phred', 'Phlyntstone', 32],        ['bharney@example.com', 'Bharney', 'Rhubble', 31],    ])

NOTE: Ensure that data being sent forSTRING columns uses a text string(str in Python 3;unicode in Python 2).

Additionally, if you are writing data intended for aBYTES column, youmust base64 encode it.

Update records using a Batch

Batch.update() updates one or more existing records in a table. This failsif any of the records do not already exist.

batch.update(    'citizens', columns=['email', 'age'],    values=[        ['phred@exammple.com', 33],        ['bharney@example.com', 32],    ])

NOTE: Ensure that data being sent forSTRING columns uses a text string(str in Python 3;unicode in Python 2).

Additionally, if you are writing data intended for aBYTES column, youmust base64 encode it.

Insert or update records using a Batch

Batch.insert_or_update() insertsor updates one or more records in atable. Existing rows have values for the supplied columns overwritten; othercolumn values are preserved.

batch.insert_or_update(    'citizens', columns=['email', 'first_name', 'last_name', 'age'],    values=[        ['phred@exammple.com', 'Phred', 'Phlyntstone', 31],        ['wylma@example.com', 'Wylma', 'Phlyntstone', 29],    ])

NOTE: Ensure that data being sent forSTRING columns uses a text string(str in Python 3;unicode in Python 2).

Additionally, if you are writing data intended for aBYTES column, youmust base64 encode it.

Replace records using a Batch

Batch.replace() insertsor updates one or more records in atable. Existing rows have values for the supplied columns overwritten; othercolumn values are set to null.

batch.replace(    'citizens', columns=['email', 'first_name', 'last_name', 'age'],    values=[        ['bharney@example.com', 'Bharney', 'Rhubble', 30],        ['bhettye@example.com', 'Bhettye', 'Rhubble', 30],    ])

NOTE: Ensure that data being sent forSTRING columns uses a text string(str in Python 3;unicode in Python 2).

Additionally, if you are writing data intended for aBYTES column, youmust base64 encode it.

Delete records using a Batch

Batch.delete() removes one or more records from a table. Attempting to deleterows that do not exist will not cause errors.

from google.cloud.spanner importKeySetto_delete = KeySet(keys=[    ('bharney@example.com',)    ('nonesuch@example.com',)])batch.delete('citizens', to_delete)

Commit changes for a Batch

After describing the modifications to be made to table data via theBatch.insert(),Batch.update(),Batch.insert_or_update(),Batch.replace(), andBatch.delete() methods above, send them tothe back-end by callingBatch.commit(), which makes theCommitAPI call.

You do not need to call this yourself asBatchCheckout will callthis method automatically upon exiting thewith block.

batch.commit()

Next Step

Next, learn aboutRead-only Transactions via Snapshots.