Create and manage authorized views

This document describes how to define, create, and perform other administrative operations on an authorized view using the Google Cloud CLI. Before you read this document, you should be familiar with the Overview of authorized views.

Required roles

To get the permissions that you need to perform administrative operations on an authorized view , ask your administrator to grant you the Bigtable Admin (roles/bigtable.admin) IAM role on the underlying table . For more information about granting roles, see Manage access.

This predefined role contains the permissions required to perform administrative operations on an authorized view . To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to perform administrative operations on an authorized view :

  • bigtable.authorizedViews.get
  • bigtable.authorizedViews.list
  • bigtable.authorizedViews.create
  • bigtable.authorizedViews.update
  • bigtable.authorizedViews.delete
  • bigtable.authorizedViews.getIamPolicy
  • bigtable.authorizedViews.setIamPolicy
  • bigtable.authorizedViews.readRows
  • bigtable.authorizedViews.sampleRowKeys
  • bigtable.authorizedViews.mutateRows

You might also be able to get these permissions with custom roles or other predefined roles.

To learn how to manage Bigtable IAM roles at the authorized-view level, see authorized view-level IAM management.

Create an authorized view

When you create an authorized view, consider the queries that will be run against it. Read, write, and delete requests that are sent to an authorized view must reference only data that is in the authorized view. This means, for example, that if you attempt to read, write to, or delete a row that has columns in the table that are not in your authorized view, the request fails.

To avoid a situation where data requests to an authorized view fail because columns have been added to the table that aren't in the authorized view, you can specify an empty column qualifier prefix "" for a column family.

You can specify up to 100 definition parameters per authorized view.

gcloud

Run the bigtable authorized-views create command.

gcloud bigtable authorized-views create AUTHORIZED_VIEW_ID \
  --instance=INSTANCE_ID \
  --table=TABLE_ID \
  --definition-file=DEFINITION_FILE_PATH

Replace the following:

  • AUTHORIZED_VIEW_ID: a permanent identifier for the authorized view that is not already in use for the table
  • INSTANCE_ID: the permanent identifier for the instance that contains the table
  • TABLE_ID: the permanent identifier of that table you are creating an authorized view of
  • DEFINITION_FILE_PATH: the path to a valid JSON formatted representation of an authorized view. For examples of correctly formatted definition files, see Definition file examples.

You can also run the command without supplying the definition file. In this case, the gcloud CLI opens an editor and prompts you for values.

To confirm that the authorized view has been created, get a list of authorized views for the table.

Java

To learn how to install and use the client library for Bigtable, see Bigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for client libraries. 

try {
  CreateAuthorizedViewRequest request =
      CreateAuthorizedViewRequest.of(tableId, authorizedViewId)
          .setAuthorizedViewType(
              SubsetView.create()
                  .addRowPrefix("")
                  .setFamilySubsets(
                      COLUMN_FAMILY,
                      FamilySubsets.create().addQualifierPrefix(COLUMN_QUALIFIER_NAME)));
  AuthorizedView authorizedView = adminClient.createAuthorizedView(request);
  System.out.printf("AuthorizedView: %s created successfully%n", authorizedView.getId());
} catch (NotFoundException e) {
  System.err.println(
      "Failed to create an authorized view from a non-existent table: " + e.getMessage());
}

Modify an authorized view

gcloud

Modify an authorized view using the bigtable authorized-views update command.

gcloud bigtable authorized-views update AUTHORIZED_VIEW_ID \
  --instance=INSTANCE_ID \
  --table=TABLE_ID \
  --definition-file=DEFINITION_FILE_PATH

Replace the following:

  • AUTHORIZED_VIEW_ID: the permanent identifier for the authorized view
  • INSTANCE_ID: the permanent identifier for the instance
  • TABLE_ID: the permanent identifier of the source table
  • DEFINITION_FILE_PATH: the path to a valid JSON formatted representation of an authorized view. For examples of correctly formatted definition files, see Definition file examples.

You can also run the command without supplying the definition file. In this case, the gcloud CLI opens an editor and prompts you for values.

Optional: To prevent the gcloud CLI from displaying a confirmation prompt showing the difference between the current authorized view structure and after the update is committed, append the --no-interactive flag to the command.

Java

To learn how to install and use the client library for Bigtable, see Bigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for client libraries. 

