Google Cloud Datastore v1 API - Class DatastoreTransactionImpl (4.12.0)

public sealed class DatastoreTransactionImpl : DatastoreTransaction, IDisposable

Reference documentation and code samples for the Google Cloud Datastore v1 API class DatastoreTransactionImpl.

Production implementation of DatastoreTransaction, using a DatastoreClient to implement the operations.

Inheritance

object > DatastoreTransaction > DatastoreTransactionImpl

Implements

IDisposable

Namespace

Google.Cloud.Datastore.V1

Assembly

Google.Cloud.Datastore.V1.dll

Constructors

DatastoreTransactionImpl(DatastoreClient, string, string, ByteString)

public DatastoreTransactionImpl(DatastoreClient client, string projectId, string namespaceId, ByteString transactionId)

Constructs a DatastoreTransactionImpl from a client, project ID and transaction ID.

Parameters
Name Description
client DatastoreClient

The client to use for Datastore operations. Must not be null.

projectId string

The ID of the project of the Datastore operations. Must not be null.

namespaceId string

The ID of the namespace which is combined with projectId to form a partition ID to use in query operations. May be null.

transactionId ByteString

The transaction obtained by an earlier BeginTransaction(string, CallSettings) or the asynchronous equivalent. Must not be null

Remarks

While this can be constructed manually, the expectation is that instances of this class are obtained via BeginTransaction(CallSettings) or BeginTransactionAsync(CallSettings).

DatastoreTransactionImpl(DatastoreClient, string, string, string, ByteString)

public DatastoreTransactionImpl(DatastoreClient client, string projectId, string namespaceId, string databaseId, ByteString transactionId)

Constructs a DatastoreTransactionImpl from a client, project ID and transaction ID.

Parameters
Name Description
client DatastoreClient

The client to use for Datastore operations. Must not be null.

projectId string

The ID of the project of the Datastore operations. Must not be null.

namespaceId string

The ID of the namespace which is combined with projectId and databaseId to form a partition ID to use in query operations. May be null.

databaseId string

The ID of the databse which is combined with projectId and namespaceId to form a partition ID to use in query operations. May be null.

transactionId ByteString

The transaction obtained by an earlier BeginTransaction(string, CallSettings) or the asynchronous equivalent. Must not be null

Remarks

While this can be constructed manually, the expectation is that instances of this class are obtained via BeginTransaction(CallSettings) or BeginTransactionAsync(CallSettings).

Properties

TransactionId

public override ByteString TransactionId { get; }

The ID of the transaction, used implicitly in operations performed with this object.

Property Value
Type Description
ByteString
Overrides

Methods

Commit(CallSettings)

public override CommitResponse Commit(CallSettings callSettings = null)

Commits all mutations in this transaction.

Parameter
Name Description
callSettings CallSettings
Returns
Type Description
CommitResponse

The response from the commit operation. This can be used to determine server-allocated keys.

Overrides Remarks

Any entities with incomplete keys that are assigned keys by this operation will be updated in memory with the server-allocated keys.

Datastore limits the number of entities that can be modified in a Commit operation, and therefore one transaction. When modifying a large number of entities, partition the changes into multiple transactions. See Datastore limits for more details on Datastore limits.

Exceptions
Type Description
InvalidOperationException

The transaction has already been committed or rolled back.

CommitAsync(CallSettings)

public override Task<CommitResponse> CommitAsync(CallSettings callSettings = null)

Commits all mutations in this transaction asynchronously.

Parameter
Name Description
callSettings CallSettings

If not null, applies overrides to RPC calls.

Returns
Type Description
TaskCommitResponse

The response from the commit operation. This can be used to determine server-allocated keys.

Overrides Remarks

Any entities with incomplete keys that are assigned keys by this operation will be updated in memory with the server-allocated keys.

Datastore limits the number of entities that can be modified in a Commit operation, and therefore one transaction. When modifying a large number of entities, partition the changes into multiple transactions. See Datastore limits for more details on Datastore limits.

Exceptions
Type Description
InvalidOperationException

The transaction has already been committed or rolled back.

Delete(IEnumerable<Entity>)

public override void Delete(IEnumerable<Entity> entities)

Adds delete operations for all the specified keys to this transaction.

Parameter
Name Description
entities IEnumerableEntity

The entities to delete. Must not be null.

Overrides

Delete(IEnumerable<Key>)

public override void Delete(IEnumerable<Key> keys)

