구조화된 row key를 사용하면 관계형 데이터베이스의 복합 키와 유사한 다중 파트 키를 사용하여 Bigtable 데이터에 액세스할 수 있습니다. 테이블의 구조화된 행 키를 정의하면 Bigtable 쿼리에 GoogleSQL을 사용하여 행 키의 특정 부분에 액세스할 수 있습니다.
행 키 스키마를 만들어 행 키의 각 세그먼트의 데이터 유형과 인코딩 방식을 정의할 수 있습니다. Bigtable은 행 키를 사전순으로 정렬된 바이트로 저장하며, 행 키 스키마는 Bigtable용 GoogleSQL에 이러한 바이트를 디코딩하고 해석하는 방법을 알려줍니다.
구조화된 행 키를 사용하는지 여부와 관계없이 행 키 설계 권장사항이 적용됩니다. 자세한 내용은 행 키를 참고하세요.
기기 유형, 국가, 제조업체 ID, 일련번호 값 사이에 구분자가 있는 다음 샘플 행 키를 고려해 보세요.
`phone#india#pke5preri2eru#8923695`
행 키 스키마에서 #를 구분자로 식별하고 행 키 세그먼트를 다음과 같이 정의할 수 있습니다.
Row key segment
유형
인코딩
기기 유형 (휴대전화)
문자열
UTF-8
국가 (인도)
문자열
UTF-8
제조업체 ID (pke5preri2eru)
문자열
UTF-8
일련번호 (8923695)
BYTES
원시
필수 권한
필요한 권한은 수행하려는 작업에 따라 다릅니다.
이러한 권한을 얻으려면 관리자에게 권한이 포함된 테이블의 역할을 부여해 달라고 요청하세요.
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 함수를 사용하여 테이블의 행 키 스키마를 만듭니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[],[],null,["Manage row key schemas\n| **Preview**\n|\n|\n| This product or feature is subject to the \"Pre-GA Offerings Terms\" in the General Service Terms section\n| of the [Service Specific Terms](/terms/service-terms#1).\n|\n| Pre-GA products and features are available \"as is\" and might have limited support.\n|\n| For more information, see the\n| [launch stage descriptions](/products#product-launch-stages).\n\n*Structured row keys* let you access your Bigtable data using\nmulti-part keys, similar to composite keys in relational databases. Defining\nstructured row keys for a table lets you access specific parts of the row keys\nusing GoogleSQL for Bigtable queries.\n\nBy creating a *row key schema*, you can define the data type of each segment of\na row key and how it is encoded. Bigtable stores the row keys as\nlexicographically sorted bytes, and the row key schema tells\nGoogleSQL for Bigtable how to decode and interpret\nthose bytes.\n\nThe best practices for designing row keys apply whether you're using structured\nrow keys or not. For more information, see [Row\nkeys](/bigtable/docs/schema-design#row-keys).\n| **Important:** If any row keys in a table don't conform to the row key schema, queries that select structured row key columns fail and return an error.\n\nConsider the following sample row key, which has delimiters between values for\ndevice type, country, manufacturer ID, and serial number: \n\n `phone#india#pke5preri2eru#8923695`\n\nIn the row key schema, you might identify `#` as the delimiter and define the\nrow key segments as follows:\n\n| **Row key segment** | **Type** | **Encoding** |\n|---------------------------------|----------|--------------|\n| Device type (phone) | STRING | UTF-8 |\n| Country (India) | STRING | UTF-8 |\n| Manufacturer ID (pke5preri2eru) | STRING | UTF-8 |\n| Serial number (8923695) | BYTES | Raw |\n\nRequired permissions\n\nThe permissions that you need depend on the action that you want to perform.\n\nTo gain these permissions, ask your administrator to grant you a role on the\ntable that includes the permissions:\n\n- View a row key schema: `bigtable.tables.get`\n- Create a row key schema: `bigtable.tables.update`\n- Delete a row key schema: `bigtable.tables.update`\n\nFor more information about granting access, see [Manage access to projects,\nfolders, and organizations](/iam/docs/granting-changing-revoking-access).\n\nCreate a row key schema\n\nWhen you create a continuous materialized view, Bigtable\nautomatically creates a row key schema for the view. For more information, see\n[Continuous materialized views](/bigtable/docs/continuous-materialized-views).\n\nTo define a row key schema for a table that is not a continuous materialized\nview, you update the table by adding a `RowKeySchema` field that is stored as\npart of the table. \n\ngcloud\n\nTo define a row key schema using the gcloud CLI, use the\n[`gcloud beta bigtable tables\nupdate`](/sdk/gcloud/reference/beta/bigtable/tables/update)\ncommand with a YAML or JSON file that defines the schema. \n\n gcloud bigtable beta tables update \u003cvar translate=\"no\"\u003eTABLE_ID\u003c/var\u003e \\\n --instance=\u003cvar translate=\"no\"\u003eINSTANCE_ID\u003c/var\u003e \\\n --row-key-schema-definition-file=\u003cvar translate=\"no\"\u003eROW_KEY_SCHEMA_DEFINITION_FILE\u003c/var\u003e \\\n --row-key-schema-pre-encoded-bytes\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eTABLE_ID\u003c/var\u003e: the unique ID of the table you want to update\n- \u003cvar translate=\"no\"\u003eINSTANCE_ID\u003c/var\u003e: the ID of the instance where the table is located\n- \u003cvar translate=\"no\"\u003eROW_KEY_SCHEMA_DEFINITION_FILE\u003c/var\u003e: the path to your YAML or JSON file that defines the row key schema. For examples of what those files should look like, see [Example-schema-files](#example-schema-files).\n\nBy default, Base64 encoding is applied to all binary fields in a YAML or\nJSON file, such as `encoding.delimitedBytes.delimiter` for the row key\ndelimiter. The flag `--row-key-schema-pre-encoded-bytes` tells\nBigtable that binary fields are encoded in the file and shouldn't\nbe encoded again.\n\nGo\n\nUse the `UpdateTableWithRowKeySchema` function to create a row key schema for a\ntable. \n\n func (ac *AdminClient) UpdateTableWithRowKeySchema(ctx context.Context, tableID\n string, rowKeySchema StructType) error\n\nThe following example creates a schema called `rks` and adds it to the\ntable. \n\n rks := StructType{\n Fields: []StructField{\n {FieldName: \"key1\", FieldType: Int64Type{Encoding: Int64OrderedCodeBytesEncoding{}}},\n {FieldName: \"key2\", FieldType: StringType{Encoding: StringUtf8BytesEncoding{}}},\n },\n Encoding: StructDelimitedBytesEncoding{Delimiter: []byte{'#'}}}\n\n err := c.UpdateTableWithRowKeySchema(context.Background(), \"my-table\", rks)\n\nDelete a row key schema **Warning:** If you delete a row key schema, then SQL queries that depend on it no longer work as expected. Delete a row key schema only when you plan to immediately replace it. \n\ngcloud\n\nTo delete a table's row key schema, use the\n[`gcloud beta bigtable tables\nupdate`](/sdk/gcloud/reference/beta/bigtable/tables/update)\ncommand with the `--clear-row-key-schema` flag. \n\n gcloud beta bigtable tables update \u003cvar translate=\"no\"\u003eTABLE_NAME\u003c/var\u003e \\\n --instance=\u003cvar translate=\"no\"\u003eINSTANCE_ID\u003c/var\u003e \\\n --clear-row-key-schema\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eTABLE_NAME\u003c/var\u003e: the unique name of the table from which you want to delete the row key schema\n- \u003cvar translate=\"no\"\u003eINSTANCE_ID\u003c/var\u003e: the ID of the instance where the table is located\n\nGo\n\nUse the `UpdateTableRemoveRowKeySchema` function to clear the row key schema\nfor a table: \n\n func (ac *AdminClient) UpdateTableRemoveRowKeySchema(ctx context.Context,\n tableID string) error\n\nModify a row key schema\n\nYou can't modify a row key schema directly. To change a row key schema, you\nmust delete the schema and create a new one that includes your changes.\n\nView a row key schema \n\ngcloud\n\nTo view a row key schema, use the [`gcloud beta bigtable tables\ndescribe`](/sdk/gcloud/reference/beta/bigtable/tables/describe) command: \n\n gcloud bigtable tables describe \u003cvar translate=\"no\"\u003eTABLE_NAME\u003c/var\u003e \\\n --instance=\u003cvar translate=\"no\"\u003eINSTANCE_ID\u003c/var\u003e\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eTABLE_NAME\u003c/var\u003e: the unique name of the table whose row key schema you want to view\n- \u003cvar translate=\"no\"\u003eINSTANCE_ID\u003c/var\u003e: the ID of the instance where the table is located\n\nThe response in the terminal is similar to the following. If the table\ndoesn't have a row key schema, the response doesn't include a `rowKeySchema`\nsection. \n\n columnFamilies:\n cf: {}\n createTime: '2025-05-28T17:25:39.433058Z'\n granularity: MILLIS\n name: projects/\u003cproject\u003e/instances/\u003cinstance\u003e/tables/\u003ctable\u003e\n rowKeySchema:\n encoding:\n delimitedBytes:\n delimiter: Iw==\n fields:\n - fieldName: \u003cfield_name_1\u003e\n type:\n stringType:\n encoding:\n utf8Bytes: {}\n - fieldName: \u003cfield_name_2\u003e\n type:\n intType:\n encoding:\n bigEndianBytes: {}\n - fieldName: \u003cfield_name_3\u003e\n type:\n timestampType:\n encoding:\n unixMicrosInt64: {\n encoding: {\n orderedCodeBytes: {}\n }\n }\n updateTime: '2025-05-28T17:25:39.433058Z'\n\nGo\n\nThe `RowKeySchema` field is available as part of the `TableInfo` object, and\nyou retrieve it using the `.TableInfo()` method. \n\n type TableInfo struct {\n ...\n RowKeySchema *StructType\n }\n\n func (ac *AdminClient) TableInfo(ctx context.Context, table string) (*TableInfo, error)\n\nQuerying structured row keys\n\nTo query the columns in structured row keys, you must use SQL. The\nBigtable Data API `ReadRows` method ignores a row key schema when it\nreads from a table.\n\nFor examples of queries selecting structured row keys, see [Structured row\nkey queries](/bigtable/docs/structured-row-key-queries).\n\nFor a list of Bigtable client libraries that support SQL queries,\nincluding code samples, see [Use SQL with a Bigtable client\nlibrary](/bigtable/docs/googlesql-overview#client-libraries).\n\nExample schema files\n\nWhen you create a row key schema using the gcloud CLI, you can define\nthe structured row keys using either a YAML file or a JSON file. \n\nYAML \n\n fields:\n - field_name: \"user_id\"\n type:\n bytesType:\n encoding:\n raw: {}\n - fieldBame: \"purchase_date\"\n type:\n stringType:\n encoding:\n utf8Bytes: {}\n - fieldName: \"order_number\"\n type:\n bytes_type:\n encoding:\n utf8Bytes: {}\n encoding:\n delimited_bytes:\n delimiter: \"#\"\n\nJSON \n\n {\n \"fields\": [\n {\n \"fieldName\": \"user_id\",\n \"type\": {\n \"bytesType\": {\n \"encoding\": {\n \"raw\": {}\n }\n }\n }\n },\n {\n \"fieldName\": \"purchase_date\",\n \"type\": {\n \"stringType\": {\n \"encoding\": {\n \"utf8Bytes\": {}\n }\n }\n }\n },\n {\n \"fieldName\": \"order_number\",\n \"type\": {\n \"bytesType\": {\n \"encoding\": {\n \"utf8Bytes\": {}\n }\n }\n }\n }\n ],\n \"encoding\": {\n \"delimitedBytes\": {\n \"delimiter\": \"#\"\n }\n }\n }\n\nWhat's next\n\n- [Create and manage continuous materialized views](/bigtable/docs/manage-continuous-materialized-views)\n- [GoogleSQL for Bigtable overview](/bigtable/docs/googlesql-overview)"]]
