Google Cloud Datastore v1 API - Class DatastoreDbImpl (4.11.0)

public sealed class DatastoreDbImpl : DatastoreDb

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

Wrapper around DatastoreClient to provide simpler operations.

Inheritance

object > DatastoreDb > DatastoreDbImpl

Namespace

Google.Cloud.Datastore.V1

Assembly

Google.Cloud.Datastore.V1.dll

Remarks

This is the "default" implementation of DatastoreDb. Most client code should refer to DatastoreDb, creating instances with Create(string, string, DatastoreClient). The constructor of this class is public for the sake of constructor-based dependency injection.

Constructors

DatastoreDbImpl(string, string, DatastoreClient)

public DatastoreDbImpl(string projectId, string namespaceId, DatastoreClient client)

Constructs an instance from the given project ID, namespace ID and client.

Parameters
Name Description
projectId string

The project ID. Must not be null.

namespaceId string

The namespace ID. Must not be null.

client DatastoreClient

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

Remarks

This constructor is primarily provided for constructor-based dependency injection. The static Create(string, string, DatastoreClient) method is provided for manually obtaining an instance, including automatic client creation.

DatastoreDbImpl(string, string, string, DatastoreClient)

public DatastoreDbImpl(string projectId, string namespaceId, string databaseId, DatastoreClient client)

Constructs an instance from the given project ID, namespace ID and client.

Parameters
Name Description
projectId string

The project ID. Must not be null.

namespaceId string

The namespace ID. Must not be null.

databaseId string

The database ID. Must not be null.

client DatastoreClient

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

Properties

Client

public override DatastoreClient Client { get; }

The DatastoreClient used for all remote operations.

Property Value
Type Description
DatastoreClient
Overrides

DatabaseId

public override string DatabaseId { get; }

The ID of the database against which the request is to be made.

Property Value
Type Description
string
Overrides

NamespaceId

public override string NamespaceId { get; }

The ID of the namespace this instance operates on.

Property Value
Type Description
string
Overrides

ProjectId

public override string ProjectId { get; }

The ID of the project this instance operates on.

Property Value
Type Description
string
Overrides

Methods

AllocateIds(IEnumerable<Key>, CallSettings)

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

Allocates IDs for a collection of incomplete keys.

Parameters
Name Description
keys IEnumerableKey

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
IReadOnlyListKey

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

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

AllocateIdsAsync(IEnumerable<Key>, CallSettings)

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

Allocates IDs for a collection of incomplete keys asynchronously.

Parameters
Name Description
keys IEnumerableKey

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
TaskIReadOnlyListKey

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

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

BeginTransaction(CallSettings)

public override 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.

Overrides

BeginTransaction(TransactionOptions, CallSettings)

public override 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.

Overrides

BeginTransactionAsync(CallSettings)

public override 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
TaskDatastoreTransaction

A new DatastoreTransaction for this object's project.

Overrides

BeginTransactionAsync(TransactionOptions, CallSettings)

public override 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
TaskDatastoreTransaction

A new DatastoreTransaction for this object's project.

Overrides

CreateKeyFactory(string)

public override 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.

Overrides

Delete(IEnumerable<Entity>, CallSettings)

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

Deletes a collection of entities, non-transactionally.

Parameters
Name Description
entities IEnumerableEntity

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

callSettings CallSettings

If not null, applies overrides to this RPC call.

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

Delete(IEnumerable<Key>, CallSettings)

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

Deletes a collection of keys, non-transactionally.

Parameters
Name Description
keys IEnumerableKey

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

callSettings CallSettings

If not null, applies overrides to this RPC call.

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

DeleteAsync(IEnumerable<Entity>, CallSettings)

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

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

Parameters
Name Description
entities IEnumerableEntity

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.

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

DeleteAsync(IEnumerable<Key>, CallSettings)

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

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

Parameters
Name Description
keys IEnumerableKey

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

Insert(IEnumerable<Entity>, CallSettings)

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

Inserts a collection of entities, non-transactionally.

Parameters
Name Description
entities IEnumerableEntity

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
IReadOnlyListKey

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.

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

InsertAsync(IEnumerable<Entity>, CallSettings)

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

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

Parameters
Name Description
entities IEnumerableEntity

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
TaskIReadOnlyListKey

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.

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

Lookup(IEnumerable<Key>, ReadConsistency?, CallSettings)

