About app profiles

An application profile, or app profile, stores settings that tell your Cloud Bigtable instance how to handle incoming requests from an application. When an application connects to a Bigtable instance, it can specify an app profile, and Bigtable uses that app profile for requests that the application sends over that connection. An app profile defines the routing policy that Bigtable uses and controls whether single-row transactions are allowed.

App profiles are especially useful for instances that have two or more clusters. Even if your instance has only one cluster, you can use a unique app profile for each application that you run, or for different components within a single application. You can then view separate graphs of your Bigtable metrics for each app profile.

This page explains the settings that an app profile controls, as well as how app profiles work with your application.

If you're using app profiles to configure cluster routing policies, you should be familiar with the overview of Bigtable replication before you read this page.

Routing policy

An app profile specifies the routing policy that Bigtable should use for each request.

Single-cluster routing routes all requests to 1 cluster in your instance. If that cluster becomes unavailable, you must manually fail over to another cluster.
Multi-cluster routing automatically routes requests to the nearest cluster in an instance. If the cluster becomes unavailable, traffic automatically fails over to the nearest cluster that is available. Bigtable considers clusters in a single region to be equidistant, even though they are in different zones. You can configure an app profile to route to any cluster in an instance, or you can specify a cluster group that tells the app profile to route to only some of the clusters in the instance.
Cluster group routing sends requests to the nearest available cluster within a cluster group that you specify in the app profile settings.

For more information about failovers, see Failovers. To learn how to complete a failover, see Managing Failovers.

Single-row transactions

In Bigtable mutations, such as read, write, and delete requests, are always atomic at the row level. This includes mutations to multiple columns in a single row, as long as they are included in the same mutation operation. Bigtable does not support transactions that atomically update more than one row.

However, Bigtable supports some write operations that would require a transaction in other databases. In effect, Bigtable uses single-row transactions to complete these operations. These operations include reads and writes, and all of the reads and writes are executed atomically, but the operations are still atomic only at the row level:

Read-modify-write operations, including increments and appends. A read-modify-write operation reads an existing value; increments or appends to the existing value; and writes the updated value to the table.
Check-and-mutate operations, also known as conditional mutations or conditional writes. In a check-and-mutate operation, Bigtable checks a row to see if it meets a specified condition. If the condition is met, Bigtable writes new values to the row.

Conflicts between single-row transactions

Every cluster in a Bigtable instance is a primary cluster that accepts both reads and writes. As a result, operations that require single-row transactions can cause problems in multi-cluster instances.

For example, suppose you have a table that you use to store data for a ticketing system. You use an integer counter to store the number of tickets that have been sold. Each time you sell a ticket, your app sends a read-modify-write operation to increment the counter by 1.

If your instance has one cluster, client apps can sell tickets at the same time and increment the counters without data loss because the requests are handled atomically in the order they are received by that single cluster.

On the other hand, if your instance has multiple clusters and your app profile were to allow multi-cluster routing, simultaneous requests to increment the counter might each be sent to different clusters, then replicated to the other clusters in the instance. If you send two increment requests at the same time that are routed to different clusters, each finishes its transaction without "knowing" about the other. The counter on each cluster is incremented by one. When the data is replicated to the other cluster, Bigtable can't possibly know that you meant to increment by 2.

To help you avoid unintended results, Bigtable does the following:

Requires each app profile to specify whether it allows single-row transactions.
Prevents you from enabling single-row transactions in an app profile that uses multi-cluster routing, because there's no safe way to enable both of these features at once.
Warns you if you enable single-row transactions in two or more different app profiles that use single-cluster routing and point to different clusters. If you choose to create this type of configuration, you must ensure that you do not send conflicting read-modify-write or check-and-mutate requests to different clusters.

How app profiles work

An app profile specifies the settings that Bigtable uses to handle an instance's incoming requests.

Many Bigtable users have multiple applications that connect to the same instance. For example, you might have one application that serves data to customers on request, and another application that runs occasional batch jobs to analyze your data. To handle these different applications, you should create multiple app profiles—at a minimum, one for each application—and configure each app profile with the right settings for that application. This setup makes it possible to change the settings for one application but not others.

You might also have a single application that performs multiple functions, such as viewing current data and querying historic data. To handle these different functions, you should create an app profile for each function, so you can configure each function differently and update the settings for one function but not others.

Every instance has a default app profile, and you can create custom app profiles for each instance as well. The sections below describe default and custom app profiles.

You use an app profile by specifying that profile in your code when you connect to your instance. If you do not specify an app profile, Bigtable uses the instance's default app profile.

Default app profile

When you create an instance, Bigtable automatically creates a default app profile for the instance. If your application does not specify an app profile, or if you use the HBase shell to connect to your instance, Bigtable uses the settings in the default app profile. You can view and change these settings at any time.

The settings in an instance's default app profile depend on the number of clusters the instance had when you first created it:

If you created the instance with 1 cluster, the default app profile uses single-cluster routing, and it enables single-row transactions. This ensures that adding additional clusters later doesn't change the behavior of your existing applications.
If you created the instance with 2 or more clusters, the default app profile uses multi-cluster routing. Single-row transactions are never allowed with multi-cluster routing.

The default app profile does not change when you add or remove clusters. You must manually update the default app profile to change its settings. However, as a best practice you should create and use a new app profile instead of changing the default app profile.

Custom app profiles

A custom app profile is an app profile that you create and configure. An instance can have up to 2,000 app profiles.