Google Cloud Datastore v1 API - Class DatastoreDbImpl (4.3.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
NameDescription
projectIdString

The project ID. Must not be null.

namespaceIdString

The namespace ID. Must not be null.

clientDatastoreClient

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.

Properties

Client

public override DatastoreClient Client { get; }

The DatastoreClient used for all remote operations.

Property Value
TypeDescription
DatastoreClient
Overrides

NamespaceId

public override string NamespaceId { get; }

The ID of the namespace this instance operates on.

Property Value
TypeDescription
String
Overrides

ProjectId

public override string ProjectId { get; }

The ID of the project this instance operates on.

Property Value
TypeDescription
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
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.

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

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
NameDescription
callSettingsCallSettings

If not null, applies overrides to this RPC call.

Returns
TypeDescription
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
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.

Overrides

BeginTransactionAsync(CallSettings)

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

Overrides

BeginTransactionAsync(TransactionOptions, CallSettings)

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

Overrides

CreateKeyFactory(String)

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

Overrides

Delete(IEnumerable<Entity>, CallSettings)

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

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

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

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

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

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>, Nullable<ReadOptions.Types.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
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.

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>, Nullable<ReadOptions.Types.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
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.

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.

RunQueryLazily(GqlQuery, Nullable<ReadOptions.Types.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
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.

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, Nullable<ReadOptions.Types.ReadConsistency>, CallSettings)

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

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, Nullable<ReadOptions.Types.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
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.

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, Nullable<ReadOptions.Types.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
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.

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

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

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

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

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.