Adds deletion operations for all the specified keys to this transaction.

Parameter
Name Description
keys IEnumerableKey

The keys to delete. Must not be null.

Overrides

Dispose()

public override void Dispose()

If the transaction has already been committed, this operation is a no-op. Otherwise, it rolls back the transaction.

Overrides

Insert(IEnumerable<Entity>)

public override void Insert(IEnumerable<Entity> entities)

Adds insert operations for all the specified keys to this transaction.

Parameter
Name Description
entities IEnumerableEntity

The entities to insert. Must not be null.

Overrides

Lookup(IEnumerable<Key>, CallSettings)

public override IReadOnlyList<Entity> Lookup(IEnumerable<Key> keys, CallSettings callSettings = null)

Looks up a collection of entities by key.

Parameters
Name Description
keys IEnumerableKey

The keys to look up. Must not be null, and every element must be non-null and refer to a complete key.

callSettings CallSettings

If not null, applies overrides to RPC calls.

Returns
Type Description
IReadOnlyListEntity

A collection of entities with the same size as keys, containing corresponding entity references, or null where the key was not found.

Overrides Remarks

This call may perform multiple RPC operations in order to look up all keys.

LookupAsync(IEnumerable<Key>, CallSettings)

public override Task<IReadOnlyList<Entity>> LookupAsync(IEnumerable<Key> keys, CallSettings callSettings = null)

Looks up a collection of entities by key asynchronously.

Parameters
Name Description
keys IEnumerableKey

The keys to look up. Must not be null, and every element must be non-null and refer to a complete key.

callSettings CallSettings

If not null, applies overrides to RPC calls.

Returns
Type Description
TaskIReadOnlyListEntity

A collection of entities with the same size as keys, containing corresponding entity references, or null where the key was not found.

Overrides Remarks

This call may perform multiple RPC operations in order to look up all keys.

Rollback(CallSettings)

public override RollbackResponse Rollback(CallSettings callSettings = null)

Rolls back this transaction.

Parameter
Name Description
callSettings CallSettings

If not null, applies overrides to RPC calls.

Returns
Type Description
RollbackResponse
Overrides Remarks

This method is rarely useful explicitly; the Dispose() method rolls back the transaction if it is still active, so a using statement is normally preferable to this.

Exceptions
Type Description
InvalidOperationException

The transaction has already been committed or rolled back.

RollbackAsync(CallSettings)

public override Task<RollbackResponse> RollbackAsync(CallSettings callSettings = null)

Rolls back this transaction asynchronously.

Parameter
Name Description
callSettings CallSettings

If not null, applies overrides to RPC calls.

Returns
Type Description
TaskRollbackResponse
Overrides Remarks

This method is rarely useful explicitly; the Dispose() method rolls back the transaction if it is still active, so a using statement is normally preferable to this.

Exceptions
Type Description
InvalidOperationException

The transaction has already been committed or rolled back.

RunAggregationQuery(AggregationQuery, CallSettings)

public override AggregationQueryResults RunAggregationQuery(AggregationQuery query, CallSettings callSettings = null)

Runs the given AggregationQuery in this transaction.

Parameters
Name Description
query AggregationQuery

The AggregationQuery to execute. Must not be null.

callSettings CallSettings

If not null, applies overrides to RPC calls.

Returns
Type Description
AggregationQueryResults

The result of aggregation query.

Overrides

RunAggregationQuery(GqlQuery, CallSettings)

public override AggregationQueryResults RunAggregationQuery(GqlQuery query, CallSettings callSettings = null)

Runs the given GqlQuery in this transaction.

Parameters
Name Description
query GqlQuery

The GqlQuery to execute. Must not be null.

callSettings CallSettings

If not null, applies overrides to RPC calls.

Returns
Type Description
AggregationQueryResults

The result of aggregation query.

Overrides

RunAggregationQueryAsync(AggregationQuery, CallSettings)

public override Task<AggregationQueryResults> RunAggregationQueryAsync(AggregationQuery query, CallSettings callSettings = null)

Runs the given AggregationQuery in this transaction.

Parameters
Name Description
query AggregationQuery

The AggregationQuery to execute. Must not be null.

callSettings CallSettings

If not null, applies overrides to RPC calls.

Returns
Type Description
TaskAggregationQueryResults

A task representing the asynchronous operation. The result of the task is the result of the aggregation query.

Overrides

RunAggregationQueryAsync(GqlQuery, CallSettings)

