Google Cloud Datastore v1 API - Class DatastoreDb (4.3.0)

Stay organized with collections Save and categorize content based on your preferences.
public abstract class DatastoreDb

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

An abstraction over DatastoreClient to simplify operations. Use the Create(String, String, DatastoreClient) method to obtain an instance of this class.

Inheritance

Object > DatastoreDb

Derived Types

Namespace

Google.Cloud.Datastore.V1

Assembly

Google.Cloud.Datastore.V1.dll

Remarks

The project ID specified on creation is used for all operations, effectively supplying the first parameter of every operation specified on DatastoreClient.

The project ID and namespace ID are combined to form a partition ID. This partition ID is used when creating a key factory or running a query. Operations that take keys or entities do not validate that the keys are within the partition associated with this object.

This abstract class is provided to enable testability while permitting additional operations to be added in the future. See Create(String, String, DatastoreClient) to construct instances; alternatively, you can construct a DatastoreClient directly.

Properties

Client

public virtual DatastoreClient Client { get; }

The DatastoreClient used for all remote operations.

Property Value
TypeDescription
DatastoreClient

NamespaceId

public virtual string NamespaceId { get; }

The ID of the namespace this instance operates on.

Property Value
TypeDescription
String

ProjectId

public virtual string ProjectId { get; }

The ID of the project this instance operates on.

Property Value
TypeDescription
String

Methods

AllocateId(Key, CallSettings)

public virtual Key AllocateId(Key key, CallSettings callSettings = null)

Allocates an ID for a single incomplete key.

Parameters
NameDescription
keyKey

The incomplete key to allocate an ID for.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
Key

The complete key.

Remarks

This method simply delegates to AllocateIds(IEnumerable<Key>, CallSettings).

Example
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("message");
Key key = db.AllocateId(keyFactory.CreateIncompleteKey());

AllocateIdAsync(Key, CallSettings)

public virtual async Task<Key> AllocateIdAsync(Key key, CallSettings callSettings = null)

Allocates an ID for a single incomplete key asynchronously.

Parameters
NameDescription
keyKey

The incomplete key to allocate an ID for.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
Task<Key>

The complete key.

Remarks

This method simply delegates to AllocateIdsAsync(IEnumerable<Key>, CallSettings).

Example
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("message");
Key key = await db.AllocateIdAsync(keyFactory.CreateIncompleteKey());

AllocateIds(Key[])

public virtual IReadOnlyList<Key> AllocateIds(params Key[] keys)

Allocates IDs for a collection of incomplete keys.

Parameter
NameDescription
keysKey[]

The incomplete keys. Must not be null or contain null elements.

Returns
TypeDescription
IReadOnlyList<Key>

A collection of complete keys with allocated IDs, in the same order as keys.

Remarks

This method simply delegates to AllocateIds(IEnumerable<Key>, CallSettings).

Call settings are not supported on this call due to restrictions with methods containing a parameter array and optional parameters. To specify options, create a collection or array explicitly, and call AllocateIds(IEnumerable<Key>, CallSettings).

Datastore limits the number of keys that can be allocated in a single operation. When allocating a large number of keys, partition the allocations into batches. See Datastore limits for more details on Datastore limits.

Example
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("message");
IReadOnlyList<Key> keys = db.AllocateIds(keyFactory.CreateIncompleteKey(), keyFactory.CreateIncompleteKey());

AllocateIds(IEnumerable<Key>, CallSettings)

public virtual IReadOnlyList<Key> AllocateIds(IEnumerable<Key> keys, CallSettings callSettings = null)

Allocates IDs for a collection of incomplete keys.

Parameters
NameDescription
keysIEnumerable<Key>

The incomplete keys. Must not be null or contain null elements.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
IReadOnlyList<Key>

A collection of complete keys with allocated IDs, in the same order as keys.

Remarks

Datastore limits the number of keys that can be allocated in a single operation. When allocating a large number of keys, partition the allocations into batches. See Datastore limits for more details on Datastore limits.

Example

See AllocateIds for an example using an alternative overload.

AllocateIdsAsync(Key[])

public virtual Task<IReadOnlyList<Key>> AllocateIdsAsync(params Key[] keys)

Allocates IDs for a collection of incomplete keys asynchronously.

Parameter
NameDescription
keysKey[]

The incomplete keys. Must not be null or contain null elements.

Returns
TypeDescription
Task<IReadOnlyList<Key>>

A collection of complete keys with allocated IDs, in the same order as keys.

Remarks

This method simply delegates to AllocateIdsAsync(IEnumerable<Key>, CallSettings).

Call settings are not supported on this call due to restrictions with methods containing a parameter array and optional parameters. To specify options, create a collection or array explicitly, and call AllocateIdsAsync(IEnumerable<Key>, CallSettings).

Datastore limits the number of keys that can be allocated in a single operation. When allocating a large number of keys, partition the allocations into batches. See Datastore limits for more details on Datastore limits.

Example
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("message");
IReadOnlyList<Key> keys = await db.AllocateIdsAsync(keyFactory.CreateIncompleteKey(), keyFactory.CreateIncompleteKey());

AllocateIdsAsync(IEnumerable<Key>, CallSettings)

public virtual Task<IReadOnlyList<Key>> AllocateIdsAsync(IEnumerable<Key> keys, CallSettings callSettings = null)

Allocates IDs for a collection of incomplete keys asynchronously.

Parameters
NameDescription
keysIEnumerable<Key>

The incomplete keys. Must not be null or contain null elements.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
Task<IReadOnlyList<Key>>

A collection of complete keys with allocated IDs, in the same order as keys.

Remarks

Datastore limits the number of keys that can be allocated in a single operation. When allocating a large number of keys, partition the allocations into batches. See Datastore limits for more details on Datastore limits.

