Google.Cloud.Bigtable.V2

Google.Cloud.Bigtable.V2 is a.NET client library for the Google Bigtable API.

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

Installation

Install the Google.Cloud.Bigtable.V2 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..."). Please ensure you enable pre-release packages (for example, in the Visual Studio NuGet user interface, check the "Include prerelease" box). Some of the following samples might only work with the latest pre-release version (3.10.0-beta01) of Google.Cloud.Bigtable.V2.

Authentication

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

Otherwise, the simplest way of authenticating your API calls is to set up Application Default Credentials. The credentials will automatically be used to authenticate. See Set up Application Default Credentials for more details.

Getting started

Common operations are exposed via the BigtableClient class.

Sample code

BigtableClient client = BigtableClient.Create();
TableName tableName = new TableName(projectId, instanceId, tableId);

// Insert a row with some cells into the table
await client.MutateRowAsync(
    tableName,
    "user12345",
    Mutations.SetCell(
        familyName: "Score",
        columnQualifier: "Level 1",
        value: 456),
    Mutations.SetCell(
        familyName: "metrics",
        columnQualifier: "Level 1 - total time",
        value: 12000));

// Read the row back from the table, but only the latest cell values
// from the 'Score' column family
Row row = await client.ReadRowAsync(
    tableName,
    "user12345",
    filter: RowFilters.Chain(
        RowFilters.FamilyNameExact("Score"),
        RowFilters.CellsPerColumnLimit(1)));

foreach (Family family in row.Families)
{
    string familyName = family.Name;
    Console.WriteLine($"Family: {familyName}");

    foreach (Column column in family.Columns)
    {
        BigtableByteString columnQualifier = column.Qualifier;
        BigtableByteString cellValue = column.Cells[0].Value;
        Console.WriteLine(
            $"\tColumn: {(string)columnQualifier}, Value: {(long)cellValue}");
    }
}

Client life-cycle management

By default, clients share an internally managed Grpc.Gcp.GcpCallInvoker to establish gRPC channels with the Bigtable service using default credentials. This class allows for multiple channels to be used concurrently and load-balances requests and streams among them. BigtableClient instances are intended to be ephermal and will reuse an existing GcpCallInvoker instance behind the scenes where possible.

Note that this reuse is dependent upon the settings which control the usage of the GcpCallInvoker instance being identical. Accidentally using different settings when creating different clients could result in unintended performance degredation as setting up a new GcpCallInvoker is expensive compared to creating a new BigtableClient.

// client1 and client3 will share the same GcpCallInvoker, since they both
// use the same default settings. This means they will use the same shared
// set of gRPC channels to the Bigtable service.
// client2 and client4 will share a different GcpCallInvoker, since they both
// use the same custom MaxChannels/PreferredMaxStreamsPerChannel settings.
BigtableServiceApiSettings settings1 = BigtableServiceApiSettings.GetDefault();
BigtableClient client1 = new BigtableClientBuilder { Settings = settings1 }.Build();

BigtableServiceApiSettings settings2 = new BigtableServiceApiSettings
{
    MaxChannels = 10,
    PreferredMaxStreamsPerChannel = 4
};
BigtableClient client2 = new BigtableClientBuilder { Settings = settings2 }.Build();

BigtableServiceApiSettings settings3 = BigtableServiceApiSettings.GetDefault();
BigtableClient client3 = new BigtableClientBuilder { Settings = settings3 }.Build();

BigtableServiceApiSettings settings4 = new BigtableServiceApiSettings
{
    MaxChannels = 10,
    PreferredMaxStreamsPerChannel = 4
};
BigtableClient client4 = new BigtableClientBuilder { Settings = settings4 }.Build();

// client5 will not share a GcpCallInvoker with any of the other clients, since
// its MaxChannels/PreferredMaxStreamsPerChannel settings differ from the others.
BigtableServiceApiSettings settings5 = new BigtableServiceApiSettings
{
    MaxChannels = 15,
    PreferredMaxStreamsPerChannel = 4
};
BigtableClient client5 = new BigtableClientBuilder { Settings = settings5 }.Build();

Non-default credentials

If you would like to create clients which share a GcpCallInvoker but do not use the default credentials, this can easily be done by manually creating a GcpCallInvoker and using Bigtable's default endpoint and settings.

// Create a client from a custom credentials and a GcpCallInvoker that has
// non-default gRPC stream/channel options.
// The easiest way of creating a GcpCallInvoker is to use a new
// BigtableServiceApiClientBuilder just to create the call invoker,
// then remember the call invoker to set it in other builders.
// Note: the GcpCallInvoker should be long-lived while the BigtableClient
// instances can be ephemeral and each use the same call invoker.
BigtableServiceApiSettings settings = new BigtableServiceApiSettings
{
    MaxChannels = 10,
    PreferredMaxStreamsPerChannel = 4
};
GcpCallInvoker callInvoker = new BigtableServiceApiClientBuilder
{
    Settings = settings,
    ChannelCredentials = credentials,
}.CreateGcpCallInvoker();

// These will share the same set of channels to the Bigtable service.
BigtableClient client1 = new BigtableClientBuilder
{
    CallInvoker = callInvoker,
    Settings = settings
}.Build();
// ...
BigtableClient client2 = new BigtableClientBuilder
{
    CallInvoker = callInvoker,
    Settings = settings
}.Build();
// ...

await callInvoker.ShutdownAsync();