Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

写入示例

本文档中的代码示例演示了在使用 Cloud Bigtable 客户端库时可以发送到 Bigtable 的各种类型的写入请求。

本页中的示例使用 SetCell 突变向非汇总单元格发送写入请求。如需查看如何发送 add 请求以聚合单元格的示例，请参阅在写入时聚合数据。

在试用这些示例之前，请确保您了解每种类型的写入请求的适用情形和不适用情形。

适用于 Bigtable 的 Python 客户端库提供两个 API：asyncio 和同步 API。如果您的应用是异步的，请使用 asyncio。

本页上的代码示例引用了示例数据中的示例表。

执行简单的写入

以下代码示例演示了如何向 Bigtable 发出简单的写入请求。这类写入会发出 MutateRow API 请求。

Go

如需了解如何安装和使用 Bigtable 的客户端库，请参阅 Bigtable 客户端库。

如需向 Bigtable 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

import (
	"context"
	"encoding/binary"
	"fmt"
	"io"

	"bytes"

	"cloud.google.com/go/bigtable"
)

func writeSimple(w io.Writer, projectID, instanceID string, tableName string) error {
	// projectID := "my-project-id"
	// instanceID := "my-instance-id"
	// tableName := "mobile-time-series"

	ctx := context.Background()
	client, err := bigtable.NewClient(ctx, projectID, instanceID)
	if err != nil {
		return fmt.Errorf("bigtable.NewClient: %w", err)
	}
	defer client.Close()
	tbl := client.Open(tableName)
	columnFamilyName := "stats_summary"
	timestamp := bigtable.Now()

	mut := bigtable.NewMutation()
	buf := new(bytes.Buffer)
	binary.Write(buf, binary.BigEndian, int64(1))

	mut.Set(columnFamilyName, "connected_cell", timestamp, buf.Bytes())
	mut.Set(columnFamilyName, "connected_wifi", timestamp, buf.Bytes())
	mut.Set(columnFamilyName, "os_build", timestamp, []byte("PQ2A.190405.003"))

	rowKey := "phone#4c410523#20190501"
	if err := tbl.Apply(ctx, rowKey, mut); err != nil {
		return fmt.Errorf("Apply: %w", err)
	}

	fmt.Fprintf(w, "Successfully wrote row: %s\n", rowKey)
	return nil
}

HBase

如需了解如何安装和使用 Bigtable 的客户端库，请参阅 Bigtable 客户端库。

如需向 Bigtable 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。


import com.google.cloud.bigtable.hbase.BigtableConfiguration;
import org.apache.hadoop.hbase.TableName;
import org.apache.hadoop.hbase.client.Connection;
import org.apache.hadoop.hbase.client.Put;
import org.apache.hadoop.hbase.client.Table;
import org.apache.hadoop.hbase.util.Bytes;

public class WriteSimple {

  private static final byte[] COLUMN_FAMILY_NAME = Bytes.toBytes("stats_summary");

  public static void writeSimple(String projectId, String instanceId, String tableId) {
    // String projectId = "my-project-id";
    // String instanceId = "my-instance-id";
    // String tableId = "mobile-time-series";

    try (Connection connection = BigtableConfiguration.connect(projectId, instanceId)) {
      final Table table = connection.getTable(TableName.valueOf(Bytes.toBytes(tableId)));
      long timestamp = System.currentTimeMillis();
      byte[] one = new byte[]{0, 0, 0, 0, 0, 0, 0, 1};

      String rowKey = "phone#4c410523#20190501";
      Put put = new Put(Bytes.toBytes(rowKey));

      put.addColumn(COLUMN_FAMILY_NAME, Bytes.toBytes("connected_cell"), timestamp, one);
      put.addColumn(COLUMN_FAMILY_NAME, Bytes.toBytes("connected_wifi"), timestamp, one);
      put.addColumn(
          COLUMN_FAMILY_NAME,
          Bytes.toBytes("os_build"),
          timestamp,
          Bytes.toBytes("PQ2A.190405.003"));
      table.put(put);

      System.out.printf("Successfully wrote row %s", rowKey);

    } catch (Exception e) {
      System.out.println("Error during WriteSimple: \n" + e.toString());
    }
  }
}