Example

See AllocateIdsAsync for an example using an alternative overload.

BeginTransaction(CallSettings)

public virtual DatastoreTransaction BeginTransaction(CallSettings callSettings = null)

Begins a transaction, returning a DatastoreTransaction which can be used to operate on the transaction.

Parameter
NameDescription
callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
DatastoreTransaction

A new DatastoreTransaction for this object's project.

Example
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
using (DatastoreTransaction transaction = db.BeginTransaction())
{
    // The return value from DatastoreTransaction.Get contains the fetched entities
    // in the same order as they are in the call.
    IReadOnlyList<Entity> entities = transaction.Lookup(fromKey, toKey);
    Entity from = entities[0];
    Entity to = entities[1];
    from["balance"] = (long)from["balance"] - amount;
    to["balance"] = (long)to["balance"] - amount;
    transaction.Update(from);
    transaction.Update(to);
    transaction.Commit();
}

BeginTransaction(TransactionOptions, CallSettings)

public virtual DatastoreTransaction BeginTransaction(TransactionOptions options, CallSettings callSettings = null)

Begins a transaction, returning a DatastoreTransaction which can be used to operate on the transaction.

Parameters
NameDescription
optionsTransactionOptions

The options for the new transaction. May be null, for default options.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
DatastoreTransaction

A new DatastoreTransaction for this object's project.

BeginTransactionAsync(CallSettings)

public virtual Task<DatastoreTransaction> BeginTransactionAsync(CallSettings callSettings = null)

Begins a transaction asynchronously, returning a DatastoreTransaction which can be used to operate on the transaction.

Parameter
NameDescription
callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
Task<DatastoreTransaction>

A new DatastoreTransaction for this object's project.

Example

See BeginTransaction for an example of the synchronous equivalent of this method.

BeginTransactionAsync(TransactionOptions, CallSettings)

public virtual Task<DatastoreTransaction> BeginTransactionAsync(TransactionOptions options, CallSettings callSettings = null)

Begins a transaction asynchronously, returning a DatastoreTransaction which can be used to operate on the transaction.

Parameters
NameDescription
optionsTransactionOptions

The options for the new transaction. May be null, for default options.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
Task<DatastoreTransaction>

A new DatastoreTransaction for this object's project.

Create(String, String, DatastoreClient)

public static DatastoreDb Create(string projectId, string namespaceId = "", DatastoreClient client = null)

Creates a DatastoreDb to operate on the partition identified by projectId and namespaceId, using the client to perform remote operations.

Parameters
NameDescription
projectIdString

The project ID to use in all operations.

namespaceIdString

The namespace ID to use in operations requiring a partition.

clientDatastoreClient

The client to use for remote operations. If this is null, an instance will be created using default settings.

Returns
TypeDescription
DatastoreDb

A DatastoreDb operating on the specified partition.

CreateKeyFactory(String)

public virtual KeyFactory CreateKeyFactory(string kind)

Creates a key factory for root entities in this objects's partition.

Parameter
NameDescription
kindString

The kind of entity key to create. Must not be null.

Returns
TypeDescription
KeyFactory

A key factory with the specified kind and this object's partition.

Delete(Entity, CallSettings)

public virtual void Delete(Entity entity, CallSettings callSettings = null)

Deletes a single entity, non-transactionally.

Parameters
NameDescription
entityEntity

The entity to delete. Must not be null.

callSettingsCallSettings

If not null, applies overrides to RPC calls.

Remarks

This method simply delegates to Delete(IEnumerable<Entity>, CallSettings).

Example
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);

// 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, CallSettings) or
// a similar overload.
db.Delete(message);

Entity fetchedAfterDeletion = db.Lookup(message.Key);

Console.WriteLine($"Entity exists before deletion? {fetchedBeforeDeletion != null}");
Console.WriteLine($"Entity exists after deletion? {fetchedAfterDeletion != null}");

Delete(Entity[])

public virtual void Delete(params Entity[] entities)

Deletes a collection of entities, non-transactionally.

Parameter
NameDescription
entitiesEntity[]

The entities to delete. Must not be null or contain null entries.

Remarks

This method simply delegates to Delete(IEnumerable<Entity>, CallSettings).

Call settings are not supported on this call due to restrictions with methods containing a parameter array and optional parameters. To specify options, create a collection or array explicitly, and call Delete(IEnumerable<Entity>, CallSettings).

Datastore limits the number of entities that can be modified in a Commit operation. Although this method does not use an existing transaction, it still performs all the work in a single Commit operation. When modifying a large number of entities, partition the changes into batches. See Datastore limits for more details on Datastore limits.

Example

See Delete for an example using an alternative overload.

Delete(Key, CallSettings)

public virtual void Delete(Key key, CallSettings callSettings = null)

Deletes a single key, non-transactionally.

Parameters
NameDescription
keyKey

The key to delete. Must not be null.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Remarks

This method simply delegates to Delete(IEnumerable<Key>, CallSettings).

Example
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);

// Only the key is required to determine what to delete.
// If you have an entity with the right key, you can use Delete(Entity, CallSettings)
// or a similar overload for convenience.
db.Delete(key);

Entity fetchedAfterDeletion = db.Lookup(key);

Console.WriteLine($"Entity exists before deletion? {fetchedBeforeDeletion != null}");
Console.WriteLine($"Entity exists after deletion? {fetchedAfterDeletion != null}");

Delete(Key[])

public virtual void Delete(params Key[] keys)

Deletes a collection of keys, non-transactionally.

Parameter
NameDescription
keysKey[]

The keys to delete. Must not be null or contain null entries.

Remarks

This method simply delegates to Delete(IEnumerable<Key>, CallSettings).

