- 3.51.0 (latest)
- 3.50.1
- 3.46.0
- 3.45.0
- 3.44.0
- 3.43.0
- 3.42.0
- 3.41.0
- 3.40.1
- 3.39.0
- 3.38.0
- 3.37.0
- 3.36.0
- 3.35.1
- 3.34.0
- 3.33.0
- 3.32.0
- 3.31.0
- 3.30.0
- 3.29.0
- 3.28.0
- 3.27.1
- 3.26.0
- 3.25.0
- 3.24.0
- 3.23.0
- 3.22.2
- 3.21.0
- 3.20.0
- 3.19.0
- 3.18.0
- 3.17.0
- 3.16.0
- 3.15.1
- 3.14.1
- 3.13.0
- 3.12.1
- 3.11.1
- 3.10.0
- 3.9.0
- 3.8.0
- 3.7.0
- 3.6.0
- 3.5.0
- 3.4.0
- 3.3.0
- 3.2.0
- 3.1.0
- 3.0.0
- 2.1.1
- 2.0.0
- 1.19.3
- 1.18.0
- 1.17.1
- 1.16.0
- 1.15.1
- 1.14.0
- 1.13.0
- 1.12.0
- 1.11.0
- 1.10.0
Transaction(session)
Implement read-write transaction semantics for a session.
Parameter |
|
---|---|
Name | Description |
session |
Session
the session used to perform the commit |
Methods
__enter__
__enter__()
Begin with
block.
__exit__
__exit__(exc_type, exc_val, exc_tb)
End with
block.
batch_update
batch_update(
statements,
request_options=None,
*,
retry=_MethodDefault._DEFAULT_VALUE,
timeout=_MethodDefault._DEFAULT_VALUE
)
Perform a batch of DML statements via an ExecuteBatchDml
request.
Parameters | |
---|---|
Name | Description |
statements |
Sequence[Union[ str, Tuple[str, Dict[str, Any], Dict[str, Union[dict, .types.Type]]]]]
List of DML statements, with optional params / param types. If passed, 'params' is a dict mapping names to the values for parameter replacement. Keys must match the names used in the corresponding DML statement. If 'params' is passed, 'param_types' must also be passed, as a dict mapping names to the type of value passed in 'params'. |
request_options |
RequestOptions
(Optional) Common options for this request. If a dict is provided, it must be of the same form as the protobuf message RequestOptions. |
retry |
(Optional) The retry settings for this request. |
timeout |
float
(Optional) The timeout for this request. |
Returns | |
---|---|
Type | Description |
Tuple(status, Sequence[int]) |
Status code, plus counts of rows affected by each completed DML statement. Note that if the status code is not OK , the statement triggering the error will not have an entry in the list, nor will any statements following that one. |
begin
begin()
Begin a transaction on the database.
Exceptions | |
---|---|
Type | Description |
ValueError |
if the transaction is already begun, committed, or rolled back. |
Returns | |
---|---|
Type | Description |
bytes |
the ID for the newly-begun transaction. |
commit
commit(return_commit_stats=False, request_options=None, max_commit_delay=None)
Commit mutations to the database.
Parameters | |
---|---|
Name | Description |
return_commit_stats |
bool
If true, the response will return commit stats which can be accessed though commit_stats. |
request_options |
RequestOptions
(Optional) Common options for this request. If a dict is provided, it must be of the same form as the protobuf message RequestOptions. |
max_commit_delay |
(Optional) The amount of latency this request is willing to incur in order to improve throughput. MaxCommitDelay. |
Exceptions | |
---|---|
Type | Description |
ValueError |
if there are no mutations to commit. |
Returns | |
---|---|
Type | Description |
datetime |
timestamp of the committed changes. |
delete
delete(table, keyset)
Delete one or more table rows.
Parameters | |
---|---|
Name | Description |
table |
str
Name of the table to be modified. |
keyset |
Keyset
Keys/ranges identifying rows to delete. |
execute_sql
execute_sql(
sql,
params=None,
param_types=None,
query_mode=None,
query_options=None,
request_options=None,
partition=None,
retry=_MethodDefault._DEFAULT_VALUE,
timeout=_MethodDefault._DEFAULT_VALUE,
data_boost_enabled=False,
directed_read_options=None,
column_info=None,
)
Perform an ExecuteStreamingSql
API request.
Parameters | |
---|---|
Name | Description |
sql |
str
SQL query statement |
params |
dict, {str -> column value}
values for parameter replacement. Keys must match the names used in |
param_types |
dict[str -> Union[dict, .types.Type]]
(Optional) maps explicit types for one or more param values; required if parameters are passed. |
query_mode |
QueryMode
Mode governing return of results / query plan. See: |
query_options |
QueryOptions or
(Optional) Query optimizer configuration to use for the given query. If a dict is provided, it must be of the same form as the protobuf message QueryOptions |
request_options |
RequestOptions
(Optional) Common options for this request. If a dict is provided, it must be of the same form as the protobuf message RequestOptions. |
partition |
bytes
(Optional) one of the partition tokens returned from |
retry |
(Optional) The retry settings for this request. |
timeout |
float
(Optional) The timeout for this request. |
directed_read_options |
DirectedReadOptions or
(Optional) Request level option used to set the directed_read_options for all ReadRequests and ExecuteSqlRequests that indicates which replicas or regions should be used for non-transactional reads or queries. |
column_info |
dict
(Optional) dict of mapping between column names and additional column information. An object where column names as keys and custom objects as corresponding values for deserialization. It's specifically useful for data types like protobuf where deserialization logic is on user-specific code. When provided, the custom object enables deserialization of backend-received column data. If not provided, data remains serialized as bytes for Proto Messages and integer for Proto Enums. |
Exceptions | |
---|---|
Type | Description |
ValueError |
for reuse of single-use snapshots, or if a transaction ID is already pending for multiple-use snapshots. |
Returns | |
---|---|
Type | Description |
StreamedResultSet |
a result set instance which can be used to consume rows. |
execute_update
execute_update(
dml,
params=None,
param_types=None,
query_mode=None,
query_options=None,
request_options=None,
*,
retry=_MethodDefault._DEFAULT_VALUE,
timeout=_MethodDefault._DEFAULT_VALUE
)
Perform an ExecuteSql
API request with DML.
Parameters | |
---|---|
Name | Description |
dml |
str
SQL DML statement |
params |
dict, {str -> column value}
values for parameter replacement. Keys must match the names used in |
param_types |
dict[str -> Union[dict, .types.Type]]
(Optional) maps explicit types for one or more param values; required if parameters are passed. |
query_mode |
QueryMode
Mode governing return of results / query plan. See: |
query_options |
QueryOptions or
(Optional) Options that are provided for query plan stability. |
request_options |
RequestOptions
(Optional) Common options for this request. If a dict is provided, it must be of the same form as the protobuf message RequestOptions. |
retry |
(Optional) The retry settings for this request. |
timeout |
float
(Optional) The timeout for this request. |
Returns | |
---|---|
Type | Description |
int |
Count of rows affected by the DML statement. |
insert
insert(table, columns, values)
Insert one or more new table rows.
Parameters | |
---|---|
Name | Description |
table |
str
Name of the table to be modified. |
columns |
list of str
Name of the table columns to be modified. |
values |
list of lists
Values to be modified. |
insert_or_update
insert_or_update(table, columns, values)
Insert/update one or more table rows.
Parameters | |
---|---|
Name | Description |
table |
str
Name of the table to be modified. |
columns |
list of str
Name of the table columns to be modified. |
values |
list of lists
Values to be modified. |
partition_query
partition_query(
sql,
params=None,
param_types=None,
partition_size_bytes=None,
max_partitions=None,
*,
retry=_MethodDefault._DEFAULT_VALUE,
timeout=_MethodDefault._DEFAULT_VALUE
)
Perform a PartitionQuery
API request.
Parameters | |
---|---|
Name | Description |
sql |
str
SQL query statement |
params |
dict, {str -> column value}
values for parameter replacement. Keys must match the names used in |
param_types |
dict[str -> Union[dict, .types.Type]]
(Optional) maps explicit types for one or more param values; required if parameters are passed. |
partition_size_bytes |
int
(Optional) desired size for each partition generated. The service uses this as a hint, the actual partition size may differ. |
max_partitions |
int
(Optional) desired maximum number of partitions generated. The service uses this as a hint, the actual number of partitions may differ. |
retry |
(Optional) The retry settings for this request. |
timeout |
float
(Optional) The timeout for this request. |
Exceptions | |
---|---|
Type | Description |
ValueError |
for single-use snapshots, or if a transaction ID is already associated with the snapshot. |
Returns | |
---|---|
Type | Description |
iterable of bytes |
a sequence of partition tokens |
partition_read
partition_read(
table,
columns,
keyset,
index="",
partition_size_bytes=None,
max_partitions=None,
*,
retry=_MethodDefault._DEFAULT_VALUE,
timeout=_MethodDefault._DEFAULT_VALUE
)
Perform a PartitionRead
API request for rows in a table.
Parameters | |
---|---|
Name | Description |
table |
str
name of the table from which to fetch data |
columns |
list of str
names of columns to be retrieved |
keyset |
KeySet
keys / ranges identifying rows to be retrieved |
index |
str
(Optional) name of index to use, rather than the table's primary key |
partition_size_bytes |
int
(Optional) desired size for each partition generated. The service uses this as a hint, the actual partition size may differ. |
max_partitions |
int
(Optional) desired maximum number of partitions generated. The service uses this as a hint, the actual number of partitions may differ. |
retry |
(Optional) The retry settings for this request. |
timeout |
float
(Optional) The timeout for this request. |
Exceptions | |
---|---|
Type | Description |
ValueError |
for single-use snapshots, or if a transaction ID is already associated with the snapshot. |
Returns | |
---|---|
Type | Description |
iterable of bytes |
a sequence of partition tokens |
read
read(
table,
columns,
keyset,
index="",
limit=0,
partition=None,
request_options=None,
data_boost_enabled=False,
directed_read_options=None,
*,
retry=_MethodDefault._DEFAULT_VALUE,
timeout=_MethodDefault._DEFAULT_VALUE,
column_info=None
)
Perform a StreamingRead
API request for rows in a table.
Parameters | |
---|---|
Name | Description |
table |
str
name of the table from which to fetch data |
columns |
list of str
names of columns to be retrieved |
keyset |
KeySet
keys / ranges identifying rows to be retrieved |
index |
str
(Optional) name of index to use, rather than the table's primary key |
limit |
int
(Optional) maximum number of rows to return. Incompatible with |
partition |
bytes
(Optional) one of the partition tokens returned from |
request_options |
RequestOptions
(Optional) Common options for this request. If a dict is provided, it must be of the same form as the protobuf message RequestOptions. Please note, the |
retry |
(Optional) The retry settings for this request. |
timeout |
float
(Optional) The timeout for this request. |
directed_read_options |
DirectedReadOptions or
(Optional) Request level option used to set the directed_read_options for all ReadRequests and ExecuteSqlRequests that indicates which replicas or regions should be used for non-transactional reads or queries. |
column_info |
dict
(Optional) dict of mapping between column names and additional column information. An object where column names as keys and custom objects as corresponding values for deserialization. It's specifically useful for data types like protobuf where deserialization logic is on user-specific code. When provided, the custom object enables deserialization of backend-received column data. If not provided, data remains serialized as bytes for Proto Messages and integer for Proto Enums. |
Exceptions | |
---|---|
Type | Description |
ValueError |
for reuse of single-use snapshots, or if a transaction ID is already pending for multiple-use snapshots. |
Returns | |
---|---|
Type | Description |
StreamedResultSet |
a result set instance which can be used to consume rows. |
replace
replace(table, columns, values)
Replace one or more table rows.
Parameters | |
---|---|
Name | Description |
table |
str
Name of the table to be modified. |
columns |
list of str
Name of the table columns to be modified. |
values |
list of lists
Values to be modified. |
rollback
rollback()
Roll back a transaction on the database.
update
update(table, columns, values)
Update one or more existing table rows.
Parameters | |
---|---|
Name | Description |
table |
str
Name of the table to be modified. |
columns |
list of str
Name of the table columns to be modified. |
values |
list of lists
Values to be modified. |