REST Resource: projects.instances.tables

Resource: Table

A collection of user data indexed by row, column, and timestamp. Each table is served using the resources of its parent cluster.

JSON representation 
{
  "name": string,
  "clusterStates": {
    string: {
      object (ClusterState)
    },
    ...
  },
  "columnFamilies": {
    string: {
      object (ColumnFamily)
    },
    ...
  },
  "granularity": enum (TimestampGranularity),
  "restoreInfo": {
    object (RestoreInfo)
  },
  "changeStreamConfig": {
    object (ChangeStreamConfig)
  },
  "deletionProtection": boolean,
  "stats": {
    object (TableStats)
  },

  // Union field automated_backup_config can be only one of the following:
  "automatedBackupPolicy": {
    object (AutomatedBackupPolicy)
  }
  // End of list of possible types for union field automated_backup_config.
}
Fields
name

string

The unique name of the table. Values are of the form projects/{project}/instances/{instance}/tables/[_a-zA-Z0-9][-_.a-zA-Z0-9]*. Views: NAME_ONLY, SCHEMA_VIEW, REPLICATION_VIEW, STATS_VIEW, FULL
clusterStates

map (key: string, value: object (ClusterState))

Output only. Map from cluster ID to per-cluster table state. If it could not be determined whether or not the table has data in a particular cluster (for example, if its zone is unavailable), then there will be an entry for the cluster with UNKNOWN replication_status. Views: REPLICATION_VIEW, ENCRYPTION_VIEW, FULL

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
columnFamilies

map (key: string, value: object (ColumnFamily))

The column families configured for this table, mapped by column family ID. Views: SCHEMA_VIEW, STATS_VIEW, FULL

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
granularity

enum (TimestampGranularity)

Immutable. The granularity (i.e. MILLIS) at which timestamps are stored in this table. Timestamps not matching the granularity will be rejected. If unspecified at creation time, the value will be set to MILLIS. Views: SCHEMA_VIEW, FULL.
restoreInfo

object (RestoreInfo)

Output only. If this table was restored from another data source (e.g. a backup), this field will be populated with information about the restore.
changeStreamConfig

object (ChangeStreamConfig)

If specified, enable the change stream on this table. Otherwise, the change stream is disabled and the change stream is not retained.
deletionProtection

boolean

Set to true to make the table protected against data loss. i.e. deleting the following resources through Admin APIs are prohibited:

  • The table.
  • The column families in the table.
  • The instance containing the table.

Note one can still delete the data stored in the table through Data APIs.
stats

object (TableStats)

Output only. Only available with STATS_VIEW, this includes summary statistics about the entire table contents. For statistics about a specific column family, see ColumnFamilyStats in the mapped ColumnFamily collection above.

Union field automated_backup_config.

automated_backup_config can be only one of the following:
automatedBackupPolicy

object (AutomatedBackupPolicy)

If specified, automated backups are enabled for this table. Otherwise, automated backups are disabled.

ClusterState

The state of a table's data in a particular cluster.

JSON representation 
{
  "replicationState": enum (ReplicationState),
  "encryptionInfo": [
    {
      object (EncryptionInfo)
    }
  ]
}
Fields
replicationState

enum (ReplicationState)

Output only. The state of replication for the table in this cluster.
encryptionInfo[]

object (EncryptionInfo)

Output only. The encryption information for the table in this cluster. If the encryption key protecting this resource is customer managed, then its version can be rotated in Cloud Key Management Service (Cloud KMS). The primary version of the key and its status will be reflected here when changes propagate from Cloud KMS.

ReplicationState

Table replication states.

Enums
STATE_NOT_KNOWN The replication state of the table is unknown in this cluster.
INITIALIZING The cluster was recently created, and the table must finish copying over pre-existing data from other clusters before it can begin receiving live replication updates and serving Data API requests.
PLANNED_MAINTENANCE The table is temporarily unable to serve Data API requests from this cluster due to planned internal maintenance.
UNPLANNED_MAINTENANCE The table is temporarily unable to serve Data API requests from this cluster due to unplanned or emergency maintenance.
READY The table can serve Data API requests from this cluster. Depending on replication delay, reads may not immediately reflect the state of the table in other clusters.
READY_OPTIMIZING The table is fully created and ready for use after a restore, and is being optimized for performance. When optimizations are complete, the table will transition to READY state.

ColumnFamily

A set of columns within a table which share a common configuration.