Call settings are not supported on this call due to restrictions with methods containing a parameter array and optional parameters. To specify options, create a collection or array explicitly, and call Delete(IEnumerable<Key>, CallSettings).

Datastore limits the number of entities that can be modified in a Commit operation. Although this method does not use an existing transaction, it still performs all the work in a single Commit operation. When modifying a large number of entities, partition the changes into batches. See Datastore limits for more details on Datastore limits.

Example

See Delete for an example using an alternative overload.

Delete(IEnumerable<Entity>, CallSettings)

public virtual void Delete(IEnumerable<Entity> entities, CallSettings callSettings = null)

Deletes a collection of entities, non-transactionally.

Parameters
NameDescription
entitiesIEnumerable<Entity>

The entities to delete. Must not be null or contain null entries.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Remarks

Datastore limits the number of entities that can be modified in a Commit operation. Although this method does not use an existing transaction, it still performs all the work in a single Commit operation. When modifying a large number of entities, partition the changes into batches. See Datastore limits for more details on Datastore limits.

Example

See Delete for an example using an alternative overload.

Delete(IEnumerable<Key>, CallSettings)

public virtual void Delete(IEnumerable<Key> keys, CallSettings callSettings = null)

Deletes a collection of keys, non-transactionally.

Parameters
NameDescription
keysIEnumerable<Key>

The keys to delete. Must not be null or contain null entries.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Remarks

Datastore limits the number of entities that can be modified in a Commit operation. Although this method does not use an existing transaction, it still performs all the work in a single Commit operation. When modifying a large number of entities, partition the changes into batches. See Datastore limits for more details on Datastore limits.

Example

See Delete for an example using an alternative overload.

DeleteAsync(Entity, CallSettings)

public virtual Task DeleteAsync(Entity entity, CallSettings callSettings = null)

Deletes a single entity, non-transactionally and asynchronously.

Parameters
NameDescription
entityEntity

The entity to delete. Must not be null.

callSettingsCallSettings

If not null, applies overrides to RPC calls.

Returns
TypeDescription
Task

A task representing the asynchronous operation.

Remarks

This method simply delegates to DeleteAsync(IEnumerable<Entity>, CallSettings).

Example

See Delete for a synchronous example.

DeleteAsync(Entity[])

public virtual Task DeleteAsync(params Entity[] entities)

Deletes a collection of entities, non-transactionally and asynchronously.

Parameter
NameDescription
entitiesEntity[]

The entities to delete. Must not be null or contain null entries.

Returns
TypeDescription
Task

A task representing the asynchronous operation.

Remarks

This method simply delegates to DeleteAsync(IEnumerable<Entity>, CallSettings).

Call settings are not supported on this call due to restrictions with methods containing a parameter array and optional parameters. To specify options, create a collection or array explicitly, and call DeleteAsync(IEnumerable<Entity>, CallSettings).

Datastore limits the number of entities that can be modified in a Commit operation. Although this method does not use an existing transaction, it still performs all the work in a single Commit operation. When modifying a large number of entities, partition the changes into batches. See Datastore limits for more details on Datastore limits.

Example

See Delete for a synchronous example.

DeleteAsync(Key, CallSettings)

public virtual Task DeleteAsync(Key key, CallSettings callSettings = null)

Deletes a single key, non-transactionally and asynchronously.

Parameters
NameDescription
keyKey

The key to delete. Must not be null.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
Task
Remarks

This method simply delegates to DeleteAsync(IEnumerable<Key>, CallSettings).

Example

See Delete for a synchronous example.

DeleteAsync(Key[])

public virtual Task DeleteAsync(params Key[] keys)

Deletes a collection of keys, non-transactionally and asynchronously.

Parameter
NameDescription
keysKey[]

The keys to delete. Must not be null or contain null entries.

Returns
TypeDescription
Task
Remarks

This method simply delegates to DeleteAsync(IEnumerable<Key>, CallSettings).

Call settings are not supported on this call due to restrictions with methods containing a parameter array and optional parameters. To specify options, create a collection or array explicitly, and call DeleteAsync(IEnumerable<Key>, CallSettings).

Datastore limits the number of entities that can be modified in a Commit operation. Although this method does not use an existing transaction, it still performs all the work in a single Commit operation. When modifying a large number of entities, partition the changes into batches. See Datastore limits for more details on Datastore limits.

Example

See Delete for a synchronous example.

DeleteAsync(IEnumerable<Entity>, CallSettings)

public virtual Task DeleteAsync(IEnumerable<Entity> entities, CallSettings callSettings = null)

Deletes a collection of entities, non-transactionally and asynchronously.

Parameters
NameDescription
entitiesIEnumerable<Entity>

The entities to delete. Must not be null or contain null entries.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
Task

A task representing the asynchronous operation.

Remarks

Datastore limits the number of entities that can be modified in a Commit operation. Although this method does not use an existing transaction, it still performs all the work in a single Commit operation. When modifying a large number of entities, partition the changes into batches. See Datastore limits for more details on Datastore limits.

Example

See Delete for a synchronous example.

DeleteAsync(IEnumerable<Key>, CallSettings)

public virtual Task DeleteAsync(IEnumerable<Key> keys, CallSettings callSettings = null)

Deletes a collection of keys, non-transactionally and asynchronously.

Parameters
NameDescription
keysIEnumerable<Key>

The keys to delete. Must not be null or contain null entries.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
Task
Remarks

Datastore limits the number of entities that can be modified in a Commit operation. Although this method does not use an existing transaction, it still performs all the work in a single Commit operation. When modifying a large number of entities, partition the changes into batches. See Datastore limits for more details on Datastore limits.

Example

See Delete for a synchronous example.

Insert(Entity, CallSettings)

