Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

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 필드를 추가하여 테이블을 업데이트합니다.

콘솔

콘솔을 사용하여 row key 스키마를 정의하려면 다음 단계를 따르세요. Google Cloud

콘솔에서 Bigtable 인스턴스 페이지를 엽니다. Google Cloud

인스턴스 목록으로 이동
목록에서 인스턴스를 선택합니다.
탐색 메뉴에서 Bigtable Studio 를 클릭합니다.

탐색기 창에 인스턴스의 테이블, 뷰, 쿼리 목록이 표시됩니다.
테이블 목록에서 row key 스키마를 만들려는 테이블의 작업 보기 메뉴를 클릭한 후 row key 스키마 만들기를 클릭합니다.

row key 스키마 탭이 열립니다.
인코딩 목록에서 row key 스키마의 인코딩 유형을 선택합니다.
DelimitedBytes를 선택한 경우 구분 기호 필드에 기존 row key의 세그먼트를 구분하는 구분 기호를 입력합니다. 기본값은 해시 기호 (#)입니다.
세그먼트 필드에 device_type과 같은 세그먼트 이름을 입력합니다.
유형 목록에서 row key 세그먼트의 데이터 유형을 선택합니다.
선택한 데이터 유형에 따라 바이트 인코딩 목록에서 row key 세그먼트의 기본 인코딩 유형을 그대로 두거나 변경합니다.
선택사항: row key 세그먼트에 두 개 이상의 파트가 있는 경우 row key 세그먼트 추가 를 클릭하여 필드를 추가합니다.
저장 을 클릭합니다.

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 스키마 삭제

콘솔

콘솔을 사용하여 테이블의 row key 스키마를 삭제하려면 다음 단계를 따르세요. Google Cloud

콘솔에서 Bigtable 인스턴스 페이지를 엽니다. Google Cloud

인스턴스 목록으로 이동
목록에서 인스턴스를 선택합니다.
탐색 메뉴에서 Bigtable Studio 를 클릭합니다.

탐색기 창에 인스턴스의 테이블, 뷰, 쿼리 목록이 표시됩니다.
테이블 목록에서 삭제하려는 row key 스키마가 있는 테이블을 클릭합니다.
삭제하려는 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 스키마 보기

콘솔

콘솔을 사용하여 테이블의 row key 스키마를 보려면 다음 단계를 따르세요. Google Cloud

콘솔에서 Bigtable 인스턴스 페이지를 엽니다. Google Cloud

인스턴스 목록으로 이동
테이블의 row key 스키마를 보려는 인스턴스를 클릭합니다.
탐색 메뉴에서 Bigtable Studio 를 클릭합니다.

탐색기 창에 인스턴스의 테이블, 뷰, 쿼리 목록이 표시됩니다.
테이블 목록에서 보려는 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=="
    }
  }
}