Amazon S3 테이블 만들기

Amazon S3 테이블 만들기 (Creating an Amazon S3 table)

Amazon S3 테이블은 테이블 버킷의 하위 리소스(subresource)예요. 테이블은 Apache Iceberg 형식으로 저장되어, Apache Iceberg를 지원하는 쿼리 엔진과 다른 애플리케이션으로 작업할 수 있어요. Amazon S3는 스토리지 비용을 줄이고 분석 쿼리 성능을 높이기 위해 테이블을 지속적으로 최적화해요.

출처: 문서

본문

테이블을 만들면 Amazon S3가 테이블의 웨어하우스 위치(warehouse location)를 자동으로 생성해요. 웨어하우스 위치는 테이블과 연관된 객체를 읽고 쓸 수 있는 고유한 S3 위치예요. 다음 예시는 웨어하우스 위치의 형식을 보여줘요.

s3://63a8e430-6e0b-46f5-k833abtwr6s8tmtsycedn8s4yc3xhuse1b--table-s3

테이블은 다음 Amazon Resource Name(ARN) 형식을 가져요.

arn:aws:s3tables:region:owner-account-id:bucket/bucket-name/table/table-id

기본적으로 테이블 버킷에는 최대 10,000개의 테이블을 만들 수 있어요. 테이블 버킷이나 테이블의 할당량(quota) 증가를 요청하려면 Support(지원)에 문의하세요.

테이블은 Amazon S3 콘솔, Amazon S3 REST API, AWS SDK, AWS Command Line Interface(AWS CLI), 또는 테이블 버킷에 연결된 쿼리 엔진으로 만들 수 있어요.

테이블을 만들 때 그 테이블의 암호화 설정을 지정할 수 있어요. 다만 Athena로 테이블을 만드는 경우는 예외예요. 암호화 설정을 지정하지 않으면 테이블은 테이블 버킷의 기본 설정으로 암호화돼요. 자세한 내용은 "Specifying encryption for tables" 문서를 참고하세요.

테이블 만들기 사전 조건

테이블을 만들려면 먼저 다음을 해야 해요.

  • 테이블 버킷을 만들어요.
  • 테이블 버킷에 네임스페이스를 만들어요.
  • s3tables:CreateTable과 s3tables:PutTableData에 대한 AWS Identity and Access Management(IAM) 권한이 있는지 확인해요.
  • 참고: 테이블에 SSE-KMS 암호화를 사용한다면 s3tables:PutTableEncryption에 대한 권한과 선택한 AWS KMS 키에 대한 DescribeKey 권한이 필요해요. 또한 사용하는 AWS KMS 키가 S3 Tables에 자동 테이블 유지 관리를 수행할 권한을 부여해야 해요. 자세한 내용은 "Permission requirements for S3 Tables SSE-KMS encryption" 문서를 참고하세요.

유효한 테이블 이름에 대한 정보는 "Naming rules for tables and namespaces" 문서를 참고하세요.

중요: 테이블을 만들 때 테이블 이름과 테이블 정의에 소문자만 사용하세요. 예를 들어 컬럼 이름을 모두 소문자로 만들어요. 테이블 이름이나 테이블 정의에 대문자가 포함되면 AWS Lake Formation이나 AWS Glue Data Catalog가 그 테이블을 지원하지 않아요. 이 경우 테이블 버킷이 AWS 분석 서비스와 통합돼 있어도 Amazon Athena 같은 AWS 분석 서비스에 테이블이 보이지 않아요.

테이블 정의에 대문자가 포함되면 Athena에서 SELECT 쿼리를 실행할 때 다음 오류 메시지를 받아요: "GENERIC_INTERNAL_ERROR: Get table request failed: com.amazonaws.services.glue.model.ValidationException: Unsupported Federation Resource - Invalid table or column names."

다음 절차는 Amazon S3 콘솔에서 Amazon Athena로 테이블을 만드는 방법이에요. 테이블 버킷에 네임스페이스를 아직 만들지 않았다면 이 과정의 일부로 만들 수 있어요. 다음 단계를 수행하기 전에 이 리전에서 테이블 버킷을 AWS 분석 서비스와 통합했는지 확인하세요. 자세한 내용은 "Integrating Amazon S3 Tables with AWS analytics services" 문서를 참고하세요.