try {
  // Update to an authorized view permitting everything.
  UpdateAuthorizedViewRequest request =
      UpdateAuthorizedViewRequest.of(tableId, authorizedViewId)
          .setAuthorizedViewType(
              SubsetView.create()
                  .addRowPrefix("")
                  .setFamilySubsets(
                      COLUMN_FAMILY, FamilySubsets.create().addQualifierPrefix("")));
  AuthorizedView authorizedView = adminClient.updateAuthorizedView(request);
  System.out.printf("AuthorizedView: %s updated successfully%n", authorizedView.getId());
} catch (NotFoundException e) {
  System.err.println("Failed to modify a non-existent authorized view: " + e.getMessage());
}

Enable or disable deletion protection

To enable deletion protection for an authorized view, add --deletion-protection to the update command.

To disable deletion protection, add no-deletion-protection to the update command.

Delete an authorized view

If you delete a table, all authorized views of the table are also deleted.

If you delete an authorized view, you can't undelete it. However, if you delete a table and then undelete the table, all authorized views of the table are restored along with the table. Then you must reconfigure IAM for the authorized views as well as for the tables. For details, see Undelete a table.

gcloud

Delete an authorized view using the bigtable instances tables authorized-views delete command.

gcloud bigtable authorized-views delete AUTHORIZED_VIEW_ID \
  --instance=INSTANCE_ID \
  --table=TABLE_ID

Replace the following:

  • AUTHORIZED_VIEW_ID: the permanent identifier for the authorized view
  • INSTANCE_ID: the permanent identifier for the instance
  • TABLE_ID: the permanent identifier of the source table

Optional: To prevent the gcloud CLI from displaying a confirmation prompt requiring you to confirm or cancel the deletion, append the --nointeractive flag to the command.

Java

To learn how to install and use the client library for Bigtable, see Bigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for client libraries. 

try {
  adminClient.deleteAuthorizedView(tableId, authorizedViewId);
  System.out.printf("AuthorizedView: %s deleted successfully%n", authorizedViewId);
} catch (NotFoundException e) {
  System.err.println("Failed to delete a non-existent authorized view: " + e.getMessage());
}

Get a list of authorized views for a table

gcloud

Run the bigtable authorized-views list command:

gcloud bigtable authorized-views list \
  --instance=INSTANCE_ID \
  --table=TABLE_ID

Replace the following:

  • INSTANCE_ID: the permanent identifier for the instance
  • TABLE_ID: the permanent identifier for the table

Java

To learn how to install and use the client library for Bigtable, see Bigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for client libraries. 

List<String> authorizedViewIds = new ArrayList<>();
try {
  authorizedViewIds = adminClient.listAuthorizedViews(tableId);
  for (String authorizedViewId : authorizedViewIds) {
    System.out.println(authorizedViewId);
  }
} catch (NotFoundException e) {
  System.err.println(
      "Failed to list authorized views from a non-existent table: " + e.getMessage());
}

View details about an authorized view

gcloud

To get details about an authorized view, run the bigtable instances tables authorized-views describe command:

gcloud bigtable authorized-views describe \
–-instance=INSTANCE_ID \
–-table=TABLE_ID \
–-view=AUTHORIZED_VIEW_ID

Replace the following:

  • INSTANCE_ID: the permanent identifier for the instance
  • TABLE_ID: the permanent identifier for the table
  • AUTHORIZED_VIEW_ID: the permanent identifier for the authorized view

Java

To learn how to install and use the client library for Bigtable, see Bigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for client libraries. 

AuthorizedView authorizedView = null;
try {
  authorizedView = adminClient.getAuthorizedView(tableId, authorizedViewId);
  SubsetView subsetView = (SubsetView) authorizedView.getAuthorizedViewType();

  for (ByteString rowPrefix : subsetView.getRowPrefixes()) {
    System.out.printf("Row Prefix: %s%n", rowPrefix.toStringUtf8());
  }
  for (Map.Entry<String, FamilySubsets> entry : subsetView.getFamilySubsets().entrySet()) {
    for (ByteString qualifierPrefix : entry.getValue().getQualifierPrefixes()) {
      System.out.printf(
          "Column Family: %s, Qualifier Prefix: %s%n",
          entry.getKey(), qualifierPrefix.toStringUtf8());
    }
    for (ByteString qualifier : entry.getValue().getQualifiers()) {
      System.out.printf(
          "Column Family: %s, Qualifier: %s%n", entry.getKey(), qualifier.toStringUtf8());
    }
  }
} catch (NotFoundException e) {
  System.err.println(
      "Failed to retrieve metadata from a non-existent authorized view: " + e.getMessage());
}

What's next