JSON representation 
{
  "gcRule": {
    object (GcRule)
  },
  "stats": {
    object (ColumnFamilyStats)
  },
  "valueType": {
    object (Type)
  }
}
Fields
gcRule

object (GcRule)

Garbage collection rule specified as a protobuf. Must serialize to at most 500 bytes.

NOTE: Garbage collection executes opportunistically in the background, and so it's possible for reads to return a cell even if it matches the active GC expression for its family.
stats

object (ColumnFamilyStats)

Output only. Only available with STATS_VIEW, this includes summary statistics about column family contents. For statistics over an entire table, see TableStats above.
valueType

object (Type)

The type of data stored in each of this family's cell values, including its full encoding. If omitted, the family only serves raw untyped bytes.

For now, only the Aggregate type is supported.

Aggregate can only be set at family creation and is immutable afterwards.

If valueType is Aggregate, written data must be compatible with: * valueType.input_type for AddInput mutations

GcRule

Rule for determining which cells to delete during garbage collection.

JSON representation 
{

  // Union field rule can be only one of the following:
  "maxNumVersions": integer,
  "maxAge": string,
  "intersection": {
    object (Intersection)
  },
  "union": {
    object (Union)
  }
  // End of list of possible types for union field rule.
}
Fields
Union field rule. Garbage collection rules. rule can be only one of the following:
maxNumVersions

integer

Delete all cells in a column except the most recent N.
maxAge

string (Duration format)

Delete cells in a column older than the given age. Values must be at least one millisecond, and will be truncated to microsecond granularity.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
intersection

object (Intersection)

Delete cells that would be deleted by every nested rule.
union

object (Union)

Delete cells that would be deleted by any nested rule.

Intersection

A GcRule which deletes cells matching all of the given rules.

JSON representation 
{
  "rules": [
    {
      object (GcRule)
    }
  ]
}
Fields
rules[]

object (GcRule)

Only delete cells which would be deleted by every element of rules.

Union

A GcRule which deletes cells matching any of the given rules.

JSON representation 
{
  "rules": [
    {
      object (GcRule)
    }
  ]
}
Fields
rules[]

object (GcRule)

Delete cells which would be deleted by any element of rules.

ColumnFamilyStats

Approximate statistics related to a single column family within a table. This information may change rapidly, interpreting these values at a point in time may already preset out-of-date information.

Everything below is approximate, unless otherwise specified.

JSON representation 
{
  "averageColumnsPerRow": number,
  "averageCellsPerColumn": number,
  "logicalDataBytes": string
}
Fields
averageColumnsPerRow

number

How many column qualifiers are present in this column family, averaged over all rows in the table.

e.g. For column family "family" in a table with 3 rows:

  • A row with cells in "family:col" and "other:col" (1 column in "family")
  • A row with cells in "family:col", "family:other_col", and "other:data" (2 columns in "family")
  • A row with cells in "other:col" (0 columns in "family", "family" not present)

would report (1 + 2 + 0)/3 = 1.5 in this field.
averageCellsPerColumn

number

How many cells are present per column qualifier in this column family, averaged over all rows containing any column in the column family.

e.g. For column family "family" in a table with 3 rows:

  • A row with 3 cells in "family:col" and 1 cell in "other:col" (3 cells / 1 column in "family")
  • A row with 1 cell in "family:col", 7 cells in "family:other_col", and 7 cells in "other:data" (8 cells / 2 columns in "family")
  • A row with 3 cells in "other:col" (0 columns in "family", "family" not present)

would report (3 + 8 + 0)/(1 + 2 + 0) = 3.66 in this field.
logicalDataBytes

string (int64 format)

How much space the data in the column family occupies. This is roughly how many bytes would be needed to read the contents of the entire column family (e.g. by streaming all contents out).

Type

Type represents the type of data that is written to, read from, or stored in Bigtable. It is heavily based on the GoogleSQL standard to help maintain familiarity and consistency across products and features.

For compatibility with Bigtable's existing untyped APIs, each Type includes an Encoding which describes how to convert to/from the underlying data.

