Class DatastoreDb (4.0.0)

public abstract 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

Inherited Members

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Object.ToString()

Derived Types

DatastoreDbImpl

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
Type	Description
`DatastoreClient`

NamespaceId

public virtual string NamespaceId { get; }

The ID of the namespace this instance operates on.

Property Value
Type	Description
`String`

ProjectId

public virtual string ProjectId { get; }

The ID of the project this instance operates on.

Property Value
Type	Description
`String`

Methods

AllocateId(Key, CallSettings)

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

Allocates an ID for a single incomplete key.

Parameters
Name	Description
`key`	`Key` The incomplete key to allocate an ID for.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`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
Name	Description
`key`	`Key` The incomplete key to allocate an ID for.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`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
Name	Description
`keys`	`Key[]` The incomplete keys. Must not be null or contain null elements.

Returns
Type	Description
`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
Name	Description
`keys`	`IEnumerable<Key>` The incomplete keys. Must not be null or contain null elements.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`IReadOnlyList<Key>`	A collection of complete keys with allocated IDs, in the same order as `keys`.

Remarks

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
Name	Description
`keys`	`Key[]` The incomplete keys. Must not be null or contain null elements.

Returns
Type	Description
`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).

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
Name	Description
`keys`	`IEnumerable<Key>` The incomplete keys. Must not be null or contain null elements.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`Task<IReadOnlyList<Key>>`	A collection of complete keys with allocated IDs, in the same order as `keys`.

Remarks

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
Name	Description
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`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
Name	Description
`options`	`TransactionOptions` The options for the new transaction. May be null, for default options.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`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
Name	Description
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`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
Name	Description
`options`	`TransactionOptions` The options for the new transaction. May be null, for default options.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`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
Name	Description
`projectId`	`String` The project ID to use in all operations.
`namespaceId`	`String` The namespace ID to use in operations requiring a partition.
`client`	`DatastoreClient` The client to use for remote operations. If this is null, an instance will be created using default settings.

Returns
Type	Description
`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
Name	Description
`kind`	`String` The kind of entity key to create. Must not be null.

Returns
Type	Description
`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
Name	Description
`entity`	`Entity` The entity to delete. Must not be null.
`callSettings`	`CallSettings` 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
Name	Description
`entities`	`Entity[]` The entities to delete. Must not be null or contain null entries.

Remarks

This method simply delegates to 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
Name	Description
`key`	`Key` The key to delete. Must not be null.
`callSettings`	`CallSettings` 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
Name	Description
`keys`	`Key[]` The keys to delete. Must not be null or contain null entries.

Remarks

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

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
Name	Description
`entities`	`IEnumerable<Entity>` The entities to delete. Must not be null or contain null entries.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Remarks

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
Name	Description
`keys`	`IEnumerable<Key>` The keys to delete. Must not be null or contain null entries.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Remarks

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
Name	Description
`entity`	`Entity` The entity to delete. Must not be null.
`callSettings`	`CallSettings` If not null, applies overrides to RPC calls.

Returns
Type	Description
`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
Name	Description
`entities`	`Entity[]` The entities to delete. Must not be null or contain null entries.

Returns
Type	Description
`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(Key, CallSettings)

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

Deletes a single key, non-transactionally and asynchronously.

Parameters
Name	Description
`key`	`Key` The key to delete. Must not be null.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`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
Name	Description
`keys`	`Key[]` The keys to delete. Must not be null or contain null entries.

Returns
Type	Description
`Task`

Remarks

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

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
Name	Description
`entities`	`IEnumerable<Entity>` The entities to delete. Must not be null or contain null entries.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`Task`	A task representing the asynchronous operation.

Remarks

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
Name	Description
`keys`	`IEnumerable<Key>` The keys to delete. Must not be null or contain null entries.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`Task`

Remarks

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
Name	Description
`entity`	`Entity` The entity to insert. Must not be null.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`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
Name	Description
`entities`	`Entity[]` The entities to insert. Must not be null or contain null entries.

Returns
Type	Description
`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).

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
Name	Description
`entities`	`IEnumerable<Entity>` The entities to insert. Must not be null or contain null entries.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`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.

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
Name	Description
`entity`	`Entity` The entity to insert. Must not be null.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`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
Name	Description
`entities`	`Entity[]` The entities to insert. Must not be null or contain null entries.

Returns
Type	Description
`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).

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
Name	Description
`entities`	`IEnumerable<Entity>` The entities to insert. Must not be null or contain null entries.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`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
Name	Description
`key`	`Key` The key to look up. Must not be null, and must be complete.
`readConsistency`	`Nullable<ReadOptions.Types.ReadConsistency>` The desired read consistency of the lookup, or null to use the default.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`Entity`	The entity with the specified key, or `null` if no such entity exists.

Remarks

This method simply delegates to Lookup(IEnumerable<Key>, Nullable<ReadOptions.Types.ReadConsistency>, CallSettings).

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
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
`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.

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
Name	Description
`keys`	`IEnumerable<Key>` The keys to look up. Must not be null, and every element must be non-null and refer to a complete key.
`readConsistency`	`Nullable<ReadOptions.Types.ReadConsistency>` The desired read consistency of the lookup, or null to use the default.
`callSettings`	`CallSettings` If not null, applies overrides to RPC calls.

