yarn add bigtable-client


This is a TypeScript Bigtable client, it acts as wrapper around the official Google package @google-cloud/bigtable. When working with Bigtable we almost always had the urge to wrap the API to add a pinch of convenience to it, as well implement a way to get TTL (per cell basis), as well as metadata information such as a simple count more efficiently.

This client automatically manages a metadata table and ttl jobs for every table that you manage through it. Additionally it aims to mimic a simple CRUD interface, that is offered by a lot of redis packages like ioredis for example.

Additionally the setup and all operation (except for scan) are optimized for sub-millisecond response times (depending on your Google Cloud Bigtable Instance configuration), which helps you to develop real-time applications based on this Bigtable. This client is not ment to be used for analytical purposes, although it is fairly possible through scan operations.

Before you get started

Make sure to follow the setup described here. You will need a Google Cloud Project with enabled billing, as well as a setup authentication flow for this client to work.


Using it is fairly simple:

First, you have to setup a factory instance, which gets the general configuration to connect to your Bigtable instance. NOTE: If the instance you describe does not exist, it will be created.

const {BigtableFactory} = require("bigtable-client");
const bigtableFactory = new BigtableFactory({

  projectId: "my-project-1", // -> see @google-cloud/bigtable configuration
  instanceName: "my-bigtable-cluster", // -> see @google-cloud/bigtable configuration
  //keyFilename: "keyfile.json", // -> see @google-cloud/bigtable configuration

  // optional:
  ttlScanIntervalMs: 5000,
  minJitterMs: 2000,
  maxJitterMs: 30000,
await bigtableFactory.init();

Then, using the factory you can create handles for you tables very easily. You can see that we are taking away the complexity of handling columnFamilies and columns in general, by assuming default values in the API that can be set via config optionally. However the API always allows you to access cells (by passing a column name as parameter) directly, as well as accessing and deleting whole rows. Please bear in mind that the number is TTL in seconds, and will be deleted on the next job run.

const myTable = await bigtableFactory.get({
  name: "mytable",

  // optional:
  columnFamily: "myfamily",
  defaultColumn: "default",
  maxVersions: 1,

const rowKey = "myrowkey";
const value = "myvalue";

await myTable.set(rowKey, value);
await myTable.set(rowKey, value, 10, "newColumn");

await myTable.ttl(rowKey);

await myTable.multiSet(rowKey, {testColumn: "hello", anotherColumn: "yes"}, 5);

await myTable.increase(rowKey);
await myTable.decrease(rowKey);

await myTable.bulkInsert([
    row: "jean-paul",
    column: "sartre",
    data: "france",
    row: "emmanuel",
    column: "kant",
    data: "germany",
    row: "baruch",
    column: "spinoza",
    data: "netherland",
], 5);

await myTable.multiAdd(rowKey, {foo: 1, bar: -5}, 7);
await myTable.get(rowKey);

await myTable.ttl(rowKey);
await myTable.count();

await myTable.getRow(rowKey)
await myTable.deleteRow(rowKey);

myTable.close(); // or bigtableFactory.close();

You can also scan tables (be carefull as these operations are slow).

const filters = [
        // -> check out the official api for bigtable filters:

const etl = (row) => {
    return || null;

const cells = await myTable.scanCells(filters, etl);

You can activate debug logs via env variable DEBUG=yildiz:bigtable:*.

You can find additional implementation examples here:


License is MIT


This project is not associated with Google.


TypeScript Bigtable Client with :battery::battery: included.

Bigtable Info

⭐ Stars 13
🔗 Source Code
🕒 Last Update 2 years ago
🕒 Created 3 years ago
🐞 Open Issues 9
➗ Star-Issue Ratio 1
😎 Author yildizdb