Each encoding also defines the following properties:

  • Order-preserving: Does the encoded value sort consistently with the original typed value? Note that Bigtable will always sort data based on the raw encoded value, not the decoded type.
    • Example: BYTES values sort in the same order as their raw encodings.
    • Counterexample: Encoding INT64 as a fixed-width decimal string does not preserve sort order when dealing with negative numbers. INT64(1) > INT64(-1), but STRING("-00001") > STRING("00001).
  • Self-delimiting: If we concatenate two encoded values, can we always tell where the first one ends and the second one begins?
    • Example: If we encode INT64s to fixed-width STRINGs, the first value will always contain exactly N digits, possibly preceded by a sign.
    • Counterexample: If we concatenate two UTF-8 encoded STRINGs, we have no way to tell where the first one ends.
  • Compatibility: Which other systems have matching encoding schemes? For example, does this encoding have a GoogleSQL equivalent? HBase? Java?
JSON representation 
{

  // Union field kind can be only one of the following:
  "bytesType": {
    object (Bytes)
  },
  "stringType": {
    object (String)
  },
  "int64Type": {
    object (Int64)
  },
  "float32Type": {
    object (Float32)
  },
  "float64Type": {
    object (Float64)
  },
  "boolType": {
    object (Bool)
  },
  "timestampType": {
    object (Timestamp)
  },
  "dateType": {
    object (Date)
  },
  "aggregateType": {
    object (Aggregate)
  },
  "structType": {
    object (Struct)
  },
  "arrayType": {
    object (Array)
  },
  "mapType": {
    object (Map)
  }
  // End of list of possible types for union field kind.
}
Fields
Union field kind. The kind of type that this represents. kind can be only one of the following:
bytesType

object (Bytes)

Bytes
stringType

object (String)

String
int64Type

object (Int64)

Int64
float32Type

object (Float32)

Float32
float64Type

object (Float64)

Float64
boolType

object (Bool)

Bool
timestampType

object (Timestamp)

Timestamp
dateType

object (Date)

Date
aggregateType

object (Aggregate)

Aggregate
structType

object (Struct)

Struct
arrayType

object (Array)

Array
mapType

object (Map)

Map

Bytes

Bytes Values of type Bytes are stored in Value.bytes_value.

JSON representation 
{
  "encoding": {
    object (Encoding)
  }
}
Fields
encoding

object (Encoding)

The encoding to use when converting to/from lower level types.

Encoding

Rules used to convert to/from lower level types.

JSON representation 
{

  // Union field encoding can be only one of the following:
  "raw": {
    object (Raw)
  }
  // End of list of possible types for union field encoding.
}
Fields
Union field encoding. Which encoding to use. encoding can be only one of the following:
raw

object (Raw)

Use Raw encoding.

Raw

This type has no fields.

Leaves the value "as-is" * Order-preserving? Yes * Self-delimiting? No * Compatibility? N/A

String

String Values of type String are stored in Value.string_value.

JSON representation 
{
  "encoding": {
    object (Encoding)
  }
}
Fields
encoding

object (Encoding)

The encoding to use when converting to/from lower level types.

Encoding

Rules used to convert to/from lower level types.

JSON representation 
{

  // Union field encoding can be only one of the following:
  "utf8Raw": {
    object (Utf8Raw)
  },
  "utf8Bytes": {
    object (Utf8Bytes)
  }
  // End of list of possible types for union field encoding.
}
Fields
Union field encoding. Which encoding to use. encoding can be only one of the following:
utf8Raw

object (Utf8Raw)

Deprecated: if set, converts to an empty utf8Bytes.
utf8Bytes

object (Utf8Bytes)

Use Utf8Bytes encoding.

Utf8Raw

This type has no fields.

Deprecated: prefer the equivalent Utf8Bytes.

Utf8Bytes

This type has no fields.

UTF-8 encoding * Order-preserving? Yes (code point order) * Self-delimiting? No * Compatibility? - BigQuery Federation TEXT encoding - HBase Bytes.toBytes - Java String#getBytes(StandardCharsets.UTF_8)

Int64

Int64 Values of type Int64 are stored in Value.int_value.

JSON representation 
{
  "encoding": {
    object (Encoding)
  }
}
Fields
encoding

object (Encoding)

The encoding to use when converting to/from lower level types.

Encoding

Rules used to convert to/from lower level types.

JSON representation 
{

  // Union field encoding can be only one of the following:
  "bigEndianBytes": {
    object (BigEndianBytes)
  }
  // End of list of possible types for union field encoding.
}
Fields
Union field encoding. Which encoding to use. encoding can be only one of the following:
bigEndianBytes

object (BigEndianBytes)

Use BigEndianBytes encoding.

BigEndianBytes

Encodes the value as an 8-byte big endian twos complement Bytes value. * Order-preserving? No (positive values only) * Self-delimiting? Yes * Compatibility? - BigQuery Federation BINARY encoding - HBase Bytes.toBytes - Java ByteBuffer.putLong() with ByteOrder.BIG_ENDIAN

JSON representation 
{
  "bytesType": {
    object (Bytes)
  }
}
Fields
bytesType

object (Bytes)

Deprecated: ignored if set.

Float32

This type has no fields.

Float32 Values of type Float32 are stored in Value.float_value.

Float64

This type has no fields.

Float64 Values of type Float64 are stored in Value.float_value.

Bool

This type has no fields.

bool Values of type Bool are stored in Value.bool_value.

Timestamp

This type has no fields.

Timestamp Values of type Timestamp are stored in Value.timestamp_value.

Date

This type has no fields.

Date Values of type Date are stored in Value.date_value.

Aggregate

A value that combines incremental updates into a summarized value.

Data is never directly written or read using type Aggregate. Writes will provide either the inputType or stateType, and reads will always return the stateType .

JSON representation 
{
  "inputType": {
    object (Type)
  },
  "stateType": {
    object (Type)
  },

  // Union field aggregator can be only one of the following:
  "sum": {
    object (Sum)
  },
  "hllppUniqueCount": {
    object (HyperLogLogPlusPlusUniqueCount)
  },
  "max": {
    object (Max)
  },
  "min": {
    object (Min)
  }
  // End of list of possible types for union field aggregator.
}
Fields
inputType

object (Type)

Type of the inputs that are accumulated by this Aggregate, which must specify a full encoding. Use AddInput mutations to accumulate new inputs.
stateType

object (Type)

Output only. Type that holds the internal accumulator state for the Aggregate. This is a function of the inputType and aggregator chosen, and will always specify a full encoding.
Union field aggregator. Which aggregator function to use. The configured types must match. aggregator can be only one of the following:
sum

object (Sum)

Sum aggregator.
hllppUniqueCount

object (HyperLogLogPlusPlusUniqueCount)

HyperLogLogPlusPlusUniqueCount aggregator.
max

object (Max)

Max aggregator.
min

object (Min)

Min aggregator.

Sum

This type has no fields.

Computes the sum of the input values. Allowed input: Int64 State: same as input

HyperLogLogPlusPlusUniqueCount

This type has no fields.

Computes an approximate unique count over the input values. When using raw data as input, be careful to use a consistent encoding. Otherwise the same value encoded differently could count more than once, or two distinct values could count as identical. Input: Any, or omit for Raw State: TBD Special state conversions: Int64 (the unique count estimate)

Max

This type has no fields.

Computes the max of the input values. Allowed input: Int64 State: same as input

Min

This type has no fields.

Computes the min of the input values. Allowed input: Int64 State: same as input

Struct

A structured data value, consisting of fields which map to dynamically typed values. Values of type Struct are stored in Value.array_value where entries are in the same order and number as field_types.

JSON representation 
{
  "fields": [
    {
      object (Field)
    }
  ]
}
Fields
fields[]

object (Field)

The names and types of the fields in this struct.

Field

A struct field and its type.

JSON representation 
{
  "fieldName": string,
  "type": {
    object (Type)
  }
}
Fields
fieldName

string

The field name (optional). Fields without a fieldName are considered anonymous and cannot be referenced by name.
type

object (Type)

The type of values in this field.

Array

An ordered list of elements of a given type. Values of type Array are stored in Value.array_value.

JSON representation 
{
  "elementType": {
    object (Type)
  }
}
Fields
elementType

object (Type)

The type of the elements in the array. This must not be Array.

Map

A mapping of keys to values of a given type. Values of type Map are stored in a Value.array_value where each entry is another Value.array_value with two elements (the key and the value, in that order). Normally encoded Map values won't have repeated keys, however, clients are expected to handle the case in which they do. If the same key appears multiple times, the last value takes precedence.

JSON representation 
{
  "keyType": {
    object (Type)
  },
  "valueType": {
    object (Type)
  }
}
Fields
keyType

object (Type)

The type of a map key. Only Bytes, String, and Int64 are allowed as key types.
valueType

object (Type)

The type of the values in a map.

TimestampGranularity

Possible timestamp granularities to use when keeping multiple versions of data in a table.

Enums
TIMESTAMP_GRANULARITY_UNSPECIFIED The user did not specify a granularity. Should not be returned. When specified during table creation, MILLIS will be used.
MILLIS The table keeps data versioned at a granularity of 1ms.

RestoreInfo

Information about a table restore.

JSON representation 
{
  "sourceType": enum (RestoreSourceType),

  // Union field source_info can be only one of the following:
  "backupInfo": {
    object (BackupInfo)
  }
  // End of list of possible types for union field source_info.
}
Fields
sourceType

enum (RestoreSourceType)

The type of the restore source.
Union field source_info. Information about the source used to restore the table. source_info can be only one of the following:
backupInfo

object (BackupInfo)

Information about the backup used to restore the table. The backup may no longer exist.

RestoreSourceType

Indicates the type of the restore source.

Enums
RESTORE_SOURCE_TYPE_UNSPECIFIED No restore associated.
BACKUP A backup was used as the source of the restore.

BackupInfo

Information about a backup.

JSON representation 
{
  "backup": string,
  "startTime": string,
  "endTime": string,
  "sourceTable": string,
  "sourceBackup": string
}
Fields
backup

string

Output only. Name of the backup.
startTime

string (Timestamp format)

Output only. The time that the backup was started. row data in the backup will be no older than this timestamp.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
endTime

string (Timestamp format)

Output only. This time that the backup was finished. row data in the backup will be no newer than this timestamp.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
sourceTable

string

Output only. Name of the table the backup was created from.
sourceBackup

string

Output only. Name of the backup from which this backup was copied. If a backup is not created by copying a backup, this field will be empty. Values are of the form: projects//instances//clusters//backups/

ChangeStreamConfig

Change stream configuration.

JSON representation 
{
  "retentionPeriod": string
}
Fields
retentionPeriod

string (Duration format)

How long the change stream should be retained. Change stream data older than the retention period will not be returned when reading the change stream from the table. Values must be at least 1 day and at most 7 days, and will be truncated to microsecond granularity.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

TableStats

Approximate statistics related to a table.

These statistics are calculated infrequently, while simultaneously, data in the table can change rapidly. Thus the values reported here (e.g. row count) are very likely out-of date, even the instant they are received in this API. Thus, only treat these values as approximate.

IMPORTANT: Everything below is approximate, unless otherwise specified.

JSON representation 
{
  "rowCount": string,
  "averageColumnsPerRow": number,
  "averageCellsPerColumn": number,
  "logicalDataBytes": string
}
Fields
rowCount

string (int64 format)

How many rows are in the table.
averageColumnsPerRow

number

How many (column family, column qualifier) combinations are present per row in the table, averaged over all rows in the table.

e.g. A table with 2 rows:

  • A row with cells in "family:col" and "other:col" (2 distinct columns)
  • A row with cells in "family:col", "family:other_col", and "other:data" (3 distinct columns)

would report (2 + 3)/2 = 2.5 in this field.
averageCellsPerColumn

number

How many cells are present per column (column family, column qualifier) combinations, averaged over all columns in all rows in the table.

e.g. A table with 2 rows:

  • A row with 3 cells in "family:col" and 1 cell in "other:col" (4 cells / 2 columns)
  • A row with 1 cell in "family:col", 7 cells in "family:other_col", and 7 cells in "other:data" (15 cells / 3 columns)

would report (4 + 15)/(2 + 3) = 3.8 in this field.
logicalDataBytes

string (int64 format)

This is roughly how many bytes would be needed to read the entire table (e.g. by streaming all contents out).

AutomatedBackupPolicy

Defines an automated backup policy for a table

JSON representation 
{
  "retentionPeriod": string,
  "frequency": string
}
Fields
retentionPeriod

string (Duration format)

Required. How long the automated backups should be retained. The only supported value at this time is 3 days.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
frequency

string (Duration format)

Required. How frequently automated backups should occur. The only supported value at this time is 24 hours.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

Methods

checkConsistency

 Checks replication consistency based on a consistency token, that is, if replication has caught up based on the conditions specified in the token and the check request.

create

 Creates a new table in the specified instance.

delete

 Permanently deletes a specified table and all of its data.

dropRowRange

 Permanently drop/delete a row range from a specified table.

generateConsistencyToken

 Generates a consistency token for a Table, which can be used in CheckConsistency to check whether mutations to the table that finished before this call started have been replicated.

get

 Gets metadata information about the specified table.

getIamPolicy

 Gets the access control policy for a Bigtable resource.

list

 Lists all tables served from a specified instance.

modifyColumnFamilies

 Performs a series of column family modifications on the specified table.

patch

 Updates a specified table.

restore

 Create a new table by restoring from a completed backup.

setIamPolicy

 Sets the access control policy on a Bigtable resource.

testIamPermissions

 Returns permissions that the caller has on the specified Bigtable resource.

undelete

 Restores a specified table which was accidentally deleted.