행 키 스키마 관리

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

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

구조화된 행 키를 사용하는지 여부와 관계없이 행 키 설계 권장사항이 적용됩니다. 자세한 내용은 행 키를 참고하세요.

기기 유형, 국가, 제조업체 ID, 일련번호 값 사이에 구분자가 있는 다음 샘플 행 키를 고려해 보세요.

`phone#india#pke5preri2eru#8923695`

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

Row key segment 유형 인코딩
기기 유형 (휴대전화) 문자열 UTF-8
국가 (인도) 문자열 UTF-8
제조업체 ID (pke5preri2eru) 문자열 UTF-8
일련번호 (8923695) BYTES 원시

필수 권한

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

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

  • 행 키 스키마를 확인합니다. bigtable.tables.get
  • 행 키 스키마를 만듭니다. bigtable.tables.update
  • 행 키 스키마 삭제: bigtable.tables.update

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

행 키 스키마 만들기

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

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

gcloud

gcloud CLI를 사용하여 행 키 스키마를 정의하려면 스키마를 정의하는 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: 행 키 스키마를 정의하는 YAML 또는 JSON 파일의 경로입니다. 이러한 파일의 예시는 Example-schema-files를 참고하세요.

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

Go

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

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)

행 키 스키마 삭제

gcloud

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

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

다음을 바꿉니다.

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

Go

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

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

row key 스키마 수정

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

행 키 스키마 보기

gcloud

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

  gcloud bigtable tables describe TABLE_NAME \
    --instance=INSTANCE_ID

다음을 바꿉니다.

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

터미널의 응답은 다음과 유사합니다. 표에 행 키 스키마가 없으면 응답에 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 쿼리

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

구조화된 행 키를 선택하는 쿼리의 예시는 구조화된 행 키 쿼리를 참고하세요.

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

스키마 파일 예시

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

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=="
    }
  }
}

다음 단계