public virtual Key Insert(Entity entity, CallSettings callSettings = null)

Inserts a single entity, non-transactionally.

Parameters
NameDescription
entityEntity

The entity to insert. Must not be null.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
Key

The key of the inserted entity if it was allocated by the server, or null if the inserted entity had a predefined key.

Remarks

On success, the entity will be updated in memory with the server-allocated keys.

This method simply delegates to Insert(IEnumerable<Entity>, CallSettings).

Example

See Insert for an example using an alternative overload.

Insert(Entity[])

public virtual IReadOnlyList<Key> Insert(params Entity[] entities)

Inserts a collection of entities, non-transactionally.

Parameter
NameDescription
entitiesEntity[]

The entities to insert. Must not be null or contain null entries.

Returns
TypeDescription
IReadOnlyList<Key>

A collection of keys of inserted entities, in the same order as entities. Only keys allocated by the server will be returned; any entity with a predefined key will have a null value in the collection.

Remarks

On success, the entities will be updated in memory with the server-allocated keys.

This method simply delegates to Insert(IEnumerable<Entity>, CallSettings).

Call settings are not supported on this call due to restrictions with methods containing a parameter array and optional parameters. To specify options, create a collection or array explicitly, and call Insert(IEnumerable<Entity>, CallSettings).

Datastore limits the number of entities that can be modified in a Commit operation. Although this method does not use an existing transaction, it still performs all the work in a single Commit operation. When modifying a large number of entities, partition the changes into batches. See Datastore limits for more details on Datastore limits.

Example
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("book");
Entity book1 = new Entity
{
    Key = keyFactory.CreateIncompleteKey(),
    ["author"] = "Harper Lee",
    ["title"] = "To Kill a Mockingbird",
    ["publication_date"] = new DateTime(1960, 7, 11, 0, 0, 0, DateTimeKind.Utc),
    ["genres"] = new[] { "Southern drama", "Courtroom drama", "Bildungsroman" }
};
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" }
};
IReadOnlyList<Key> insertedKeys = db.Insert(book1, book2);
Console.WriteLine($"Inserted keys: {string.Join(",", insertedKeys)}");

Insert(IEnumerable<Entity>, CallSettings)

public virtual IReadOnlyList<Key> Insert(IEnumerable<Entity> entities, CallSettings callSettings = null)

Inserts a collection of entities, non-transactionally.

Parameters
NameDescription
entitiesIEnumerable<Entity>

The entities to insert. Must not be null or contain null entries.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
IReadOnlyList<Key>

A collection of keys of inserted entities, in the same order as entities. Only keys allocated by the server will be returned; any entity with a predefined key will have a null value in the collection.

Remarks

On success, the entities will be updated in memory with the server-allocated keys.

Datastore limits the number of entities that can be modified in a Commit operation. Although this method does not use an existing transaction, it still performs all the work in a single Commit operation. When modifying a large number of entities, partition the changes into batches. See Datastore limits for more details on Datastore limits.

Example

See Insert for an example using an alternative overload.

InsertAsync(Entity, CallSettings)

public virtual async Task<Key> InsertAsync(Entity entity, CallSettings callSettings = null)

Inserts a single entity, non-transactionally and asynchronously.

Parameters
NameDescription
entityEntity

The entity to insert. Must not be null.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
Task<Key>

A task representing the asynchronous operation. The result of the task is the key of the inserted entity if it was allocated by the server, or null if the inserted entity had a predefined key.

Remarks

On success, the entity will be updated in memory with the server-allocated keys.

This method simply delegates to InsertAsync(IEnumerable<Entity>, CallSettings).

Example

See InsertAsync for an example using an alternative overload.

InsertAsync(Entity[])

public virtual Task<IReadOnlyList<Key>> InsertAsync(params Entity[] entities)

Inserts a collection of entities, non-transactionally and asynchronously.

Parameter
NameDescription
entitiesEntity[]

The entities to insert. Must not be null or contain null entries.

Returns
TypeDescription
Task<IReadOnlyList<Key>>

A task representing the asynchronous operation. The result of the task is a collection of keys of inserted entities, in the same order as entities. Only keys allocated by the server will be returned; any entity with a predefined key will have a null value in the collection.

Remarks

On success, the entities will be updated in memory with the server-allocated keys.

This method simply delegates to InsertAsync(IEnumerable<Entity>, CallSettings).

Call settings are not supported on this call due to restrictions with methods containing a parameter array and optional parameters. To specify options, create a collection or array explicitly, and call InsertAsync(IEnumerable<Entity>, CallSettings).

Datastore limits the number of entities that can be modified in a Commit operation. Although this method does not use an existing transaction, it still performs all the work in a single Commit operation. When modifying a large number of entities, partition the changes into batches. See Datastore limits for more details on Datastore limits.

Example
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("book");
Entity book1 = new Entity
{
    Key = keyFactory.CreateIncompleteKey(),
    ["author"] = "Harper Lee",
    ["title"] = "To Kill a Mockingbird",
    ["publication_date"] = new DateTime(1960, 7, 11, 0, 0, 0, DateTimeKind.Utc),
    ["genres"] = new[] { "Southern drama", "Courtroom drama", "Bildungsroman" }
};
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" }
};
IReadOnlyList<Key> insertedKeys = await db.InsertAsync(book1, book2);
Console.WriteLine($"Inserted keys: {string.Join(",", insertedKeys)}");

InsertAsync(IEnumerable<Entity>, CallSettings)

public virtual Task<IReadOnlyList<Key>> InsertAsync(IEnumerable<Entity> entities, CallSettings callSettings = null)

Inserts a collection of entities, non-transactionally and asynchronously.

Parameters
NameDescription
entitiesIEnumerable<Entity>

