batch-usage.rst

Batching Modifications

A ~google.cloud.spanner.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.snapshot.Snapshot or ~google.cloud.spanner.transaction.Transaction. Until ~google.cloud.spanner.batch.Batch.commit is called on a Batch, no changes are propagated to the back-end.

Use Batch via BatchCheckout

Database.batch creates a BatchCheckout instance to use as a context manager to handle creating and committing a Batch. The BatchCheckout will automatically call ~google.cloud.spanner.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)

Inserting records using a Batch

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.

Update records using a Batch

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.

Insert or update records using a Batch

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.

Replace records using a Batch

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.

Delete records using a Batch

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)

Commit changes for a Batch

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.

Yu do not need to call this yourself as BatchCheckout will call this method automatically upon exiting the with block.

batch.commit()

Next Step

Next, learn about snapshot-usage.