참고: Athena로 테이블을 만들면 그 테이블은 테이블 버킷의 기본 암호화 설정을 상속해요. 다른 암호화 유형을 사용하려면 다른 방법으로 테이블을 만들어야 해요.

테이블을 만들려면:

  1. AWS Management Console에 로그인하고 https://console.aws.amazon.com/s3/ 에서 Amazon S3 콘솔을 열어요.
  2. 왼쪽 탐색 창에서 Table buckets를 선택해요.
  3. Table buckets 페이지에서 테이블을 만들 버킷을 선택해요.
  4. 버킷 세부 정보 페이지에서 Create table with Athena를 선택해요.
  5. Create table with Athena 대화 상자에서 다음 중 하나를 수행해요.
    • 새 네임스페이스 만들기: Create a namespace를 선택한 다음 Namespace name 필드에 이름을 입력해요. 네임스페이스 이름은 1~255자여야 하고 테이블 버킷 안에서 고유해야 해요. 유효한 문자는 a–z, 0–9, 밑줄(_)이에요. 밑줄은 네임스페이스 이름의 시작에 쓸 수 없어요. Create namespace를 선택해요.
    • 기존 네임스페이스 지정하기: Specify an existing namespace within this table bucket을 선택해요. 그런 다음 Choose from existing namespaces 또는 Enter an existing namespace name을 선택해요. 버킷에 네임스페이스가 1,000개보다 많고 이름이 목록에 나타나지 않으면 네임스페이스 이름을 입력해야 해요.
  6. Create table with Athena를 선택해요.
  7. Amazon Athena 콘솔이 열리고 Athena 쿼리 편집기가 나타나요. Catalog 필드에는 s3tablescatalog/ 다음에 테이블 버킷 이름이 채워져야 해요. 예를 들어 s3tablescatalog/amzn-s3-demo-bucket처럼요. Database 필드에는 앞에서 만들거나 선택한 네임스페이스가 채워져야 해요.

    참고: Catalog와 Database 필드에 이 값들이 보이지 않으면 이 리전에서 테이블 버킷을 AWS 분석 서비스와 통합했는지 확인하세요. 자세한 내용은 "Integrating Amazon S3 Tables with AWS analytics services" 문서를 참고하세요.

  8. 쿼리 편집기에는 테이블을 만드는 데 사용할 수 있는 샘플 쿼리가 채워져 있어요. 테이블에 넣을 테이블 이름과 컬럼을 지정하도록 쿼리를 수정해요.
  9. 쿼리 수정을 마쳤으면 Run을 선택해 테이블을 만들어요.

    참고: Athena에서 쿼리를 실행할 때 "Insufficient permissions to execute the query. Principal does not have any privilege on specified resource" 오류가 발생하면 테이블에 필요한 Lake Formation 권한을 부여받아야 해요. 자세한 내용은 "Granting Lake Formation permission on a table or database" 문서를 참고하세요. Athena에서 쿼리를 실행할 때 "Iceberg cannot access the requested resource" 오류가 발생하면 AWS Lake Formation 콘솔로 가서 만든 테이블 버킷 카탈로그와 데이터베이스(네임스페이스)에 자신의 권한을 부여했는지 확인하세요. 이 권한을 부여할 때 테이블을 지정하지 마세요. 자세한 내용은 "Granting Lake Formation permission on a table or database" 문서를 참고하세요. Athena에서 SELECT 쿼리를 실행할 때 다음 오류 메시지가 발생하면 테이블 이름이나 테이블 정의의 컬럼 이름에 대문자가 있어서예요: "GENERIC_INTERNAL_ERROR: Get table request failed: com.amazonaws.services.glue.model.ValidationException: Unsupported Federation Resource - Invalid table or column names." 테이블과 컬럼 이름이 모두 소문자인지 확인하세요.