public override Task<AggregationQueryResults> RunAggregationQueryAsync(GqlQuery query, CallSettings callSettings = null)

Runs the given GqlQuery in this transaction.

Parameters
Name Description
query GqlQuery

The GqlQuery to execute. Must not be null.

callSettings CallSettings

If not null, applies overrides to RPC calls.

Returns
Type Description
TaskAggregationQueryResults

A task representing the asynchronous operation. The result of the task is the result of the aggregation query.

Overrides

RunQueryLazily(GqlQuery, CallSettings)

public override LazyDatastoreQuery RunQueryLazily(GqlQuery gqlQuery, CallSettings callSettings = null)

Lazily executes the given GQL query in this transaction.

Parameters
Name Description
gqlQuery GqlQuery

The query to execute. Must not be null.

callSettings CallSettings

If not null, applies overrides to RPC calls.

Returns
Type Description
LazyDatastoreQuery

A LazyDatastoreQuery representing the result of the query.

Overrides Remarks

Using a transaction ensures that a commit operation will fail if any of the entities returned by this query have been modified while the transaction is active. Note that modifications performed as part of this operation are not reflected in the query results.

The results are requested lazily: no API calls will be made until the application starts iterating over the results. Iterating over the same LazyDatastoreQuery object multiple times will execute the query again, potentially returning different results.

RunQueryLazily(Query, CallSettings)

public override LazyDatastoreQuery RunQueryLazily(Query query, CallSettings callSettings = null)

Lazily executes the given structured query in this transaction.

Parameters
Name Description
query Query

The query to execute. Must not be null.

callSettings CallSettings

If not null, applies overrides to RPC calls.

Returns
Type Description
LazyDatastoreQuery

A LazyDatastoreQuery representing the the lazy query results.

Overrides Remarks

Using a transaction ensures that a commit operation will fail if any of the entities returned by this query have been modified while the transaction is active. Note that modifications performed as part of this operation are not reflected in the query results.

The results are requested lazily: no API calls will be made until the application starts iterating over the results. Iterating over the same LazyDatastoreQuery object multiple times will execute the query again, potentially returning different results.

RunQueryLazilyAsync(GqlQuery, CallSettings)

public override AsyncLazyDatastoreQuery RunQueryLazilyAsync(GqlQuery gqlQuery, CallSettings callSettings = null)

Lazily executes the given structured query in this transaction for asynchronous consumption.

Parameters
Name Description
gqlQuery GqlQuery

The query to execute. Must not be null.

callSettings CallSettings

If not null, applies overrides to RPC calls.

Returns
Type Description
AsyncLazyDatastoreQuery

An AsyncLazyDatastoreQuery representing the result of the query.

Overrides Remarks

Using a transaction ensures that a commit operation will fail if any of the entities returned by this query have been modified while the transaction is active. Note that modifications performed as part of this operation are not reflected in the query results.

The results are requested lazily: no API calls will be made until the application starts iterating over the results. Iterating over the same LazyDatastoreQuery object multiple times will execute the query again, potentially returning different results.

RunQueryLazilyAsync(Query, CallSettings)

public override AsyncLazyDatastoreQuery RunQueryLazilyAsync(Query query, CallSettings callSettings = null)

Lazily executes the given structured query in this transaction for asynchronous consumption.

Parameters
Name Description
query Query

The query to execute. Must not be null.

callSettings CallSettings

If not null, applies overrides to RPC calls.

Returns
Type Description
AsyncLazyDatastoreQuery

An AsyncLazyDatastoreQuery representing the result of the query.

Overrides Remarks

Using a transaction ensures that a commit operation will fail if any of the entities returned by this query have been modified while the transaction is active. Note that modifications performed as part of this operation are not reflected in the query results.

The results are requested lazily: no API calls will be made until the application starts iterating over the results. Iterating over the same LazyDatastoreQuery object multiple times will execute the query again, potentially returning different results.

Update(IEnumerable<Entity>)

public override void Update(IEnumerable<Entity> entities)

Adds update operations for all the specified keys to this transaction.

Parameter
Name Description
entities IEnumerableEntity

The entities to update. Must not be null.

Overrides

Upsert(IEnumerable<Entity>)

public override void Upsert(IEnumerable<Entity> entities)

Adds upsert operations for all the specified keys to this transaction.

Parameter
Name Description
entities IEnumerableEntity

The entities to upsert. Must not be null.

Overrides