Amazon S3 Tables Iceberg REST 엔드포인트로 테이블 접근하기

Amazon S3 Tables Iceberg REST 엔드포인트로 테이블 접근하기 (Accessing tables using the Iceberg REST endpoint)

Iceberg REST 클라이언트를 Amazon S3 Tables Iceberg REST 엔드포인트에 연결하면 REST API 호출로 S3 테이블 버킷에서 테이블을 만들고, 업데이트하고, 쿼리할 수 있어요. 이 엔드포인트는 Apache Iceberg REST Catalog Open API 스펙에 지정된 표준화된 Iceberg REST API 세트를 구현해요. 이 엔드포인트는 Iceberg REST API 작업을 해당 S3 Tables 작업으로 변환해 동작해요.

출처: 문서

본문

참고: Amazon S3 Tables Iceberg REST 엔드포인트는 AWS Partner Network(APN) 카탈로그 구현이나 커스텀 카탈로그 구현의 테이블에 접근하는 데 사용할 수 있어요. 단일 테이블 버킷에 기본 읽기·쓰기 접근만 필요할 때도 사용할 수 있어요. 다른 접근 시나리오에서는 통합된 테이블 관리, 중앙 집중식 거버넌스, 세분화된 접근 제어를 제공하는 AWS Glue Iceberg REST 엔드포인트로 테이블에 연결할 것을 권장해요. 자세한 내용은 "Accessing Amazon S3 tables using the AWS Glue Iceberg REST endpoint" 문서를 참고하세요.

엔드포인트 구성하기

서비스 엔드포인트를 사용해 Amazon S3 Tables Iceberg REST 엔드포인트에 연결해요. S3 Tables Iceberg REST 엔드포인트는 다음 형식이에요.

https://s3tables.<REGION>.amazonaws.com/iceberg

리전별 엔드포인트는 "S3 Tables AWS Regions and endpoints" 문서를 참고하세요.

카탈로그 구성 속성

Iceberg 클라이언트로 분석 엔진을 서비스 엔드포인트에 연결할 때는 카탈로그를 초기화하면서 다음 구성 속성을 지정해야 해요. 자리표시자 값을 리전과 테이블 버킷 정보로 바꾸세요.

• 엔드포인트 URI로 리전별 엔드포인트: https://s3tables.<REGION>.amazonaws.com/iceberg
• 웨어하우스 위치로 테이블 버킷 ARN: arn:aws:s3tables:<region>:<accountID>:bucket/<bucketname>
• 인증을 위한 Sigv4 속성. 서비스 엔드포인트 요청의 SigV4 서명 이름(signing name)은 s3tables예요.

다음 예시들은 다양한 클라이언트를 Amazon S3 Tables Iceberg REST 엔드포인트로 구성하는 방법을 보여줘요.

PyIceberg

PyIceberg에서 Amazon S3 Tables Iceberg REST 엔드포인트를 사용하려면 다음 애플리케이션 구성 속성을 지정해요.

rest_catalog = load_catalog(
  "catalog_name",
  **{
    "type": "rest",
    "warehouse":"arn:aws:s3tables:<Region>:<accountID>:bucket/<bucketname>",
    "uri": "https://s3tables.<Region>.amazonaws.com/iceberg",
    "rest.sigv4-enabled": "true",
    "rest.signing-name": "s3tables",
    "rest.signing-region": "<Region>"
  }
)

Apache Spark

Spark에서 Amazon S3 Tables Iceberg REST 엔드포인트를 사용하려면 다음 애플리케이션 구성 속성을 지정하고, 자리표시자 값을 리전과 테이블 버킷 정보로 바꿔요.

spark-shell \
  --packages "org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.4.1,software.amazon.awssdk:bundle:2.20.160,software.amazon.awssdk:url-connection-client:2.20.160" \
  --master "local[*]" \
  --conf "spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" \
  --conf "spark.sql.defaultCatalog=spark_catalog" \
   --conf "spark.sql.catalog.spark_catalog=org.apache.iceberg.spark.SparkCatalog" \
  --conf "spark.sql.catalog.spark_catalog.type=rest" \
  --conf "spark.sql.catalog.spark_catalog.uri=https://s3tables.<Region>.amazonaws.com/iceberg" \
  --conf "spark.sql.catalog.spark_catalog.warehouse=arn:aws:s3tables:<Region>:<accountID>:bucket/<bucketname>" \
  --conf "spark.sql.catalog.spark_catalog.rest.sigv4-enabled=true" \
  --conf "spark.sql.catalog.spark_catalog.rest.signing-name=s3tables" \
  --conf "spark.sql.catalog.spark_catalog.rest.signing-region=<Region>" \
  --conf "spark.sql.catalog.spark_catalog.io-impl=org.apache.iceberg.aws.s3.S3FileIO" \
  --conf "spark.hadoop.fs.s3a.aws.credentials.provider=org.apache.hadoop.fs.s3a.SimpleAWSCredentialProvider" \
  --conf "spark.sql.catalog.spark_catalog.rest-metrics-reporting-enabled=false"