The entities to insert. Must not be null or contain null entries.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
Task<IReadOnlyList<Key>>

A task representing the asynchronous operation. The result of the task is a collection of keys of inserted entities, in the same order as entities. Only keys allocated by the server will be returned; any entity with a predefined key will have a null value in the collection.

Remarks

On success, the entities will be updated in memory with the server-allocated keys.

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.

Example

See InsertAsync for an example using an alternative overload.

Lookup(Key, Nullable<ReadOptions.Types.ReadConsistency>, CallSettings)

public virtual Entity Lookup(Key key, ReadOptions.Types.ReadConsistency? readConsistency = null, CallSettings callSettings = null)

Looks up a single entity by key.

Parameters
NameDescription
keyKey

The key to look up. Must not be null, and must be complete.

readConsistencyNullable<ReadOptions.Types.ReadConsistency>

The desired read consistency of the lookup, or null to use the default.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
Entity

The entity with the specified key, or null if no such entity exists.

Remarks Example

See Lookup for an example using an alternative overload.

Lookup(Key[])

public virtual IReadOnlyList<Entity> Lookup(params Key[] keys)

Looks up a collection of entities by key.

Parameter
NameDescription
keysKey[]

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

Returns
TypeDescription
IReadOnlyList<Entity>

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

Remarks

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

This overload does not support the ReadOptions.Types.ReadConsistency or CallSettings to be specified due to restrictions with methods containing a parameter array and optional parameters. It simply delegates to Lookup(IEnumerable<Key>, Nullable<ReadOptions.Types.ReadConsistency>, CallSettings), passing in a null value for the read consistency and 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.

Example
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("book");
Key key1 = keyFactory.CreateKey("pride_and_prejudice");
Key key2 = keyFactory.CreateKey("not_present");

IReadOnlyList<Entity> entities = db.Lookup(key1, key2);
Console.WriteLine(entities[0]); // Pride and Prejudice entity
Console.WriteLine(entities[1]); // Nothing (value is null reference)

Lookup(IEnumerable<Key>, Nullable<ReadOptions.Types.ReadConsistency>, CallSettings)

public virtual IReadOnlyList<Entity> Lookup(IEnumerable<Key> keys, ReadOptions.Types.ReadConsistency? readConsistency = null, CallSettings callSettings = null)

Looks up a collection of entities by key.

Parameters
NameDescription
keysIEnumerable<Key>

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

readConsistencyNullable<ReadOptions.Types.ReadConsistency>

The desired read consistency of the lookup, or null to use the default.

callSettingsCallSettings

If not null, applies overrides to RPC calls.

Returns
TypeDescription
IReadOnlyList<Entity>

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

Remarks

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

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.

Example

See Lookup for an example using an alternative overload.

LookupAsync(Key, Nullable<ReadOptions.Types.ReadConsistency>, CallSettings)

public virtual async Task<Entity> LookupAsync(Key key, ReadOptions.Types.ReadConsistency? readConsistency = null, CallSettings callSettings = null)

Looks up a single entity by key asynchronously.

Parameters
NameDescription
keyKey

The key to look up. Must not be null, and must be complete.

readConsistencyNullable<ReadOptions.Types.ReadConsistency>

The desired read consistency of the lookup, or null to use the default.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
Task<Entity>

The entity with the specified key, or null if no such entity exists.

Remarks Example

See LookupAsync for an example using an alternative overload.

LookupAsync(Key[])

public virtual Task<IReadOnlyList<Entity>> LookupAsync(params Key[] keys)

Looks up a collection of entities by key asynchronously.

Parameter
NameDescription
keysKey[]

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

Returns
TypeDescription
Task<IReadOnlyList<Entity>>

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

Remarks

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

This overload does not support the ReadOptions.Types.ReadConsistency or CallSettings to be specified due to restrictions with methods containing a parameter array and optional parameters. It simply delegates to LookupAsync(IEnumerable<Key>, Nullable<ReadOptions.Types.ReadConsistency>, CallSettings), passing in a null value for the read consistency and 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.

Example
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
KeyFactory keyFactory = db.CreateKeyFactory("book");
Key key1 = keyFactory.CreateKey("pride_and_prejudice");
Key key2 = keyFactory.CreateKey("not_present");

IReadOnlyList<Entity> entities = await db.LookupAsync(key1, key2);
Console.WriteLine(entities[0]); // Pride and Prejudice entity
Console.WriteLine(entities[1]); // Nothing (value is null reference)

LookupAsync(IEnumerable<Key>, Nullable<ReadOptions.Types.ReadConsistency>, CallSettings)

public virtual Task<IReadOnlyList<Entity>> LookupAsync(IEnumerable<Key> keys, ReadOptions.Types.ReadConsistency? readConsistency = null, CallSettings callSettings = null)

Looks up a collection of entities by key asynchronously.

Parameters
NameDescription
keysIEnumerable<Key>

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

readConsistencyNullable<ReadOptions.Types.ReadConsistency>

The desired read consistency of the lookup, or null to use the default.

callSettingsCallSettings

If not null, applies overrides to RPC calls.

Returns
TypeDescription
Task<IReadOnlyList<Entity>>

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

Remarks

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

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.

Example

See LookupAsync for an example using an alternative overload.

RunQuery(GqlQuery, Nullable<ReadOptions.Types.ReadConsistency>, CallSettings)

public virtual DatastoreQueryResults RunQuery(GqlQuery query, ReadOptions.Types.ReadConsistency? readConsistency = null, CallSettings callSettings = null)

Runs the given query eagerly, 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
NameDescription
queryGqlQuery

The query to execute. Must not be null.

readConsistencyNullable<ReadOptions.Types.ReadConsistency>

If not null, overrides the read consistency of the query.