Java

如需了解如何安装和使用 Bigtable 的客户端库，请参阅 Bigtable 客户端库。

如需向 Bigtable 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。


import com.google.cloud.bigtable.data.v2.BigtableDataClient;
import com.google.cloud.bigtable.data.v2.models.RowMutation;
import com.google.cloud.bigtable.data.v2.models.TableId;
import com.google.protobuf.ByteString;

public class WriteSimple {
  private static final String COLUMN_FAMILY_NAME = "stats_summary";

  public static void writeSimple(String projectId, String instanceId, String tableId) {
    // String projectId = "my-project-id";
    // String instanceId = "my-instance-id";
    // String tableId = "mobile-time-series";

    try (BigtableDataClient dataClient = BigtableDataClient.create(projectId, instanceId)) {
      long timestamp = System.currentTimeMillis() * 1000;

      String rowkey = "phone#4c410523#20190501";

      RowMutation rowMutation =
          RowMutation.create(TableId.of(tableId), rowkey)
              .setCell(
                  COLUMN_FAMILY_NAME,
                  ByteString.copyFrom("connected_cell".getBytes()),
                  timestamp,
                  1)
              .setCell(
                  COLUMN_FAMILY_NAME,
                  ByteString.copyFrom("connected_wifi".getBytes()),
                  timestamp,
                  1)
              .setCell(COLUMN_FAMILY_NAME, "os_build", timestamp, "PQ2A.190405.003");

      dataClient.mutateRow(rowMutation);
      System.out.printf("Successfully wrote row %s", rowkey);

    } catch (Exception e) {
      System.out.println("Error during WriteSimple: \n" + e.toString());
    }
  }
}

Python asyncio

如需了解如何安装和使用 Bigtable 的客户端库，请参阅 Bigtable 客户端库。

如需向 Bigtable 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

from google.cloud.bigtable.data import BigtableDataClientAsync
from google.cloud.bigtable.data import SetCell

async def write_simple(project_id, instance_id, table_id):
    async with BigtableDataClientAsync(project=project_id) as client:
        async with client.get_table(instance_id, table_id) as table:
            family_id = "stats_summary"
            row_key = b"phone#4c410523#20190501"

            cell_mutation = SetCell(family_id, "connected_cell", 1)
            wifi_mutation = SetCell(family_id, "connected_wifi", 1)
            os_mutation = SetCell(family_id, "os_build", "PQ2A.190405.003")

            await table.mutate_row(row_key, cell_mutation)
            await table.mutate_row(row_key, wifi_mutation)
            await table.mutate_row(row_key, os_mutation)

Python

如需了解如何安装和使用 Bigtable 的客户端库，请参阅 Bigtable 客户端库。

如需向 Bigtable 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

from datetime import datetime, timezone

from google.cloud import bigtable


def write_simple(project_id, instance_id, table_id):
    client = bigtable.Client(project=project_id, admin=True)
    instance = client.instance(instance_id)
    table = instance.table(table_id)

    timestamp = datetime.now(timezone.utc)
    column_family_id = "stats_summary"

    row_key = "phone#4c410523#20190501"

    row = table.direct_row(row_key)
    row.set_cell(column_family_id, "connected_cell", 1, timestamp)
    row.set_cell(column_family_id, "connected_wifi", 1, timestamp)
    row.set_cell(column_family_id, "os_build", "PQ2A.190405.003", timestamp)

    row.commit()

    print("Successfully wrote row {}.".format(row_key))

C#

如需了解如何安装和使用 Bigtable 的客户端库，请参阅 Bigtable 客户端库。

如需向 Bigtable 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。


using System;
using Google.Cloud.Bigtable.V2;
using Google.Cloud.Bigtable.Common.V2;

