Batching Modifications#

A Batch represents a set of data modification operations to be performed on tables in a dataset. Use of a Batch does not require creating an explicit Snapshot or Transaction. Until commit() is called on a Batch, no changes are propagated to the back-end.

Starting a Batch#

batch = session.batch()

Inserting records using a Batch#

Batch.insert() adds one or more new records to a table. Fails if any of the records already exists.

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. Fails if any of the records does 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. Non-existent rows do not cause errors.

batch.delete('citizens',
    keyset['bharney@example.com', 'nonesuch@example.com'])

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.

batch.commit()

Use a Batch as a Context Manager#

Rather than calling Batch.commit() manually, you can use the Batch instance as a context manager, and have it called automatically if the with block exits without raising an exception.

with session.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',
        keyset['bharney@example.com', 'nonesuch@example.com'])

Next Step#

Next, learn about Read-only Transactions via Snapshots.