Returns
Type	Description
`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.

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
Name	Description
`key`	`Key` The key to look up. Must not be null, and must be complete.
`readConsistency`	`Nullable<ReadOptions.Types.ReadConsistency>` The desired read consistency of the lookup, or null to use the default.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`Task<Entity>`	The entity with the specified key, or `null` if no such entity exists.

Remarks

This method simply delegates to LookupAsync(IEnumerable<Key>, Nullable<ReadOptions.Types.ReadConsistency>, CallSettings).

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
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
`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.

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
Name	Description
`keys`	`IEnumerable<Key>` The keys to look up. Must not be null, and every element must be non-null and refer to a complete key.
`readConsistency`	`Nullable<ReadOptions.Types.ReadConsistency>` The desired read consistency of the lookup, or null to use the default.
`callSettings`	`CallSettings` If not null, applies overrides to RPC calls.

Returns
Type	Description
`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.

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
Name	Description
`query`	`GqlQuery` The query to execute. Must not be null.
`readConsistency`	`Nullable<ReadOptions.Types.ReadConsistency>` If not null, overrides the read consistency of the query.
`callSettings`	`CallSettings` If not null, applies overrides to RPC calls.

Returns
Type	Description
`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)

Parameters
Name	Description
`query`	`Query` The query to execute. Must not be null.
`readConsistency`	`Nullable<ReadOptions.Types.ReadConsistency>` If not null, overrides the read consistency of the query.
`callSettings`	`CallSettings` If not null, applies overrides to RPC calls.

Returns
Type	Description
`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
Name	Description
`query`	`GqlQuery` The query to execute. Must not be null.
`readConsistency`	`Nullable<ReadOptions.Types.ReadConsistency>` If not null, overrides the read consistency of the query.
`callSettings`	`CallSettings` If not null, applies overrides to RPC calls.

Returns
Type	Description
`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)

Parameters
Name	Description
`query`	`Query` The query to execute. Must not be null.
`readConsistency`	`Nullable<ReadOptions.Types.ReadConsistency>` If not null, overrides the read consistency of the query.
`callSettings`	`CallSettings` If not null, applies overrides to RPC calls.

Returns
Type	Description
`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
Name	Description
`gqlQuery`	`GqlQuery` The query to execute. Must not be null.
`readConsistency`	`Nullable<ReadOptions.Types.ReadConsistency>` If not null, overrides the read consistency of the query.
`callSettings`	`CallSettings` If not null, applies overrides to RPC calls.

Returns
Type	Description
`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
Name	Description
`query`	`Query` The query to execute. Must not be null.
`readConsistency`	`Nullable<ReadOptions.Types.ReadConsistency>` If not null, overrides the read consistency of the query.
`callSettings`	`CallSettings` If not null, applies overrides to RPC calls.

Returns
Type	Description
`LazyDatastoreQuery`	A LazyDatastoreQuery representing the lazy query results.

Remarks

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
Name	Description
`gqlQuery`	`GqlQuery` The query to execute. Must not be null.
`readConsistency`	`Nullable<ReadOptions.Types.ReadConsistency>` If not null, overrides the read consistency of the query.
`callSettings`	`CallSettings` If not null, applies overrides to RPC calls.

Returns
Type	Description
`AsyncLazyDatastoreQuery`	An AsyncLazyDatastoreQuery representing the lazy query results.

Remarks

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
Name	Description
`query`	`Query` The query to execute. Must not be null.
`readConsistency`	`Nullable<ReadOptions.Types.ReadConsistency>` If not null, overrides the read consistency of the query.
`callSettings`	`CallSettings` If not null, applies overrides to RPC calls.

Returns
Type	Description
`AsyncLazyDatastoreQuery`	An AsyncLazyDatastoreQuery representing the lazy query results.

Remarks

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
Name	Description
`entity`	`Entity` The entity to update. Must not be null.
`callSettings`	`CallSettings` 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
Name	Description
`entities`	`Entity[]` The entities to update. Must not be null or contain null entries.

Remarks

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

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
Name	Description
`entities`	`IEnumerable<Entity>` The entities to update. Must not be null or contain null entries.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Remarks

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
Name	Description
`entity`	`Entity` The entity to update. Must not be null.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`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
Name	Description
`entities`	`Entity[]` The entities to update. Must not be null or contain null entries.

Returns
Type	Description
`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(IEnumerable<Entity>, CallSettings)

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

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

Parameters
Name	Description
`entities`	`IEnumerable<Entity>` The entities to update. Must not be null or contain null entries.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`Task`	A task representing the asynchronous operation.

Remarks

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
Name	Description
`entity`	`Entity` The entity to upsert. Must not be null.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`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
Name	Description
`entities`	`Entity[]` The entities to upsert. Must not be null or contain null entries.

Returns
Type	Description
`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).

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
Name	Description
`entities`	`IEnumerable<Entity>` The entities to upsert. Must not be null or contain null entries.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`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.

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
Name	Description
`entity`	`Entity` The entity to upsert. Must not be null.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns
Type	Description
`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
Name	Description
`entities`	`Entity[]` The entities to upsert. Must not be null or contain null entries.

Returns

Type Description

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).

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
Name	Description
`entities`	`IEnumerable<Entity>` The entities to upsert. Must not be null or contain null entries.
`callSettings`	`CallSettings` If not null, applies overrides to this RPC call.

Returns

Type Description

Task<IReadOnlyList<Key>>

Remarks

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

Example

See Update for a synchronous example.