namespace Writes
{
    public class WriteSimpleSample
    {
        /// <summary>
        /// Mutate one row in an existing table and column family. Updates multiple cells within that row using one API call.
        ///</summary>
        /// <param name="projectId">Your Google Cloud Project ID.</param>
        /// <param name="instanceId">Your Google Cloud Bigtable Instance ID.</param>
        /// <param name="tableId">Your Google Cloud Bigtable table ID.</param>
        public string WriteSimple(
            string projectId = "YOUR-PROJECT-ID",
            string instanceId = "YOUR-INSTANCE-ID",
            string tableId = "YOUR-TABLE-ID")
        {
            BigtableClient bigtableClient = BigtableClient.Create();

            TableName tableName = new TableName(projectId, instanceId, tableId);
            BigtableByteString rowkey = new BigtableByteString("phone#4c410523#20190501");
            BigtableVersion timestamp = new BigtableVersion(DateTime.UtcNow);
            string COLUMN_FAMILY = "stats_summary";

            Mutation[] mutations = {
                    Mutations.SetCell(COLUMN_FAMILY, "connected_cell", 1, timestamp),
                    Mutations.SetCell(COLUMN_FAMILY, "connected_wifi", 1, timestamp),
                    Mutations.SetCell(COLUMN_FAMILY, "os_build", "PQ2A.190405.003", timestamp)
                };
            MutateRowResponse mutateRowResponse = bigtableClient.MutateRow(tableName, rowkey, mutations);
            Console.WriteLine(mutateRowResponse);
            return $"Successfully wrote row {rowkey}";
        }
    }
}

C++

如需了解如何安装和使用 Bigtable 的客户端库，请参阅 Bigtable 客户端库。

如需向 Bigtable 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

namespace cbt = ::google::cloud::bigtable;
[](cbt::Table table) {
  auto timestamp = std::chrono::duration_cast<std::chrono::milliseconds>(
      std::chrono::system_clock::now().time_since_epoch());

  std::string row_key = "phone#4c410523#20190501";
  cbt::SingleRowMutation mutation(row_key);
  std::string column_family = "stats_summary";

  mutation.emplace_back(cbt::SetCell(column_family, "connected_cell",
                                     timestamp, std::int64_t{1}));
  mutation.emplace_back(cbt::SetCell(column_family, "connected_wifi",
                                     timestamp, std::int64_t{1}));
  mutation.emplace_back(
      cbt::SetCell(column_family, "os_build", timestamp, "PQ2A.190405.003"));
  google::cloud::Status status = table.Apply(std::move(mutation));
  if (!status.ok()) throw std::runtime_error(status.message());
  std::cout << "Successfully wrote row" << row_key << "\n";
}

Node.js

如需了解如何安装和使用 Bigtable 的客户端库，请参阅 Bigtable 客户端库。

如需向 Bigtable 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

const {Bigtable} = require('@google-cloud/bigtable');
const bigtable = new Bigtable();

async function writeSimple() {
  /**
   * TODO(developer): Uncomment these variables before running the sample.
   */
  // const instanceId = 'YOUR_INSTANCE_ID';
  // const tableId = 'YOUR_TABLE_ID';
  const instance = bigtable.instance(instanceId);
  const table = instance.table(tableId);

  const timestamp = new Date();
  const rowToInsert = {
    key: 'phone#4c410523#20190501',
    data: {
      stats_summary: {
        connected_cell: {
          value: 1,
          timestamp,
        },
        connected_wifi: {
          value: 1,
          timestamp,
        },
        os_build: {
          value: 'PQ2A.190405.003',
          timestamp,
        },
      },
    },
  };

  await table.insert(rowToInsert);

  console.log(`Successfully wrote row ${rowToInsert.key}`);
}

writeSimple();

PHP

如需了解如何安装和使用 Bigtable 的客户端库，请参阅 Bigtable 客户端库。

如需向 Bigtable 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

use Google\Cloud\Bigtable\BigtableClient;
use Google\Cloud\Bigtable\DataUtil;
use Google\Cloud\Bigtable\Mutations;

/**
 * Write data in a table
 *
 * @param string $projectId The Google Cloud project ID
 * @param string $instanceId The ID of the Bigtable instance
 * @param string $tableId The ID of the table where the data needs to be written
 */