public override 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 IEnumerableKey

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

readConsistency ReadOptionsTypesReadConsistency

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
IReadOnlyListEntity

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

Overrides Remarks

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

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.

LookupAsync(IEnumerable<Key>, ReadConsistency?, CallSettings)

public override 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 IEnumerableKey

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

readConsistency ReadOptionsTypesReadConsistency

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
TaskIReadOnlyListEntity

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

Overrides Remarks

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

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.

RunAggregationQuery(AggregationQuery, ReadConsistency?, CallSettings)

public override AggregationQueryResults RunAggregationQuery(AggregationQuery query, ReadOptions.Types.ReadConsistency? readConsistency = null, CallSettings callSettings = null)

Executes the given structured query.

Parameters
Name Description
query AggregationQuery

The query to execute. Must not be null.

readConsistency ReadOptionsTypesReadConsistency

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

callSettings CallSettings

If not null, applies overrides to RPC calls.

Returns
Type Description
AggregationQueryResults

An AggregationQueryResults holds result of aggregations.

Overrides

RunAggregationQuery(GqlQuery, ReadConsistency?, CallSettings)

public override AggregationQueryResults RunAggregationQuery(GqlQuery query, ReadOptions.Types.ReadConsistency? readConsistency = null, CallSettings callSettings = null)

Executes the given GQL query.

Parameters
Name Description
query GqlQuery

The query to execute. Must not be null.

readConsistency ReadOptionsTypesReadConsistency

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

callSettings CallSettings

If not null, applies overrides to RPC calls.

Returns
Type Description
AggregationQueryResults

An AggregationQueryResults holds result of aggregations.

Overrides

RunAggregationQueryAsync(AggregationQuery, ReadConsistency?, CallSettings)

public override Task<AggregationQueryResults> RunAggregationQueryAsync(AggregationQuery query, ReadOptions.Types.ReadConsistency? readConsistency = null, CallSettings callSettings = null)

Executes the given structured query.

Parameters
Name Description
query AggregationQuery

The query to execute. Must not be null.

readConsistency ReadOptionsTypesReadConsistency

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

callSettings CallSettings

If not null, applies overrides to RPC calls.

Returns
Type Description
TaskAggregationQueryResults

An AggregationQueryResults holds result of aggregations.

Overrides

RunAggregationQueryAsync(GqlQuery, ReadConsistency?, CallSettings)

public override Task<AggregationQueryResults> RunAggregationQueryAsync(GqlQuery query, ReadOptions.Types.ReadConsistency? readConsistency = null, CallSettings callSettings = null)

Executes the given GQL query.

Parameters
Name Description
query GqlQuery

The query to execute. Must not be null.

readConsistency ReadOptionsTypesReadConsistency

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

callSettings CallSettings

If not null, applies overrides to RPC calls.

Returns
Type Description
TaskAggregationQueryResults

An AggregationQueryResults holds result of aggregations.

Overrides

RunQueryLazily(GqlQuery, ReadConsistency?, CallSettings)

public override 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 ReadOptionsTypesReadConsistency

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.

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

RunQueryLazily(Query, ReadConsistency?, CallSettings)

public override 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 ReadOptionsTypesReadConsistency

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.

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

RunQueryLazilyAsync(GqlQuery, ReadConsistency?, CallSettings)

public override 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 ReadOptionsTypesReadConsistency

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.

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

RunQueryLazilyAsync(Query, ReadConsistency?, CallSettings)

public override 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 ReadOptionsTypesReadConsistency

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.

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

Update(IEnumerable<Entity>, CallSettings)

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

Updates a collection of entities, non-transactionally.

Parameters
Name Description
entities IEnumerableEntity

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

callSettings CallSettings

If not null, applies overrides to this RPC call.

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

UpdateAsync(IEnumerable<Entity>, CallSettings)

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

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

Parameters
Name Description
entities IEnumerableEntity

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.

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

Upsert(IEnumerable<Entity>, CallSettings)

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

Upserts a collection of entities, non-transactionally.

Parameters
Name Description
entities IEnumerableEntity

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
IReadOnlyListKey

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.

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

UpsertAsync(IEnumerable<Entity>, CallSettings)

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

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

Parameters
Name Description
entities IEnumerableEntity

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
TaskIReadOnlyListKey

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.

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