A ~google.cloud.spanner_v1.batch.Batch
represents a set of data modification operations to be performed on tables in a database. Use of a Batch
does not require creating an explicit ~google.cloud.spanner_v1.snapshot.Snapshot
or ~google.cloud.spanner_v1.transaction.Transaction
. Until ~google.cloud.spanner_v1.batch.Batch.commit
is called on a Batch
, no changes are propagated to the back-end.
Database.batch
creates a ~google.cloud.spanner_v1.database.BatchCheckout
instance to use as a context manager to handle creating and committing a ~google.cloud.spanner_v1.batch.Batch
. The BatchCheckout
will automatically call ~google.cloud.spanner_v1.batch.Batch.commit
if the with
block exits without raising an exception.
from google.cloud.spanner import KeySet
client = 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)
Batch.insert
adds one or more new records to a table. This fails if any 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 for STRING
columns uses a text string (str
in Python 3; unicode
in Python 2).
Additionally, if you are writing data intended for a BYTES
column, you must base64 encode it.
Batch.update
updates one or more existing records in a table. This fails if 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 for STRING
columns uses a text string (str
in Python 3; unicode
in Python 2).
Additionally, if you are writing data intended for a BYTES
column, you must base64 encode it.
Batch.insert_or_update
inserts or updates one or more records in a table. Existing rows have values for the supplied columns overwritten; other column 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 for STRING
columns uses a text string (str
in Python 3; unicode
in Python 2).
Additionally, if you are writing data intended for a BYTES
column, you must base64 encode it.
Batch.replace
inserts or updates one or more records in a table. Existing rows have values for the supplied columns overwritten; other column 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 for STRING
columns uses a text string (str
in Python 3; unicode
in Python 2).
Additionally, if you are writing data intended for a BYTES
column, you must base64 encode it.
Batch.delete
removes one or more records from a table. Attempting to delete rows that do not exist will not cause errors.
from google.cloud.spanner import KeySet
to_delete = KeySet(keys=[
('bharney@example.com',)
('nonesuch@example.com',)
])
batch.delete('citizens', to_delete)
After describing the modifications to be made to table data via the Batch.insert
, Batch.update
, Batch.insert_or_update
, Batch.replace
, and Batch.delete
methods above, send them to the back-end by calling Batch.commit
, which makes the Commit
API call.
You do not need to call this yourself as ~google.cloud.spanner_v1.database.BatchCheckout
will call this method automatically upon exiting the with
block.
batch.commit()
Next, learn about snapshot-usage
.