function write_simple(
    string $projectId,
    string $instanceId,
    string $tableId = 'mobile-time-series'
): void {
    // Connect to an existing table with an existing instance.
    $dataClient = new BigtableClient([
        'projectId' => $projectId,
    ]);
    $table = $dataClient->table($instanceId, $tableId);

    $timestampMicros = time() * 1000 * 1000;
    $columnFamilyId = 'stats_summary';
    $mutations = (new Mutations())
    ->upsert($columnFamilyId, 'connected_cell', '1', $timestampMicros)
    ->upsert($columnFamilyId, 'connected_wifi', DataUtil::intToByteString(1), $timestampMicros)
    ->upsert($columnFamilyId, 'os_build', 'PQ2A.190405.003', $timestampMicros);

    $table->mutateRow('phone#4c410523#20190501', $mutations);

    printf('Successfully wrote row.' . PHP_EOL);
}

Ruby

如需了解如何安装和使用 Bigtable 的客户端库，请参阅 Bigtable 客户端库。

如需向 Bigtable 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

# instance_id = "my-instance"
# table_id    = "my-table"
table = bigtable.table instance_id, table_id
column_family = "stats_summary"
timestamp = (Time.now.to_f * 1_000_000).round(-3)

rowkey = "phone#4c410523#20190501"
entry = table.new_mutation_entry(rowkey)
             .set_cell(column_family, "connected_cell", 1, timestamp: timestamp)
             .set_cell(column_family, "connected_wifi", 1, timestamp: timestamp)
             .set_cell(column_family, "os_build", "PQ2A.190405.003", timestamp: timestamp)

table.mutate_row entry
puts "Successfully wrote row #{rowkey}"

递增值

以下代码示例演示了如何发送递增或递减汇总单元格中现有数值的写入请求。这类写入会发出 MutateRow 请求，并带有 AddToCell 突变类型。这些示例会向需要 Int64 输入类型的列族中的总和添加值。

cbt

cbt addtocell TABLE_ID ROW_KEY
FAMILY_NAME:COLUMN_QUALIFER=VALUE@TIMESTAMP

替换以下内容：

TABLE_ID：表的永久标识符
ROW_KEY：行键
FAMILY_NAME：汇总列族的名称
COLUMN_QUALIFIER：列的标识符
VALUE：要添加到单元格的值
TIMESTAMP：以微秒为单位的 Unix 时间戳，例如 1710868850000000

此示例会将 device-1 行中 week12 列内存储的值减去 100：

cbt addtocell mobile-data device-1 updates:week12=-100@1710868850000000

Go

如需了解如何安装和使用 Bigtable 的客户端库，请参阅 Bigtable 客户端库。

如需向 Bigtable 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/bigtable"
)

func writeAggregate(w io.Writer, projectID, instanceID string, tableName string) error {
	// projectID := "my-project-id"
	// instanceID := "my-instance-id"
	// tableName := "mobile-time-series"

	ctx := context.Background()
	client, err := bigtable.NewClient(ctx, projectID, instanceID)
	if err != nil {
		return fmt.Errorf("bigtable.NewClient: %w", err)
	}
	defer client.Close()
	tbl := client.Open(tableName)
	columnFamilyName := "view_count"
	viewTimestamp, err := time.Parse(time.RFC3339, "2024-03-13T12:41:34Z")
	if err != nil {
		return err
	}
	hourlyBucket := viewTimestamp.Truncate(time.Hour)

	mut := bigtable.NewMutation()
	mut.AddIntToCell(columnFamilyName, "views", bigtable.Time(hourlyBucket), 1)

	rowKey := "page#index.html"
	if err := tbl.Apply(ctx, rowKey, mut); err != nil {
		return fmt.Errorf("Apply: %w", err)
	}

	fmt.Fprintf(w, "Successfully wrote row: %s\n", rowKey)
	return nil
}

Java

如需了解如何安装和使用 Bigtable 的客户端库，请参阅 Bigtable 客户端库。

如需向 Bigtable 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。


import com.google.cloud.bigtable.data.v2.BigtableDataClient;
import com.google.cloud.bigtable.data.v2.models.RowMutation;
import com.google.common.primitives.Longs;
import com.google.protobuf.ByteString;
import java.time.Instant;
import java.time.temporal.ChronoUnit;

public class WriteAggregate {
  private static final String COUNT_COLUMN_FAMILY_NAME = "view_count";
  private static final long MICROS_PER_MILLI = 1000;

