Google.Cloud.Datastore.V1

Google.Cloud.Datastore.V1 is a.NET client library for the Google Cloud Datastore API.

Note: This documentation is for version 3.5.0 of the library. Some samples may not work with other versions.

Installation

Install the Google.Cloud.Datastore.V1 package from NuGet. Add it to your project in the normal way (for example by right-clicking on the project in Visual Studio and choosing "Manage NuGet Packages...").

Authentication

When running on Google Cloud Platform, no action needs to be taken to authenticate.

Otherwise, the simplest way of authenticating your API calls is to download a service account JSON file then set the GOOGLE_APPLICATION_CREDENTIALS environment variable to refer to it. The credentials will automatically be used to authenticate. See the Getting Started With Authentication guide for more details.

Getting started

See the Datastore Quickstart for an introduction with runnable code samples.

The DatastoreDb class is provided as a wrapper for DatastoreClient, simplifying operations considerably by assuming all operations act on the same partition, and providing page streaming operations on structured query results.

Several custom conversions, additional constructors, factory methods (particularly on Filter are provided to simplify working with the protobuf messages.

Support for emulator detection

As of 2.2.0-beta02 and 2.2.0, the library has support for detecting the emulator via environment variables, if requested. This is configured via DatastoreDbBuilder, which can also be used to configure custom credentials easily.

The following code creates a DatastoreDb which will use the emulator when the environment variables are present, but will otherwise connect to the production environment.

DatastoreDb db = new DatastoreDbBuilder
{
    ProjectId = projectId,
    EmulatorDetection = EmulatorDetection.EmulatorOrProduction
}.Build();
// Use db as normal

See the EmulatorDetection enum for details of the other possible values.

Sample code

Inserting data

DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);

KeyFactory keyFactory = db.CreateKeyFactory("message");
Entity entity = new Entity
{
    Key = keyFactory.CreateIncompleteKey(),
    ["created"] = DateTime.UtcNow,
    ["text"] = "Text of the message",
    ["tags"] = new[] { "tag1", "tag2" }
};
using (DatastoreTransaction transaction = db.BeginTransaction())
{
    transaction.Insert(entity);
    CommitResponse commitResponse = transaction.Commit();
    Key insertedKey = commitResponse.MutationResults[0].Key;
    Console.WriteLine($"Inserted key: {insertedKey}");
    // The key is also propagated to the entity
    Console.WriteLine($"Entity key: {entity.Key}");
}

Querying data

DatastoreDb db = DatastoreDb.Create(projectId, namespaceId);

// Print the messages created in the last 5 minutes, most recent first
DateTime cutoff = DateTime.UtcNow.AddMinutes(-5);
Query query = new Query("message")
{
    Filter = Filter.GreaterThanOrEqual("created", cutoff),
    Order = { { "created", Direction.Descending } }
};
foreach (Entity entity in db.RunQueryLazily(query))
{
    DateTime created = (DateTime)entity["created"];
    string text = (string)entity["text"];
    Console.WriteLine($"{created:yyyy-MM-dd'T'HH:mm:ss}: {text}");
}

When a query contains a projection, any timestamp fields will be returned using integer values. Use the Value.ToDateTimeFromProjection and Value.ToDateTimeOffsetFromProjection methods to convert either integer or timestamp values to DateTime or DateTimeOffset.

Lots more samples: github.com/googleapis/dotnet-docs-samples