callSettingsCallSettings

If not null, applies overrides to RPC calls.

Returns
TypeDescription
DatastoreQueryResults

The complete query results.

Example
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
GqlQuery gqlQuery = new GqlQuery
{
    QueryString = "SELECT * FROM book WHERE author = @author LIMIT @limit",
    NamedBindings = {
        { "author", "Jane Austen" },
        { "limit", 10 }
    }
};
DatastoreQueryResults results = db.RunQuery(gqlQuery);
// 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, Nullable<ReadOptions.Types.ReadConsistency>, CallSettings)

public virtual DatastoreQueryResults RunQuery(Query query, ReadOptions.Types.ReadConsistency? readConsistency = null, CallSettings callSettings = null)

Runs the given query eagerly, 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
NameDescription
queryQuery

The query to execute. Must not be null.

readConsistencyNullable<ReadOptions.Types.ReadConsistency>

If not null, overrides the read consistency of the query.

callSettingsCallSettings

If not null, applies overrides to RPC calls.

Returns
TypeDescription
DatastoreQueryResults

The complete query results.

Example
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
Query query = new Query("book")
{
    Filter = Filter.Equal("author", "Jane Austen"),
    Limit = 10
};
// 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.
DatastoreQueryResults results = db.RunQuery(query);
foreach (Entity entity in results.Entities)
{
    Console.WriteLine(entity);
}

RunQueryAsync(GqlQuery, Nullable<ReadOptions.Types.ReadConsistency>, CallSettings)

public virtual Task<DatastoreQueryResults> RunQueryAsync(GqlQuery query, ReadOptions.Types.ReadConsistency? readConsistency = null, CallSettings callSettings = null)

Runs the given query eagerly and asynchronously, 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
NameDescription
queryGqlQuery

The query to execute. Must not be null.

readConsistencyNullable<ReadOptions.Types.ReadConsistency>

If not null, overrides the read consistency of the query.

callSettingsCallSettings

If not null, applies overrides to RPC calls.

Returns
TypeDescription
Task<DatastoreQueryResults>

A task representing the asynchronous operation. The result of the task is the complete set of query results.

Example
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
GqlQuery gqlQuery = new GqlQuery
{
    QueryString = "SELECT * FROM book WHERE author = @author",
    NamedBindings = { { "author", "Jane Austen" } },
};
DatastoreQueryResults results = await db.RunQueryAsync(gqlQuery);
// 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(Query, Nullable<ReadOptions.Types.ReadConsistency>, CallSettings)

public virtual Task<DatastoreQueryResults> RunQueryAsync(Query query, ReadOptions.Types.ReadConsistency? readConsistency = null, CallSettings callSettings = null)

Runs the given query eagerly and asynchronously, 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
NameDescription
queryQuery

The query to execute. Must not be null.

readConsistencyNullable<ReadOptions.Types.ReadConsistency>

If not null, overrides the read consistency of the query.

callSettingsCallSettings

If not null, applies overrides to RPC calls.

Returns
TypeDescription
Task<DatastoreQueryResults>

A task representing the asynchronous operation. The result of the task is the complete set of query results.

Example
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
Query query = new Query("book")
{
    Filter = Filter.Equal("author", "Jane Austen"),
    Limit = 10
};
DatastoreQueryResults results = await db.RunQueryAsync(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);
}

RunQueryLazily(GqlQuery, Nullable<ReadOptions.Types.ReadConsistency>, CallSettings)

public virtual LazyDatastoreQuery RunQueryLazily(GqlQuery gqlQuery, ReadOptions.Types.ReadConsistency? readConsistency = null, CallSettings callSettings = null)

Lazily executes the given GQL query for asynchronous consumption.

Parameters
NameDescription
gqlQueryGqlQuery

The query to execute. Must not be null.

readConsistencyNullable<ReadOptions.Types.ReadConsistency>

If not null, overrides the read consistency of the query.

callSettingsCallSettings

If not null, applies overrides to RPC calls.

Returns
TypeDescription
LazyDatastoreQuery

A LazyDatastoreQuery representing the lazy query results.

Remarks

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.

Example
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
GqlQuery gqlQuery = new GqlQuery
{
    QueryString = "SELECT * FROM book WHERE author = @author",
    NamedBindings = { { "author", "Jane Austen" } },
};
LazyDatastoreQuery results = db.RunQueryLazily(gqlQuery);
// 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, Nullable<ReadOptions.Types.ReadConsistency>, CallSettings)

public virtual LazyDatastoreQuery RunQueryLazily(Query query, ReadOptions.Types.ReadConsistency? readConsistency = null, CallSettings callSettings = null)

Lazily executes the given structured query.

Parameters
NameDescription
queryQuery

The query to execute. Must not be null.

readConsistencyNullable<ReadOptions.Types.ReadConsistency>

If not null, overrides the read consistency of the query.

callSettingsCallSettings

If not null, applies overrides to RPC calls.

Returns
TypeDescription
LazyDatastoreQuery

A LazyDatastoreQuery representing the lazy query results.

Remarks

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.

Example
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
Query query = new Query("book")
{
    Filter = Filter.Equal("author", "Jane Austen")
};
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, Nullable<ReadOptions.Types.ReadConsistency>, CallSettings)

public virtual AsyncLazyDatastoreQuery RunQueryLazilyAsync(GqlQuery gqlQuery, ReadOptions.Types.ReadConsistency? readConsistency = null, CallSettings callSettings = null)

Lazily executes the given GQL query for asynchronous consumption.

Parameters
NameDescription
gqlQueryGqlQuery

The query to execute. Must not be null.

readConsistencyNullable<ReadOptions.Types.ReadConsistency>

If not null, overrides the read consistency of the query.

callSettingsCallSettings