  public static void writeAggregate(String projectId, String instanceId, String tableId) {
    // String projectId = "my-project-id";
    // String instanceId = "my-instance-id";
    // String tableId = "page-view-counter";

    try (BigtableDataClient dataClient = BigtableDataClient.create(projectId, instanceId)) {

      String rowKey = "page#index.html";
      Instant viewTimestamp = Instant.parse("2024-03-13T12:41:34.123Z");

      // Bucket the views for an hour into a single count, giving us an hourly view count for a
      // given page.
      Instant hourlyBucket = viewTimestamp.truncatedTo(ChronoUnit.HOURS);
      long hourlyBucketMicros = hourlyBucket.toEpochMilli() * MICROS_PER_MILLI;

      RowMutation rowMutation =
          RowMutation.create(tableId, rowKey)
              .addToCell(COUNT_COLUMN_FAMILY_NAME, "views", hourlyBucketMicros, 1);

      dataClient.mutateRow(rowMutation);
      System.out.printf("Successfully wrote row %s", rowKey);

    } catch (Exception e) {
      System.out.println("Error during WriteAggregate: \n" + e.toString());
    }
  }

  public static void mergeAggregate(String projectId, String instanceId, String tableId) {
    // String projectId = "my-project-id";
    // String instanceId = "my-instance-id";
    // String tableId = "page-view-counter";

    try (BigtableDataClient dataClient = BigtableDataClient.create(projectId, instanceId)) {

      String rowKey = "page#index.html";
      Instant viewTimestamp = Instant.parse("2024-03-13T12:41:34.123Z");

      // Bucket the views for an hour into a single count, giving us an hourly view count for a
      // given page.
      Instant hourlyBucket = viewTimestamp.truncatedTo(ChronoUnit.HOURS);
      long hourlyBucketMicros = hourlyBucket.toEpochMilli() * MICROS_PER_MILLI;

      RowMutation rowMutation =
          RowMutation.create(tableId, rowKey)
              .mergeToCell(
                  COUNT_COLUMN_FAMILY_NAME,
                  "views",
                  hourlyBucketMicros,
                  ByteString.copyFrom(Longs.toByteArray(1L)));

      dataClient.mutateRow(rowMutation);
      System.out.printf("Successfully wrote row %s", rowKey);

    } catch (Exception e) {
      System.out.println("Error during mergeAggregate: \n" + e.toString());
    }
  }
}

Python asyncio

如需了解如何安装和使用 Bigtable 的客户端库，请参阅 Bigtable 客户端库。

如需向 Bigtable 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

import time
from google.cloud.bigtable.data import BigtableDataClientAsync
from google.cloud.bigtable.data.mutations import AddToCell, RowMutationEntry
from google.cloud.bigtable.data.exceptions import MutationsExceptionGroup

async def write_aggregate(project_id, instance_id, table_id):
    """Increments a value in a Bigtable table using AddToCell mutation."""
    async with BigtableDataClientAsync(project=project_id) as client:
        table = client.get_table(instance_id, table_id)
        row_key = "unique_device_ids_1"
        try:
            async with table.mutations_batcher() as batcher:
                # The AddToCell mutation increments the value of a cell.
                # The `counters` family must be set up to be an aggregate
                # family with an int64 input type.
                reading = AddToCell(
                    family="counters",
                    qualifier="odometer",
                    value=32304,
                    # Convert nanoseconds to microseconds
                    timestamp_micros=time.time_ns() // 1000,
                )
                await batcher.append(
                    RowMutationEntry(row_key.encode("utf-8"), [reading])
                )
        except MutationsExceptionGroup as e:
            # MutationsExceptionGroup contains a FailedMutationEntryError for
            # each mutation that failed.
            for sub_exception in e.exceptions:
                failed_entry: RowMutationEntry = sub_exception.entry
                cause: Exception = sub_exception.__cause__
                print(
                    f"Failed mutation for row {failed_entry.row_key!r} with error: {cause!r}"
                )

有条件地写入值

以下代码示例演示了如何发送条件写入请求，该请求检查某行是否符合条件，然后根据结果向该行写入数据。这类写入会发出 CheckAndMutateRow API 请求。

Go

如需了解如何安装和使用 Bigtable 的客户端库，请参阅 Bigtable 客户端库。

如需向 Bigtable 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

import (