public abstract class DatastoreTransaction : IDisposable
Reference documentation and code samples for the Google Cloud Datastore v1 API class DatastoreTransaction.
Convenience wrapper around a Datastore transaction. All mutation operations (Insert(IEnumerable<Entity>), Delete(IEnumerable<Key>), Update(IEnumerable<Entity>) and Upsert(IEnumerable<Entity>)) merely add to a list of mutations which are performed in a single Commit(CallSettings) or CommitAsync(CallSettings) operation. This means the mutation methods are all synchronous and do not take call settings, as they don't perform any API operations.
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.
Even though transactions aren't inherently related to a specific partition ID, the expected usage is that queries run inside a transaction are likely to be in a single partition, specified in a DatastoreDb used to create the transaction.
Disposing of a transaction calls Rollback(CallSettings) if the transaction has not already been committed or rolled back.
This is an abstract class, implemented by DatastoreTransactionImpl for production use. Users creating their own DatastoreDb subclasses may choose to create fake implementations for testing purposes. There are no abstract methods in this class; instead, all methods either delegate to another or throw NotImplementedException.
Implements
IDisposableDerived Types
Namespace
Google.Cloud.Datastore.V1Assembly
Google.Cloud.Datastore.V1.dll
Properties
TransactionId
public virtual ByteString TransactionId { get; }
The ID of the transaction, used implicitly in operations performed with this object.
Property Value | |
---|---|
Type | Description |
ByteString |
Methods
Commit(CallSettings)
public virtual 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. |
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.
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("message");
using (DatastoreTransaction transaction = db.BeginTransaction())
{
Entity entity = new Entity
{
Key = keyFactory.CreateIncompleteKey(),
["message"] = "Hello"
};
// This adds the entity to a collection in memory: nothing
// is sent to the server.
transaction.Insert(entity);
// Without the Commit call, the transaction will automatically
// be rolled back. The Commit call performs all the mutations
// within the transaction.
transaction.Commit();
}
Exceptions | |
---|---|
Type | Description |
InvalidOperationException | The transaction has already been committed or rolled back. |
CommitAsync(CallSettings)
public virtual 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. |
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.
See Commit for a synchronous example.
Exceptions | |
---|---|
Type | Description |
InvalidOperationException | The transaction has already been committed or rolled back. |
Create(DatastoreClient, string, string, ByteString)
public static DatastoreTransaction Create(DatastoreClient client, string projectId, string namespaceId, ByteString transactionId)
Constructs an instance of DatastoreClientImpl with the given arguments. Clients using the DatastoreDb abstraction layer would normally call BeginTransaction(CallSettings) or BeginTransactionAsync(CallSettings) instead of calling this method directly.
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 |
transactionId | ByteString The transaction obtained by an earlier BeginTransaction(string, CallSettings) or the asynchronous equivalent. Must not be null |
Returns | |
---|---|
Type | Description |
DatastoreTransaction | A DatastoreTransaction representation of the specified transaction. |
Create(DatastoreClient, string, string, string, ByteString)
public static DatastoreTransaction Create(DatastoreClient client, string projectId, string namespaceId, string databaseId, ByteString transactionId)
Constructs an instance of DatastoreClientImpl with the given arguments. Clients using the DatastoreDb abstraction layer would normally call BeginTransaction(CallSettings) or BeginTransactionAsync(CallSettings) instead of calling this method directly.
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 |
databaseId | string The ID of the database which is combined with |
transactionId | ByteString The transaction obtained by an earlier BeginTransaction(string, CallSettings) or the asynchronous equivalent. Must not be null |
Returns | |
---|---|
Type | Description |
DatastoreTransaction | A DatastoreTransaction representation of the specified transaction. |
Delete(params Entity[])
public virtual void Delete(params Entity[] entities)
Adds delete operations for all the specified keys to this transaction.
Parameter | |
---|---|
Name | Description |
entities | Entity The entities to delete. Must not be null. |
This method delegates to Delete(IEnumerable<Entity>).
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("message");
Entity message = new Entity
{
Key = keyFactory.CreateIncompleteKey(),
["text"] = "Hello",
};
db.Insert(message);
Entity fetchedBeforeDeletion = db.Lookup(message.Key);
using (DatastoreTransaction transaction = db.BeginTransaction())
{
// This adds the entity key to a collection of mutations in memory: nothing
// is sent to the server. Only the key from the entity is used to determine what to delete.
// If you already have the key but not the entity, use Delete(Key[]) or
// a similar overload.
transaction.Delete(message);
// Without the Commit call, the transaction will automatically
// be rolled back. The Commit call performs all the mutations
// within the transaction.
transaction.Commit();
}
Entity fetchedAfterDeletion = db.Lookup(message.Key);
Console.WriteLine($"Entity exists before deletion? {fetchedBeforeDeletion != null}");
Console.WriteLine($"Entity exists after deletion? {fetchedAfterDeletion != null}");
Delete(params Key[])
public virtual void Delete(params Key[] keys)
Adds deletion operations for all the specified keys to this transaction.
Parameter | |
---|---|
Name | Description |
keys | Key The keys to delete. Must not be null. |
This method delegates to Delete(IEnumerable<Key>).
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("message");
Entity message = new Entity
{
Key = keyFactory.CreateIncompleteKey(),
["text"] = "Hello",
};
Key key = db.Insert(message);
Entity fetchedBeforeDeletion = db.Lookup(key);
using (DatastoreTransaction transaction = db.BeginTransaction())
{
// This adds the key to a collection of mutations in memory: nothing
// is sent to the server. Only the key is required to determine what to delete.
// If you have an entity with the right key, you can use Delete(Entity[])
// or a similar overload for convenience.
transaction.Delete(key);
// Without the Commit call, the transaction will automatically
// be rolled back. The Commit call performs all the mutations
// within the transaction.
transaction.Commit();
}
Entity fetchedAfterDeletion = db.Lookup(key);
Console.WriteLine($"Entity exists before deletion? {fetchedBeforeDeletion != null}");
Console.WriteLine($"Entity exists after deletion? {fetchedAfterDeletion != null}");
Delete(IEnumerable<Entity>)
public virtual 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. |
See Delete for an example using an alternative overload.
Delete(IEnumerable<Key>)
public virtual 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. |
See Delete for an example using an alternative overload.
Dispose()
public virtual void Dispose()
If the transaction has already been committed, this operation is a no-op. Otherwise, it rolls back the transaction.
Insert(params Entity[])
public virtual void Insert(params Entity[] entities)
Adds insert operations for all the specified keys to this transaction.
Parameter | |
---|---|
Name | Description |
entities | Entity The entities to insert. Must not be null. |
This method delegates to Insert(IEnumerable<Entity>).
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("message");
using (DatastoreTransaction transaction = db.BeginTransaction())
{
Entity entity = new Entity
{
Key = keyFactory.CreateIncompleteKey(),
["message"] = "Hello"
};
// This adds the entity to a collection in memory: nothing
// is sent to the server.
transaction.Insert(entity);
// Without the Commit call, the transaction will automatically
// be rolled back. The Commit call performs all the mutations
// within the transaction.
transaction.Commit();
}
Insert(IEnumerable<Entity>)
public virtual 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. |
See Insert for an example using an alternative overload.
Lookup(Key, CallSettings)
public virtual Entity Lookup(Key key, CallSettings callSettings = null)
Looks up a single entity by key.
Parameters | |
---|---|
Name | Description |
key | Key The key to look up. Must not be null, and must be complete. |
callSettings | CallSettings If not null, applies overrides to this RPC call. |
Returns | |
---|---|
Type | Description |
Entity | The entity with the specified key, or |
This method simply delegates to Lookup(IEnumerable<Key>, CallSettings).
See Lookup for an example using an alternative overload.
Lookup(params Key[])
public virtual IReadOnlyList<Entity> Lookup(params Key[] keys)
Looks up a collection of entities by key.
Parameter | |
---|---|
Name | Description |
keys | Key The keys to look up. Must not be null, and every element must be non-null and refer to a complete key. |
Returns | |
---|---|
Type | Description |
IReadOnlyListEntity | A collection of entities with the same size as |
This call may perform multiple RPC operations in order to look up all keys.
This overload does not support the CallSettings to be specified due to restrictions with
methods containing a parameter array and optional parameters.
It simply delegates to Lookup(IEnumerable<Key>, CallSettings), passing in a null
value for the call settings.
Datastore limits the number of entities that can be looked up in a single operation. When looking up a large number of entities, partition the look-ups into batches. See Datastore limits for more details on Datastore limits.
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("message");
Entity message = new Entity { Key = keyFactory.CreateIncompleteKey(), ["text"] = "Original" };
db.Insert(message);
using (DatastoreTransaction transaction = db.BeginTransaction())
{
// Look the message up at the start of the transaction
Entity fetched1 = transaction.Lookup(message.Key);
Console.WriteLine((string) fetched1["text"]); // "Original"
// Update the message outside the transaction
message["text"] = "Updated";
db.Update(message);
// Look up the message up again. We are guaranteed not to see the
// update because it occurred after the start of the transaction.
Entity fetched2 = transaction.Lookup(message.Key);
Console.WriteLine((string) fetched2["text"]); // Still "Original"
}
Lookup(IEnumerable<Key>, CallSettings)
public virtual 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 |
This call may perform multiple RPC operations in order to look up all keys.
See Lookup for an example using an alternative overload.
LookupAsync(Key, CallSettings)
public virtual Task<Entity> LookupAsync(Key key, CallSettings callSettings = null)
Looks up a single entity by key asynchronously.
Parameters | |
---|---|
Name | Description |
key | Key The key to look up. Must not be null, and must be complete. |
callSettings | CallSettings If not null, applies overrides to this RPC call. |
Returns | |
---|---|
Type | Description |
TaskEntity | The entity with the specified key, or |
This method simply delegates to LookupAsync(IEnumerable<Key>, CallSettings).
See Lookup for a synchronous example.
LookupAsync(params Key[])
public virtual Task<IReadOnlyList<Entity>> LookupAsync(params Key[] keys)
Looks up a collection of entities by key asynchronously.
Parameter | |
---|---|
Name | Description |
keys | Key The keys to look up. Must not be null, and every element must be non-null and refer to a complete key. |
Returns | |
---|---|
Type | Description |
TaskIReadOnlyListEntity | A collection of entities with the same size as |
This call may perform multiple RPC operations in order to look up all keys.
This overload does not support the CallSettings to be specified due to restrictions with
methods containing a parameter array and optional parameters.
It simply delegates to LookupAsync(IEnumerable<Key>, CallSettings), passing in a null
value for the call settings.
Datastore limits the number of entities that can be looked up in a single operation. When looking up a large number of entities, partition the look-ups into batches. See Datastore limits for more details on Datastore limits.
See Lookup for a synchronous example.
LookupAsync(IEnumerable<Key>, CallSettings)
public virtual 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 |
This call may perform multiple RPC operations in order to look up all keys.
See Lookup for a synchronous example.
Rollback(CallSettings)
public virtual 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 |
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.
See [RollbackAsync] for an asynchronous example.
Exceptions | |
---|---|
Type | Description |
InvalidOperationException | The transaction has already been committed or rolled back. |
RollbackAsync(CallSettings)
public virtual 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 |
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.
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("message");
// Dispose automatically rolls back an uncommitted transaction synchronously.
// To roll back asynchronously,
bool committed = false;
DatastoreTransaction transaction = await db.BeginTransactionAsync();
try
{
Entity message = new Entity
{
Key = keyFactory.CreateIncompleteKey(),
["text"] = "Hello",
};
// This adds the entity to a collection in memory: nothing
// is sent to the server.
db.Insert(message);
// Attempt to commit the transaction asynchronously.
await transaction.CommitAsync();
committed = true;
}
finally
{
if (!committed)
{
// Roll back asynchronously if anything failed.
await transaction.RollbackAsync();
}
}
Exceptions | |
---|---|
Type | Description |
InvalidOperationException | The transaction has already been committed or rolled back. |
RunAggregationQuery(AggregationQuery, CallSettings)
public virtual 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. |
RunAggregationQuery(GqlQuery, CallSettings)
public virtual 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. |
RunAggregationQueryAsync(AggregationQuery, CallSettings)
public virtual 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. |
RunAggregationQueryAsync(GqlQuery, CallSettings)
public virtual 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. |
RunQuery(GqlQuery, CallSettings)
public virtual DatastoreQueryResults RunQuery(GqlQuery query, CallSettings callSettings = null)
Runs the given query eagerly in this transaction, retrieving all results in memory and indicating whether more results may be available beyond the query's limit. Use this method when your query has a limited number of results, for example to build a web application which fetches results in pages.
Parameters | |
---|---|
Name | Description |
query | GqlQuery The query to execute. Must not be null. |
callSettings | CallSettings If not null, applies overrides to RPC calls. |
Returns | |
---|---|
Type | Description |
DatastoreQueryResults | The complete query results. |
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 default implementation of this method delegates to RunQueryLazily(GqlQuery, CallSettings) and calls GetAllResults() on the return value.
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("player");
// Prepare the data: a player with two game child entities
Entity player = new Entity
{
Key = keyFactory.CreateIncompleteKey(),
["name"] = "Sophie"
};
Key playerKey = db.Insert(player);
Entity game1 = new Entity
{
Key = playerKey.WithElement(new PathElement { Kind = "game" }),
["score"] = 10,
["timestamp"] = new DateTime(2017, 2, 16, 8, 35, 0, DateTimeKind.Utc)
};
Entity game2 = new Entity
{
Key = playerKey.WithElement(new PathElement { Kind = "game" }),
["score"] = 25,
["timestamp"] = new DateTime(2017, 3, 15, 10, 35, 0, DateTimeKind.Utc)
};
db.Insert(game1, game2);
// Perform a query within a transaction
using (DatastoreTransaction transaction = db.BeginTransaction())
{
// Any query executed in a transaction must at least have an ancestor filter.
GqlQuery query = new GqlQuery
{
QueryString = "SELECT * FROM game WHERE __key__ HAS ANCESTOR @player LIMIT @limit",
NamedBindings = {
{ "player", playerKey },
{ "limit", 10 }
}
};
DatastoreQueryResults results = db.RunQuery(query);
// RunQuery fetches all the results into memory in a single call.
// Constrast this with RunQueryLazily, which merely prepares an enumerable
// query. Always specify a limit when you use RunQuery, to avoid running
// out of memory.
foreach (Entity entity in results.Entities)
{
Console.WriteLine(entity);
}
}
RunQuery(Query, CallSettings)
public virtual DatastoreQueryResults RunQuery(Query query, CallSettings callSettings = null)
Runs the given query eagerly in this transaction, retrieving all results in memory and indicating whether more results may be available beyond the query's limit. Use this method when your query has a limited number of results, for example to build a web application which fetches results in pages.
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 |
DatastoreQueryResults | The complete query results. |
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 default implementation of this method delegates to RunQueryLazily(Query, CallSettings) and calls GetAllResults() on the return value.
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("player");
// Prepare the data: a player with two game child entities
Entity player = new Entity
{
Key = keyFactory.CreateIncompleteKey(),
["name"] = "Sophie"
};
Key playerKey = db.Insert(player);
Entity game1 = new Entity
{
Key = playerKey.WithElement(new PathElement { Kind = "game" }),
["score"] = 10,
["timestamp"] = new DateTime(2017, 2, 16, 8, 35, 0, DateTimeKind.Utc)
};
Entity game2 = new Entity
{
Key = playerKey.WithElement(new PathElement { Kind = "game" }),
["score"] = 25,
["timestamp"] = new DateTime(2017, 3, 15, 10, 35, 0, DateTimeKind.Utc)
};
db.Insert(game1, game2);
// Perform a query within a transaction
using (DatastoreTransaction transaction = db.BeginTransaction())
{
// Any query executed in a transaction must at least have an ancestor filter.
Query query = new Query("game")
{
Filter = Filter.HasAncestor(playerKey),
Limit = 10
};
DatastoreQueryResults results = db.RunQuery(query);
// RunQuery fetches all the results into memory in a single call.
// Constrast this with RunQueryLazily, which merely prepares an enumerable
// query. Always specify a limit when you use RunQuery, to avoid running
// out of memory.
foreach (Entity entity in results.Entities)
{
Console.WriteLine(entity);
}
}
RunQueryAsync(GqlQuery, CallSettings)
public virtual Task<DatastoreQueryResults> RunQueryAsync(GqlQuery query, CallSettings callSettings = null)
Runs the given query eagerly and asynchronously in this transaction, retrieving all results in memory and indicating whether more results may be available beyond the query's limit. Use this method when your query has a limited number of results, for example to build a web application which fetches results in pages.
Parameters | |
---|---|
Name | Description |
query | GqlQuery The query to execute. Must not be null. |
callSettings | CallSettings If not null, applies overrides to RPC calls. |
Returns | |
---|---|
Type | Description |
TaskDatastoreQueryResults | A task representing the asynchronous operation. The result of the task is the complete set of query results. |
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 default implementation of this method delegates to RunQueryLazilyAsync(GqlQuery, CallSettings) and calls GetAllResultsAsync() on the return value.
See RunQuery for a synchronous example.
RunQueryAsync(Query, CallSettings)
public virtual Task<DatastoreQueryResults> RunQueryAsync(Query query, CallSettings callSettings = null)
Runs the given query eagerly and asynchronously in this transaction, retrieving all results in memory and indicating whether more results may be available beyond the query's limit. Use this method when your query has a limited number of results, for example to build a web application which fetches results in pages.
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 |
TaskDatastoreQueryResults | A task representing the asynchronous operation. The result of the task is the complete set of query results. |
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 default implementation of this method delegates to RunQueryLazilyAsync(Query, CallSettings) and calls GetAllResultsAsync() on the return value.
See RunQueryLazily for a synchronous example.
RunQueryLazily(GqlQuery, CallSettings)
public virtual 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. |
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.
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("player");
// Prepare the data: a player with two game child entities
Entity player = new Entity
{
Key = keyFactory.CreateIncompleteKey(),
["name"] = "Sophie"
};
Key playerKey = db.Insert(player);
Entity game1 = new Entity
{
Key = playerKey.WithElement(new PathElement { Kind = "game" }),
["score"] = 10,
["timestamp"] = new DateTime(2017, 2, 16, 8, 35, 0, DateTimeKind.Utc)
};
Entity game2 = new Entity
{
Key = playerKey.WithElement(new PathElement { Kind = "game" }),
["score"] = 25,
["timestamp"] = new DateTime(2017, 3, 15, 10, 35, 0, DateTimeKind.Utc)
};
db.Insert(game1, game2);
// Perform a query within a transaction
using (DatastoreTransaction transaction = db.BeginTransaction())
{
// Any query executed in a transaction must at least have an ancestor filter.
GqlQuery query = new GqlQuery
{
QueryString = "SELECT * FROM game WHERE __key__ HAS ANCESTOR @player",
NamedBindings = { { "player", playerKey } }
};
LazyDatastoreQuery results = db.RunQueryLazily(query);
// LazyDatastoreQuery implements IEnumerable<Entity>, but you can
// call AsResponses() to see the raw RPC responses, or
// GetAllResults() to get all the results into memory, complete with
// the end cursor and the reason for the query finishing.
foreach (Entity entity in results)
{
Console.WriteLine(entity);
}
}
RunQueryLazily(Query, CallSettings)
public virtual 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. |
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.
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("player");
// Prepare the data: a player with two game child entities
Entity player = new Entity
{
Key = keyFactory.CreateIncompleteKey(),
["name"] = "Sophie"
};
Key playerKey = db.Insert(player);
Entity game1 = new Entity
{
Key = playerKey.WithElement(new PathElement { Kind = "game" }),
["score"] = 10,
["timestamp"] = new DateTime(2017, 2, 16, 8, 35, 0, DateTimeKind.Utc)
};
Entity game2 = new Entity
{
Key = playerKey.WithElement(new PathElement { Kind = "game" }),
["score"] = 25,
["timestamp"] = new DateTime(2017, 3, 15, 10, 35, 0, DateTimeKind.Utc)
};
db.Insert(game1, game2);
// Perform a query within a transaction
using (DatastoreTransaction transaction = db.BeginTransaction())
{
// Any query executed in a transaction must at least have an ancestor filter.
Query query = new Query("game")
{
Filter = Filter.HasAncestor(playerKey)
};
LazyDatastoreQuery results = db.RunQueryLazily(query);
// LazyDatastoreQuery implements IEnumerable<Entity>, but you can
// call AsResponses() to see the raw RPC responses, or
// GetAllResults() to get all the results into memory, complete with
// the end cursor and the reason for the query finishing.
foreach (Entity entity in results)
{
Console.WriteLine(entity);
}
}
RunQueryLazilyAsync(GqlQuery, CallSettings)
public virtual 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. |
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.
See RunQueryLazily for a synchronous example.
RunQueryLazilyAsync(Query, CallSettings)
public virtual 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. |
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.
See RunQueryLazily for a synchronous example.
Update(params Entity[])
public virtual void Update(params Entity[] entities)
Adds update operations for all the specified keys to this transaction.
Parameter | |
---|---|
Name | Description |
entities | Entity The entities to update. Must not be null. |
This method delegates to Update(IEnumerable<Entity>).
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("book");
Entity book = new Entity
{
Key = keyFactory.CreateIncompleteKey(),
["author"] = "Harper Lee",
["title"] = "Tequila Mockingbird",
["publication_date"] = new DateTime(1960, 7, 11, 0, 0, 0, DateTimeKind.Utc),
["genres"] = new[] { "Southern drama", "Courtroom drama", "Bildungsroman" }
};
db.Insert(book);
using (DatastoreTransaction transaction = db.BeginTransaction())
{
// Correct the typo in memory
book["title"] = "To Kill a Mockingbird";
// This adds the entity to a collection of mutations in memory: nothing
// is sent to the server.
transaction.Update(book);
// Without the Commit call, the transaction will automatically
// be rolled back. The Commit call performs all the mutations
// within the transaction.
transaction.Commit();
}
Update(IEnumerable<Entity>)
public virtual 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. |
See Update for an example using an alternative overload.
Upsert(params Entity[])
public virtual void Upsert(params Entity[] entities)
Adds upsert operations for all the specified keys to this transaction.
Parameter | |
---|---|
Name | Description |
entities | Entity The entities to upsert. Must not be null. |
This method delegates to Upsert(IEnumerable<Entity>).
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("book");
Entity book1 = new Entity
{
Key = keyFactory.CreateIncompleteKey(),
["author"] = "Harper Lee",
["title"] = "Tequila Mockingbird",
["publication_date"] = new DateTime(1960, 7, 11, 0, 0, 0, DateTimeKind.Utc),
["genres"] = new[] { "Southern drama", "Courtroom drama", "Bildungsroman" }
};
db.Insert(book1);
using (DatastoreTransaction transaction = db.BeginTransaction())
{
// Correct the typo in memory
book1["title"] = "To Kill a Mockingbird";
Entity book2 = new Entity
{
Key = keyFactory.CreateIncompleteKey(),
["author"] = "Charlotte Brontë",
["title"] = "Jane Eyre",
["publication_date"] = new DateTime(1847, 10, 16, 0, 0, 0, DateTimeKind.Utc),
["genres"] = new[] { "Gothic", "Romance", "Bildungsroman" }
};
// This adds the entities to a collection of mutations in memory: nothing
// is sent to the server.
transaction.Upsert(book1, book2);
// Without the Commit call, the transaction will automatically
// be rolled back. The Commit call performs all the mutations
// within the transaction.
transaction.Commit();
}
Upsert(IEnumerable<Entity>)
public virtual 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. |
See Upsert for an example using an alternative overload.