엔드포인트 접근 인증 및 권한 부여

S3 Tables 서비스 엔드포인트에 대한 API 요청은 AWS Signature Version 4(SigV4)로 인증돼요. AWS SigV4에 대해 자세히 알아보려면 "AWS Signature Version 4 for API requests" 문서를 참고하세요.

Amazon S3 Tables Iceberg REST 엔드포인트 요청의 SigV4 서명 이름은 s3tables예요.

Amazon S3 Tables Iceberg REST 엔드포인트에 대한 요청은 REST API 작업에 대응하는 s3tables IAM 작업으로 권한이 부여돼요. 이 권한은 IAM 자격 증명 기반 정책이나 테이블·테이블 버킷에 연결된 리소스 기반 정책으로 정의할 수 있어요. 자세한 내용은 "Access management for S3 Tables" 문서를 참고하세요.

AWS CloudTrail로 REST 엔드포인트를 통해 테이블에 대한 요청을 추적할 수 있어요. 요청은 해당 S3 IAM 작업으로 기록돼요. 예를 들어 LoadTable API는 GetTableMetadataLocation 작업에 대한 관리 이벤트와 GetTableData 작업에 대한 데이터 이벤트를 생성해요. 자세한 내용은 "Logging with AWS CloudTrail for S3 Tables" 문서를 참고하세요.

접두어 및 경로 파라미터

Iceberg REST 카탈로그 API는 요청 URL에 자유 형식 접두어(free-form prefix)가 있어요. 예를 들어 ListNamespaces API 호출은 GET /v1/{prefix}/namespaces URL 형식을 사용해요. S3 Tables의 경우 REST 경로의 {prefix}는 항상 URL 인코딩된 테이블 버킷 ARN이에요.

예를 들어 테이블 버킷 ARN arn:aws:s3tables:us-east-1:111122223333:bucket/bucketname에 대한 접두어는 arn%3Aaws%3As3tables%3Aus-east-1%3A111122223333%3Abucket%2Fbucketname이 돼요.

네임스페이스 경로 파라미터

Iceberg REST 카탈로그 API 경로의 네임스페이스는 여러 수준을 가질 수 있어요. 하지만 S3 Tables는 단일 수준 네임스페이스만 지원해요. 다중 수준 카탈로그 계층의 네임스페이스에 접근하려면 네임스페이스를 참조할 때 그 위의 다중 수준 카탈로그에 연결하면 돼요. 이렇게 하면 catalog.namespace.table의 3부분 표기법을 지원하는 모든 쿼리 엔진이 다중 수준 네임스페이스를 사용할 때와 비교해 호환성 문제 없이 S3 Tables의 카탈로그 계층에 있는 객체에 접근할 수 있어요.

지원되는 Iceberg REST API 작업

다음 표는 지원되는 Iceberg REST API와 S3 Tables 작업의 대응 관계를 보여줘요.

고려 사항 및 제한 사항

Amazon S3 Tables Iceberg REST 엔드포인트를 사용할 때의 고려 사항과 제한 사항은 다음과 같아요.

고려 사항

• CreateTable API 동작 – 이 작업에는 stage-create 옵션이 지원되지 않으며 400 Bad Request 오류가 발생해요. 즉 CREATE TABLE AS SELECT(CTAS)로 쿼리 결과에서 테이블을 만들 수 없어요.
• DeleteTable API 동작 – purge가 활성화된 상태에서만 테이블을 삭제(drop)할 수 있어요. purge=false로 삭제하는 것은 지원되지 않으며 400 Bad Request 오류가 발생해요. 일부 Spark 버전은 DROP TABLE PURGE 명령을 실행할 때도 이 플래그를 항상 false로 설정해요. DROP TABLE PURGE를 시도하거나 S3 Tables DeleteTable 작업으로 테이블을 삭제할 수 있어요.
• 이 엔드포인트는 표준 테이블 메타데이터 작업만 지원해요. 스냅샷 관리나 압축 같은 테이블 유지 관리는 S3 Tables 유지 관리 API 작업을 사용하세요. 자세한 내용은 "S3 Tables maintenance" 문서를 참고하세요.

제한 사항

• 다중 수준 네임스페이스는 지원되지 않아요.
• OAuth 기반 인증은 지원되지 않아요.
• 네임스페이스에는 owner 속성만 지원돼요.
• Apache Iceberg REST Open API 스펙에 정의된 뷰 관련 API는 지원되지 않아요.
• 50MB가 넘는 metadata.json 파일이 있는 테이블에서 작업을 실행하는 것은 지원되지 않으며 400 Bad Request 오류가 반환돼요. metadata.json 파일의 크기를 제어하려면 테이블 유지 관리 작업을 사용하세요. 자세한 내용은 "S3 Tables maintenance" 문서를 참고하세요.

더 알아보기 (Learn more)

• AWS Glue Iceberg REST 엔드포인트로 테이블 접근하기 (Accessing tables using the AWS Glue Iceberg REST endpoint)
• 클라이언트 카탈로그로 테이블 접근하기 (Accessing tables with the client catalog)