If not null, applies overrides to RPC calls.

Returns
TypeDescription
AsyncLazyDatastoreQuery

An AsyncLazyDatastoreQuery representing the lazy query results.

Remarks

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.

Example
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
GqlQuery gqlQuery = new GqlQuery
{
    QueryString = "SELECT * FROM book WHERE author = @author",
    NamedBindings = { { "author", "Jane Austen" } },
};
AsyncLazyDatastoreQuery results = db.RunQueryLazilyAsync(gqlQuery);
// AsyncLazyDatastoreQuery implements IAsyncEnumerable<Entity>, but you can
// call AsResponses() to see the raw RPC responses, or
// GetAllResultsAsync() to get all the results into memory, complete with
// the end cursor and the reason for the query finishing.
await results.ForEachAsync(entity =>
{
    Console.WriteLine(entity);
});

RunQueryLazilyAsync(Query, Nullable<ReadOptions.Types.ReadConsistency>, CallSettings)

public virtual AsyncLazyDatastoreQuery RunQueryLazilyAsync(Query query, ReadOptions.Types.ReadConsistency? readConsistency = null, CallSettings callSettings = null)

Lazily executes the given structured query for asynchronous consumption.

Parameters
NameDescription
queryQuery

The query to execute. Must not be null.

readConsistencyNullable<ReadOptions.Types.ReadConsistency>

If not null, overrides the read consistency of the query.

callSettingsCallSettings

If not null, applies overrides to RPC calls.

Returns
TypeDescription
AsyncLazyDatastoreQuery

An AsyncLazyDatastoreQuery representing the lazy query results.

Remarks

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.

Example
DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);
Query query = new Query("book")
{
    Filter = Filter.Equal("author", "Jane Austen")
};
AsyncLazyDatastoreQuery results = db.RunQueryLazilyAsync(query);
// AsyncLazyDatastoreQuery implements IAsyncEnumerable<Entity>, but you can
// call AsResponses() to see the raw RPC responses, or
// GetAllResultsAsync() to get all the results into memory, complete with
// the end cursor and the reason for the query finishing.
await results.ForEachAsync(entity =>
{
    Console.WriteLine(entity);
});

Update(Entity, CallSettings)

public virtual void Update(Entity entity, CallSettings callSettings = null)

Updates a single entity, non-transactionally.

Parameters
NameDescription
entityEntity

The entity to update. Must not be null.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Remarks

This method simply delegates to Update(IEnumerable<Entity>, CallSettings).

Example
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);

// Correct the typo in memory
book["title"] = "To Kill a Mockingbird";
// Then update the entity in Datastore
db.Update(book);

Update(Entity[])

public virtual void Update(params Entity[] entities)

Updates a collection of entities, non-transactionally.

Parameter
NameDescription
entitiesEntity[]

The entities to update. Must not be null or contain null entries.

Remarks

This method simply delegates to Update(IEnumerable<Entity>, CallSettings).

Call settings are not supported on this call due to restrictions with methods containing a parameter array and optional parameters. To specify options, create a collection or array explicitly, and call Update(IEnumerable<Entity>, CallSettings).

Datastore limits the number of entities that can be modified in a Commit operation. Although this method does not use an existing transaction, it still performs all the work in a single Commit operation. When modifying a large number of entities, partition the changes into batches. See Datastore limits for more details on Datastore limits.

Example

See Update for an example using an alternative overload.

Update(IEnumerable<Entity>, CallSettings)

public virtual void Update(IEnumerable<Entity> entities, CallSettings callSettings = null)

Updates a collection of entities, non-transactionally.

Parameters
NameDescription
entitiesIEnumerable<Entity>

The entities to update. Must not be null or contain null entries.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Remarks

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.

Example

See Update for an example using an alternative overload.

UpdateAsync(Entity, CallSettings)

public virtual Task UpdateAsync(Entity entity, CallSettings callSettings = null)

Updates a single entity, non-transactionally and asynchronously.

Parameters
NameDescription
entityEntity

The entity to update. Must not be null.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
Task

A task representing the asynchronous operation.

Remarks

This method simply delegates to UpdateAsync(IEnumerable<Entity>, CallSettings).

Example

See Update for a synchronous example.

UpdateAsync(Entity[])

public virtual Task UpdateAsync(params Entity[] entities)

Updates a collection of entities, non-transactionally and asynchronously.

Parameter
NameDescription
entitiesEntity[]

The entities to update. Must not be null or contain null entries.

Returns
TypeDescription
Task

A task representing the asynchronous operation.

Remarks

This method simply delegates to UpdateAsync(IEnumerable<Entity>, CallSettings).

Call settings are not supported on this call due to restrictions with methods containing a parameter array and optional parameters. To specify options, create a collection or array explicitly, and call UpdateAsync(IEnumerable<Entity>, CallSettings).

Datastore limits the number of entities that can be modified in a Commit operation. Although this method does not use an existing transaction, it still performs all the work in a single Commit operation. When modifying a large number of entities, partition the changes into batches. See Datastore limits for more details on Datastore limits.

Example

See Update for a synchronous example.

UpdateAsync(IEnumerable<Entity>, CallSettings)

public virtual Task UpdateAsync(IEnumerable<Entity> entities, CallSettings callSettings = null)

Updates a collection of entities, non-transactionally and asynchronously.

Parameters
NameDescription
entitiesIEnumerable<Entity>

The entities to update. Must not be null or contain null entries.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
Task

A task representing the asynchronous operation.

Remarks

Datastore limits the number of entities that can be modified in a Commit operation. Although this method does not use an existing transaction, it still performs all the work in a single Commit operation. When modifying a large number of entities, partition the changes into batches. See Datastore limits for more details on Datastore limits.

Example

