row key 스키마 관리

구조화된 row key 를 사용하면 관계형 데이터베이스의 복합 키와 유사한 다중 파트 키를 사용하여 Bigtable 데이터에 액세스할 수 있습니다. 테이블에 구조화된 row key를 정의하면 Bigtable용 GoogleSQL 쿼리를 사용하여 row key의 특정 부분에 액세스할 수 있습니다.

row key 스키마를 만들면 row key의 각 세그먼트 데이터 유형과 인코딩 방식을 정의할 수 있습니다. Bigtable은 row key를 사전순으로 정렬된 바이트로 저장하며 row key 스키마는 Bigtable용 GoogleSQL에 이러한 바이트를 디코딩하고 해석하는 방법을 알려줍니다.

구조화된 row key를 사용하는지 여부에 관계없이 row key 설계에 권장사항이 적용됩니다. 자세한 내용은 Row keys를 참조하세요.

기기 유형, 국가, 제조업체 ID, 일련번호의 값 사이에 구분 기호가 있는 다음 샘플 row key를 고려하세요.

`phone#india#pke5preri2eru#8923695`

row key 스키마에서 #을 구분 기호로 식별하고 row key 세그먼트를 다음과 같이 정의할 수 있습니다.

row key 세그먼트 유형 인코딩
기기 유형 (휴대전화) STRING UTF-8
국가 (인도) STRING UTF-8
제조업체 ID (pke5preri2eru) STRING UTF-8
일련번호 (8923695) BYTES 원시

필수 권한

필요한 권한은 수행하려는 작업에 따라 다릅니다.

이러한 권한을 얻으려면 관리자에게 권한이 포함된 테이블의 역할을 부여해 달라고 요청하세요.

  • row key 스키마 보기: bigtable.tables.get
  • row key 스키마 만들기: bigtable.tables.update
  • row key 스키마 삭제: bigtable.tables.update

액세스 권한 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

row key 스키마 만들기

연속 구체화된 뷰를 만들면 Bigtable에서 자동으로 뷰의 row key 스키마를 만듭니다. 자세한 내용은 연속 구체화된 뷰를 참조하세요.

연속 구체화된 뷰가 아닌 테이블의 row key 스키마를 정의하려면 테이블의 일부로 저장되는 RowKeySchema 필드를 추가하여 테이블을 업데이트합니다.

gcloud

gcloud CLI를 사용하여 row key 스키마를 정의하려면 스키마를 정의하는 YAML 또는 JSON 파일과 함께 gcloud beta bigtable tables update 명령어를 사용합니다.

gcloud beta bigtable tables update TABLE_ID \
  --instance=INSTANCE_ID \
  --row-key-schema-definition-file=ROW_KEY_SCHEMA_DEFINITION_FILE \
  --row-key-schema-pre-encoded-bytes

다음을 바꿉니다.

  • TABLE_ID: 업데이트하려는 테이블의 고유 ID
  • INSTANCE_ID: 테이블이 있는 인스턴스의 ID
  • ROW_KEY_SCHEMA_DEFINITION_FILE: row key 스키마를 정의하는 YAML 또는 JSON 파일의 경로입니다. 이러한 파일의 모양에 대한 예시는 스키마 파일 예시를 참조하세요.

기본적으로 Base64 인코딩은 row key 구분 기호의 encoding.delimitedBytes.delimiter와 같이 YAML 또는 JSON 파일의 모든 바이너리 필드에 적용됩니다. --row-key-schema-pre-encoded-bytes 플래그는 Bigtable에 바이너리 필드가 파일에 인코딩되어 있으며 다시 인코딩해서는 안 된다고 알려줍니다.

Go

UpdateTableWithRowKeySchema 함수를 사용하여 테이블의 row key 스키마를 만듭니다.

func (ac *AdminClient) UpdateTableWithRowKeySchema(ctx context.Context, tableID
string, rowKeySchema StructType) error

다음 예시에서는 rks라는 스키마를 만들고 테이블에 추가합니다.

rks := StructType{
Fields: []StructField{
    {FieldName: "key1", FieldType: Int64Type{Encoding: Int64OrderedCodeBytesEncoding{}}},
    {FieldName: "key2", FieldType: StringType{Encoding: StringUtf8BytesEncoding{}}},
  },
  Encoding: StructDelimitedBytesEncoding{Delimiter: []byte{'#'}}}

err := c.UpdateTableWithRowKeySchema(context.Background(), "my-table", rks)