테이블 생성이 성공하면 새 테이블 이름이 Athena의 테이블 목록에 나타나요. Amazon S3 콘솔로 돌아가면 목록을 새로고침한 후 테이블 버킷의 버킷 세부 정보 페이지 Tables 목록에 새 테이블이 나타나요.

AWS CLI로 스키마가 있는 테이블을 만들고 JSON으로 테이블 메타데이터를 지정하는 예시는 다음과 같아요. 이 예시를 사용할 때는 사용자 입력 자리표시자를 자신의 정보로 바꾸세요.

aws s3tables create-table --cli-input-json file://mytabledefinition.json

mytabledefinition.json 파일에는 다음 예시 테이블 정의를 사용해요. 파티션 테이블을 만들려면 테이블 메타데이터에 partitionSpec을 포함해요. 각 파티션 필드는 sourceId로 스키마의 컬럼을 참조하고, 파티션 값을 생성하기 위해 변환(identity, bucket, truncate, year, month, day, hour 등)을 적용해요. 파티션 필드는 ID로 스키마 컬럼을 참조하므로 스키마의 각 필드에 명시적 ID를 할당해야 해요. 다음 예시는 스키마 필드에 ID를 할당하고 day 변환을 사용해 registration_date 컬럼으로 테이블을 파티션해요. 이 예시를 사용할 때는 사용자 입력 자리표시자를 자신의 정보로 바꾸세요.

{
    "tableBucketARN": "arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket",
    "namespace": "your_namespace",
    "name": "example_table",
    "format": "ICEBERG",
    "metadata": {
        "iceberg": {
            "schema": {
                "fields": [
                     {"id": 1, "name": "id", "type": "int", "required": true},
                     {"id": 2, "name": "name", "type": "string"},
                     {"id": 3, "name": "registration_date", "type": "timestamp"}
                ]
            },
            "partitionSpec": {
                "specId": 0,
                "fields": [
                    {"sourceId": 3, "transform": "day", "name": "registration_day"}
                ]
            }
        }
    }
}

테이블 버킷에 연결된 지원되는 쿼리 엔진(예: Amazon EMR의 Apache Spark 세션)에서 테이블을 만들 수도 있어요.

다음 예시는 CREATE 문으로 Spark에서 테이블을 만들고, INSERT 문이나 기존 파일에서 데이터를 읽어 테이블 데이터를 추가하는 방법을 보여줘요. 파티션 테이블을 만들려면 CREATE 문에 PARTITIONED BY 절을 추가해요. 하나 이상의 컬럼을 직접(identity 파티셔닝) 또는 bucket, truncate, years, months, days, hours 같은 파티션 변환을 적용해 파티션할 수 있어요. 다음 예시는 days 변환으로 registration_date 컬럼으로 테이블을 파티션해요. 이 예시를 사용할 때는 사용자 입력 자리표시자를 자신의 정보로 바꾸세요.

spark.sql(
"CREATE TABLE IF NOT EXISTS s3tablesbucket.example_namespace.`example_table` (
    id INT,
    name STRING,
    registration_date TIMESTAMP
)
USING iceberg
PARTITIONED BY (days(registration_date))"
)

테이블을 만든 뒤에는 테이블에 데이터를 로드할 수 있어요. 다음 방법 중에서 선택해요.

  • INSERT 문으로 테이블에 데이터를 추가해요. 
    spark.sql("""
    INSERT INTO s3tablesbucket.my_namespace.my_table VALUES
        (1, 'ABC', 100),
        (2, 'XYZ', 200)
""")
  • 기존 데이터 파일을 로드해요.
    • 데이터를 Spark로 읽어요. 
      val data_file_location = "Path such as S3 URI to data file"
val data_file = spark.read.parquet(data_file_location)
    • 데이터를 Iceberg 테이블로 작성해요. 
      data_file.writeTo("s3tablesbucket.my_namespace.my_table").using("Iceberg").tableProperty("format-version", "2").createOrReplace()

더 알아보기 (Learn more)

  • 테이블 (Tables)
  • 테이블 삭제하기 (Delete a table)