See Update for a synchronous example.

Upsert(Entity, CallSettings)

public virtual Key Upsert(Entity entity, CallSettings callSettings = null)

Upserts a single entity, non-transactionally.

Parameters
NameDescription
entityEntity

The entity to upsert. Must not be null.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
Key

null if the entity was updated or was inserted with a predefined key, or the new key if the entity was inserted and the mutation allocated the key.

Remarks

On success, if entity has an incomplete key it will be updated in memory with the server-allocated keys.

This method simply delegates to Upsert(IEnumerable<Entity>, CallSettings).

Example

See Upsert for an example using an alternative overload.

Upsert(Entity[])

public virtual IReadOnlyList<Key> Upsert(params Entity[] entities)

Upserts a collection of entities, non-transactionally.

Parameter
NameDescription
entitiesEntity[]

The entities to upsert. Must not be null or contain null entries.

Returns
TypeDescription
IReadOnlyList<Key>

A collection of allocated keys, in the same order as entities. Each inserted entity which had an incomplete key - requiring the server to allocate a new key - will have a non-null value in the collection, equal to the new key for the entity. Each updated entity or inserted entity with a predefined key will have a null value in the collection.

Remarks

This method simply delegates to Upsert(IEnumerable<Entity>, CallSettings).

Datastore limits the number of entities that can be modified in a Commit operation. Although this method does not use an existing transaction, it still performs all the work in a single Commit operation. When modifying a large number of entities, partition the changes into batches. See Datastore limits for more details on Datastore limits.

Call settings are not supported on this call due to restrictions with methods containing a parameter array and optional parameters. To specify options, create a collection or array explicitly, and call Upsert(IEnumerable<Entity>, CallSettings).

Example
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);

// 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" }
};

// Update book1 and insert book2 into Datastore
db.Upsert(book1, book2);

Upsert(IEnumerable<Entity>, CallSettings)

public virtual IReadOnlyList<Key> Upsert(IEnumerable<Entity> entities, CallSettings callSettings = null)

Upserts a collection of entities, non-transactionally.

Parameters
NameDescription
entitiesIEnumerable<Entity>

The entities to upsert. Must not be null or contain null entries.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
IReadOnlyList<Key>

A collection of allocated keys, in the same order as entities. Each inserted entity which had an incomplete key - requiring the server to allocate a new key - will have a non-null value in the collection, equal to the new key for the entity. Each updated entity or inserted entity with a predefined key will have a null value in the collection.

Remarks

On success, any entities with incomplete keys will be updated in memory with the server-allocated keys.

Datastore limits the number of entities that can be modified in a Commit operation. Although this method does not use an existing transaction, it still performs all the work in a single Commit operation. When modifying a large number of entities, partition the changes into batches. See Datastore limits for more details on Datastore limits.

Example

See Upsert for an example using an alternative overload.

UpsertAsync(Entity, CallSettings)

public virtual async Task<Key> UpsertAsync(Entity entity, CallSettings callSettings = null)

Upserts a single entity, non-transactionally and asynchronously.

Parameters
NameDescription
entityEntity

The entity to upsert. Must not be null.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
Task<Key>

A task representing the asynchronous operation. The result of the task is null if the entity was updated or was inserted with a predefined key, or the new key if the entity was inserted and the mutation allocated the key.

Remarks

This method simply delegates to UpsertAsync(IEnumerable<Entity>, CallSettings).

Example

See Update for a synchronous example.

UpsertAsync(Entity[])

public virtual Task<IReadOnlyList<Key>> UpsertAsync(params Entity[] entities)

Upserts a collection of entities, non-transactionally and asynchronously.

Parameter
NameDescription
entitiesEntity[]

The entities to upsert. Must not be null or contain null entries.

Returns
TypeDescription
Task<IReadOnlyList<Key>>

A task representing the asynchronous operation. The result of the task is a collection of allocated keys, in the same order as entities. Each inserted entity which had an incomplete key - requiring the server to allocate a new key - will have a non-null value in the collection, equal to the new key for the entity. Each updated entity or inserted entity with a predefined key will have a null value in the collection.

Remarks

This method simply delegates to UpsertAsync(IEnumerable<Entity>, CallSettings).

Call settings are not supported on this call due to restrictions with methods containing a parameter array and optional parameters. To specify options, create a collection or array explicitly, and call UpsertAsync(IEnumerable<Entity>, CallSettings).

Datastore limits the number of entities that can be modified in a Commit operation. Although this method does not use an existing transaction, it still performs all the work in a single Commit operation. When modifying a large number of entities, partition the changes into batches. See Datastore limits for more details on Datastore limits.

Example

See Update for a synchronous example.

UpsertAsync(IEnumerable<Entity>, CallSettings)

public virtual Task<IReadOnlyList<Key>> UpsertAsync(IEnumerable<Entity> entities, CallSettings callSettings = null)

Upserts a collection of entities, non-transactionally and asynchronously.

Parameters
NameDescription
entitiesIEnumerable<Entity>

The entities to upsert. Must not be null or contain null entries.

callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
Task<IReadOnlyList<Key>>

A task representing the asynchronous operation. The result of the task is a collection of allocated keys, in the same order as entities. Each inserted entity which had an incomplete key - requiring the server to allocate a new key - will have a non-null value in the collection, equal to the new key for the entity. Each updated entity or inserted entity with a predefined key will have a null value in the collection.

Remarks

On success, any entities with incomplete keys will be updated with the server-allocated keys.

Datastore limits the number of entities that can be modified in a Commit operation. Although this method does not use an existing transaction, it still performs all the work in a single Commit operation. When modifying a large number of entities, partition the changes into batches. See Datastore limits for more details on Datastore limits.

Example

See Update for a synchronous example.