row key 스키마 삭제

gcloud

테이블의 row key 스키마를 삭제하려면 gcloud beta bigtable tables update 명령어를 --clear-row-key-schema 플래그와 함께 사용합니다.

  gcloud beta bigtable tables update TABLE_NAME \
    --instance=INSTANCE_ID \
    --clear-row-key-schema

다음을 바꿉니다.

  • TABLE_NAME: row key 스키마를 삭제하려는 테이블의 고유 이름
  • INSTANCE_ID: 테이블이 있는 인스턴스의 ID

Go

UpdateTableRemoveRowKeySchema 함수를 사용하여 테이블의 row key 스키마를 지웁니다.

func (ac *AdminClient) UpdateTableRemoveRowKeySchema(ctx context.Context,
tableID string) error

row key 스키마 수정

row key 스키마는 직접 수정할 수 없습니다. row key 스키마를 변경하려면 스키마를 삭제하고 변경사항이 포함된 새 스키마를 만들어야 합니다.

row key 스키마 보기

gcloud

row key 스키마를 보려면 gcloud beta bigtable tables describe 명령어를 사용합니다.

  gcloud bigtable tables describe TABLE_NAME \
    --instance=INSTANCE_ID

다음을 바꿉니다.

  • TABLE_NAME: row key 스키마를 보려는 테이블의 고유 이름
  • INSTANCE_ID: 테이블이 있는 인스턴스의 ID

터미널의 응답은 다음과 유사합니다. 테이블에 row key 스키마가 없으면 응답에 rowKeySchema 섹션이 포함되지 않습니다.

columnFamilies:
  cf: {}
createTime: '2025-05-28T17:25:39.433058Z'
granularity: MILLIS
name: projects/<project>/instances/<instance>/tables/<table>
rowKeySchema:
  encoding:
    delimitedBytes:
      delimiter: Iw==
  fields:
  - fieldName: <field_name_1>
    type:
      stringType:
        encoding:
          utf8Bytes: {}
  - fieldName: <field_name_2>
    type:
      intType:
        encoding:
          bigEndianBytes: {}
  - fieldName: <field_name_3>
    type:
      timestampType:
        encoding:
          unixMicrosInt64: {
              encoding: {
                  orderedCodeBytes: {}
              }
          }
updateTime: '2025-05-28T17:25:39.433058Z'

Go

RowKeySchema 필드는 TableInfo 객체의 일부로 제공되며 .TableInfo() 메서드를 사용하여 검색합니다.

type TableInfo struct {
  ...
  RowKeySchema          *StructType
}

func (ac *AdminClient) TableInfo(ctx context.Context, table string) (*TableInfo, error)

구조화된 row key 쿼리

구조화된 row key의 열을 쿼리하려면 SQL을 사용해야 합니다. Bigtable Data API ReadRows 메서드는 테이블에서 읽을 때 row key 스키마를 무시합니다.

구조화된 row key를 선택하는 쿼리의 예시는 구조화된 row key 쿼리를 참조하세요.

코드 샘플을 비롯하여 SQL 쿼리를 지원하는 Bigtable 클라이언트 라이브러리 목록은 Bigtable 클라이언트 라이브러리에 SQL 사용을 참조하세요.

스키마 파일 예시

gcloud CLI를 사용하여 row key 스키마를 만들 때 YAML 파일 또는 JSON 파일을 사용하여 구조화된 row key를 정의할 수 있습니다.

YAML 

fields:
  - fieldName: "user_id"
    type:
      stringType:
        encoding:
          utf8Bytes: {}
  - fieldName: "purchase_date"
    type:
      stringType:
        encoding:
          utf8Bytes: {}
  - fieldName: "order_number"
    type:
      stringType:
        encoding:
          utf8Bytes: {}
encoding:
  delimitedBytes:
    delimiter: "Iw=="

JSON 

{
  "fields": [
    {
      "fieldName": "user_id",
      "type": {
        "stringType": {
          "encoding": {
            "utf8Bytes": {}
          }
        }
      }
    },
    {
      "fieldName": "purchase_date",
      "type": {
        "stringType": {
          "encoding": {
            "utf8Bytes": {}
          }
        }
      }
    },
    {
      "fieldName": "order_number",
      "type": {
        "stringType": {
          "encoding": {
            "utf8Bytes": {}
          }
        }
      }
    }
  ],
  "encoding": {
    "delimitedBytes": {
      "delimiter": "Iw=="
    }
  }
}

다음 단계