# Usar a estrutura Iceberg no AWS Glue
<a name="aws-glue-programming-etl-format-iceberg"></a>

O AWS Glue 3.0 e versões posteriores são compatíveis com a estrutura Apache Iceberg para data lakes. O Iceberg fornece um formato de tabela de alta performance que funciona exatamente como uma tabela SQL. Este tópico aborda os recursos disponíveis para usar dados no AWS Glue ao transportar ou armazenar dados em uma tabela do Iceberg. Para saber mais sobre o Iceberg, consulte a [documentação do Apache Iceberg](https://iceberg.apache.org/docs/latest/). 

É possível usar o AWS Glue para realizar operações de leitura e gravação em tabelas do Iceberg no Amazon S3 ou trabalhar com tabelas do Iceberg usando o AWS Glue Data Catalog. Operações adicionais, incluindo inserção e todas as [consultas do Spark](https://iceberg.apache.org/docs/latest/spark-queries/) e [gravações do Spark](https://iceberg.apache.org/docs/latest/spark-writes/) também são compatíveis. Não há suporte à atualização de tabelas do Iceberg. 

**nota**  
`ALTER TABLE … RENAME TO` não está disponível para o Apache Iceberg 0.13.1 para AWS Glue 3.0.

A tabela a seguir lista a versão do Iceberg incluída em cada versão do AWS Glue.


****  

| Versão do AWS Glue | Versão compatível do Iceberg | 
| --- | --- | 
| 5.1 | 1.10.0 | 
| 5,0 | 1.7.1 | 
| 4,0 | 1.0.0 | 
| 3.0 | 0.13.1 | 

Para saber mais sobre as estruturas de data lake compatíveis com o AWS Glue, consulte [Usar estruturas de data lake com trabalhos do AWS Glue ETL](aws-glue-programming-etl-datalake-native-frameworks.md).

## Habilitar a estrutura Iceberg
<a name="aws-glue-programming-etl-format-iceberg-enable"></a>

Para habilitar o Iceberg para AWS Glue, faça as seguintes tarefas:
+ Especifique `iceberg` como um valor para o parâmetro de trabalho `--datalake-formats`. Para obter mais informações, consulte [Usar parâmetros de tarefa em tarefas do AWS Glue](aws-glue-programming-etl-glue-arguments.md).
+ Crie uma chave denominada `--conf` para o trabalho do AWS Glue e defina-a com o seguinte valor. Ou então, é possível definir a configuração a seguir usando `SparkConf` no script. Essas configurações ajudam o Apache Spark a lidar corretamente com as tabelas do Iceberg.

  ```
  spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions 
  --conf spark.sql.catalog.glue_catalog=org.apache.iceberg.spark.SparkCatalog 
  --conf spark.sql.catalog.glue_catalog.warehouse=s3://<your-warehouse-dir>/ 
  --conf spark.sql.catalog.glue_catalog.catalog-impl=org.apache.iceberg.aws.glue.GlueCatalog 
  --conf spark.sql.catalog.glue_catalog.io-impl=org.apache.iceberg.aws.s3.S3FileIO
  ```

  Se você estiver lendo ou gravando em tabelas do Iceberg registradas no Lake Formation, siga as orientações em [Usar o AWS Glue com AWS Lake Formation para controle de acesso refinado](security-lf-enable.md) no AWS Glue 5.0 e versões posteriores. No AWS Glue 4.0, adicione a configuração a seguir para habilitar o suporte ao Lake Formation.

  ```
  --conf spark.sql.catalog.glue_catalog.glue.lakeformation-enabled=true
  --conf spark.sql.catalog.glue_catalog.glue.id=<table-catalog-id>
  ```

  Se você usar o AWS Glue 3.0 com o Iceberg 0.13.1, deverá definir as seguintes configurações adicionais para usar o gerenciador de bloqueios do Amazon DynamoDB para garantir a transação atômica. AWS O Glue 4.0 usa o bloqueio positivo por padrão. Para obter mais informações, consulte [Iceberg AWS Integrations](https://iceberg.apache.org/docs/latest/aws/#dynamodb-lock-manager) na documentação oficial do Apache Iceberg.

  ```
  --conf spark.sql.catalog.glue_catalog.lock-impl=org.apache.iceberg.aws.glue.DynamoLockManager 
  --conf spark.sql.catalog.glue_catalog.lock.table=<your-dynamodb-table-name>
  ```

**Usar uma versão diferente do Iceberg**

Para usar uma versão do Iceberg que não é compatível com o AWS Glue, especifique seus próprios arquivos JAR do Iceberg usando o parâmetro de trabalho `--extra-jars`. Não inclua `iceberg` como um valor para o parâmetro `--datalake-formats`. Se você usa o AWS Glue 5.0 ou versões superiores, é necessário definir o parâmetro `--user-jars-first true` do trabalho.

**Habilitar criptografia para tabelas do Iceberg**

**nota**  
As tabelas do Iceberg têm seus próprios mecanismos para habilitar a criptografia no lado do servidor. Você deve habilitar essa configuração além da configuração de segurança do AWS Glue.

Para habilitar a criptografia do lado do servidor nas tabelas do Iceberg, consulte as orientações na [documentação do Iceberg.](https://iceberg.apache.org/docs/latest/aws/#s3-server-side-encryption)

**Adicionar configuração do Spark para acesso entre regiões do Iceberg**

Para adicionar uma configuração adicional do Spark para acesso à tabela entre regiões do Iceberg com o Catálogo de Dados do AWS Glue e o AWS Lake Formation, siga as etapas abaixo:

1. Crie um [ponto de acesso multirregional](https://docs.aws.amazon.com/AmazonS3/latest/userguide/multi-region-access-point-create-examples.html).

1. Defina as seguintes propriedades do Spark:

   ```
   -----
       --conf spark.sql.catalog.my_catalog.s3.use-arn-region-enabled=true \
       --conf spark.sql.catalog.{CATALOG}.s3.access-points.bucket1", "arn:aws:s3::<account-id>:accesspoint/<mrap-id>.mrap \
       --conf spark.sql.catalog.{CATALOG}.s3.access-points.bucket2", "arn:aws:s3::<account-id>:accesspoint/<mrap-id>.mrap
   -----
   ```

## Exemplo: escrever uma tabela do Iceberg no Amazon S3 e registrá-la no AWS Glue Data Catalog
<a name="aws-glue-programming-etl-format-iceberg-write"></a>

Esse exemplo de script demonstra como escrever uma tabela Iceberg no Amazon S3. O exemplo usa aso [integrações da AWS no Iceberg](https://iceberg.apache.org/docs/latest/aws/) para registrar a tabela no AWS Glue Data Catalog.

------
#### [ Python ]

```
# Example: Create an Iceberg table from a DataFrame 
# and register the table to Glue Data Catalog

dataFrame.createOrReplaceTempView("tmp_<your_table_name>")

query = f"""
CREATE TABLE glue_catalog.<your_database_name>.<your_table_name>
USING iceberg
TBLPROPERTIES ("format-version"="2")
AS SELECT * FROM tmp_<your_table_name>
"""
spark.sql(query)
```

------
#### [ Scala ]

```
// Example: Example: Create an Iceberg table from a DataFrame
// and register the table to Glue Data Catalog

dataFrame.createOrReplaceTempView("tmp_<your_table_name>")

val query = """CREATE TABLE glue_catalog.<your_database_name>.<your_table_name>
USING iceberg
TBLPROPERTIES ("format-version"="2")
AS SELECT * FROM tmp_<your_table_name>
"""
spark.sql(query)
```

------

Como alternativa, é possível escrever uma tabela do Iceberg no Amazon S3 e no catálogo de dados usando os métodos do Spark.

Pré-requisitos: você precisará provisionar um catálogo para uso da biblioteca do Iceberg. Ao usar o catálogo de dados do AWS Glue, o AWS Glue simplifica essa operação. O catálogo de dados do AWS Glue é pré-configurado para ser usado pelas bibliotecas do Spark como `glue_catalog`. As tabelas do catálogo de dados são identificadas por um*databaseName* e um *tableName*. Para obter mais informações sobre o catálogo de dados do AWS Glue, consulte [Descoberta e catalogação de dados no AWS Glue](catalog-and-crawler.md).

Se você não estiver usando o catálogo de dados do AWS Glue, precisará provisionar um catálogo por meio das APIs do Spark. Para obter mais informações, consulte [Configuração do Spark](https://iceberg.apache.org/docs/latest/spark-configuration/) na documentação do Iceberg.

Este exemplo grava uma tabela Iceberg no Amazon S3 e no Data Catalog usando Spark.

------
#### [ Python ]

```
# Example: Write an Iceberg table to S3 on the Glue Data Catalog

# Create (equivalent to CREATE TABLE AS SELECT)
dataFrame.writeTo("glue_catalog.databaseName.tableName") \
    .tableProperty("format-version", "2") \
    .create()

# Append (equivalent to INSERT INTO)
dataFrame.writeTo("glue_catalog.databaseName.tableName") \
    .tableProperty("format-version", "2") \
    .append()
```

------
#### [ Scala ]

```
// Example: Write an Iceberg table to S3 on the Glue Data Catalog

// Create (equivalent to CREATE TABLE AS SELECT)
dataFrame.writeTo("glue_catalog.databaseName.tableName")
    .tableProperty("format-version", "2")
    .create()

// Append (equivalent to INSERT INTO)
dataFrame.writeTo("glue_catalog.databaseName.tableName")
    .tableProperty("format-version", "2")
    .append()
```

------

## Exemplo: ler uma tabela do Iceberg do Amazon S3 usando o AWS Glue Data Catalog
<a name="aws-glue-programming-etl-format-iceberg-read"></a>

Este exemplo lê a tabela do Iceberg que você criou em [Exemplo: escrever uma tabela do Iceberg no Amazon S3 e registrá-la no AWS Glue Data Catalog](#aws-glue-programming-etl-format-iceberg-write).

------
#### [ Python ]

Para este exemplo, use o método `GlueContext.create\$1data\$1frame.from\$1catalog()`.

```
# Example: Read an Iceberg table from Glue Data Catalog

from awsglue.context import GlueContext
from pyspark.context import SparkContext

sc = SparkContext()
glueContext = GlueContext(sc)

df = glueContext.create_data_frame.from_catalog(
    database="<your_database_name>",
    table_name="<your_table_name>",
    additional_options=additional_options
)
```

------
#### [ Scala ]

Neste exemplo, use o método [getCatalogSource](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getCatalogSource).

```
// Example: Read an Iceberg table from Glue Data Catalog

import com.amazonaws.services.glue.GlueContext
import org.apacke.spark.SparkContext

object GlueApp {
  def main(sysArgs: Array[String]): Unit = {
    val spark: SparkContext = new SparkContext()
    val glueContext: GlueContext = new GlueContext(spark)
    val df = glueContext.getCatalogSource("<your_database_name>", "<your_table_name>",
      additionalOptions = additionalOptions)
      .getDataFrame()
  }
}
```

------

## Exemplo: inserir um `DataFrame` em um tabela do Iceberg no Amazon S3 usando o AWS Glue Data Catalog
<a name="aws-glue-programming-etl-format-iceberg-insert"></a>

Este exemplo insere dados na tabela do Iceberg que você criou em [Exemplo: escrever uma tabela do Iceberg no Amazon S3 e registrá-la no AWS Glue Data Catalog](#aws-glue-programming-etl-format-iceberg-write).

**nota**  
Este exemplo exige que você defina o parâmetro de trabalho `--enable-glue-datacatalog` para usar o AWS Glue Data Catalog como metastore do Apache Spark Hive. Para saber mais, consulte [Usar parâmetros de tarefa em tarefas do AWS Glue](aws-glue-programming-etl-glue-arguments.md).

------
#### [ Python ]

Para este exemplo, use o método `GlueContext.write\$1data\$1frame.from\$1catalog()`.

```
# Example: Insert into an Iceberg table from Glue Data Catalog

from awsglue.context import GlueContext
from pyspark.context import SparkContext

sc = SparkContext()
glueContext = GlueContext(sc)

glueContext.write_data_frame.from_catalog(
    frame=dataFrame,
    database="<your_database_name>",
    table_name="<your_table_name>",
    additional_options=additional_options
)
```

------
#### [ Scala ]

Neste exemplo, use o método [getCatalogSink](glue-etl-scala-apis-glue-gluecontext.md#glue-etl-scala-apis-glue-gluecontext-defs-getCatalogSink).

```
// Example: Insert into an Iceberg table from Glue Data Catalog

import com.amazonaws.services.glue.GlueContext
import org.apacke.spark.SparkContext

object GlueApp {
  def main(sysArgs: Array[String]): Unit = {
    val spark: SparkContext = new SparkContext()
    val glueContext: GlueContext = new GlueContext(spark)
    glueContext.getCatalogSink("<your_database_name>", "<your_table_name>",
      additionalOptions = additionalOptions)
      .writeDataFrame(dataFrame, glueContext)
  }
}
```

------

## Exemplo: ler uma tabela do Iceberg do Amazon S3 usando o Spark
<a name="aws-glue-programming-etl-format-iceberg-read-spark"></a>

Pré-requisitos: você precisará provisionar um catálogo para uso da biblioteca do Iceberg. Ao usar o catálogo de dados do AWS Glue, o AWS Glue simplifica essa operação. O catálogo de dados do AWS Glue é pré-configurado para ser usado pelas bibliotecas do Spark como `glue_catalog`. As tabelas do catálogo de dados são identificadas por um*databaseName* e um *tableName*. Para obter mais informações sobre o catálogo de dados do AWS Glue, consulte [Descoberta e catalogação de dados no AWS Glue](catalog-and-crawler.md).

Se você não estiver usando o catálogo de dados do AWS Glue, precisará provisionar um catálogo por meio das APIs do Spark. Para obter mais informações, consulte [Configuração do Spark](https://iceberg.apache.org/docs/latest/spark-configuration/) na documentação do Iceberg.

Este exemplo lê uma tabela do Iceberg no Amazon S3 do catálogo de dados usando o Spark.

------
#### [ Python ]

```
# Example: Read an Iceberg table on S3 as a DataFrame from the Glue Data Catalog

dataFrame = spark.read.format("iceberg").load("glue_catalog.databaseName.tableName")
```

------
#### [ Scala ]

```
// Example: Read an Iceberg table on S3 as a DataFrame from the Glue Data Catalog

val dataFrame = spark.read.format("iceberg").load("glue_catalog.databaseName.tableName")
```

------

## Exemplo: ler e escrever na tabela do Iceberg com o controle de permissão do Lake Formation
<a name="aws-glue-programming-etl-format-iceberg-read-write-lake-formation-tables"></a>

Este exemplo lê e escreve uma tabela do Iceberg com o controle de permissão do Lake Formation.

**nota**  
Este exemplo funciona apenas no AWS Glue 4.0. No AWS Glue 5.0 e versões posteriores, siga as orientações em [Usar o AWS Glue com AWS Lake Formation para controle de acesso refinado](security-lf-enable.md).

1. Crie uma tabela do Iceberg e registrá-la no Lake Formation:

   1. Para habilitar o controle de permissão do Lake Formation, primeiro será necessário registrar o caminho da tabela do Amazon S3 no Lake Formation. Para obter mais informações, consulte [Registering an Amazon S3 location](https://docs.aws.amazon.com/lake-formation/latest/dg/register-location.html) (Registrar um local do Amazon S3). É possível registrá-lo no console do Lake Formation ou usando a AWS CLI:

      ```
      aws lakeformation register-resource --resource-arn arn:aws:s3:::<s3-bucket>/<s3-folder> --use-service-linked-role --region <REGION>
      ```

      Depois de registrar uma localização no Amazon S3, qualquer tabela do AWS Glue apontando para a localização (ou qualquer uma de suas localizações secundárias) retornará o valor do parâmetro `IsRegisteredWithLakeFormation` como verdadeiro na chamada `GetTable`.

   1. Crie uma tabela do Iceberg que aponte para o caminho registrado por meio do Spark:
**nota**  
Os exemplos a seguir foram criados em Python.

      ```
      dataFrame.createOrReplaceTempView("tmp_<your_table_name>")
      
      query = f"""
      CREATE TABLE glue_catalog.<your_database_name>.<your_table_name>
      USING iceberg
      AS SELECT * FROM tmp_<your_table_name>
      """
      spark.sql(query)
      ```

      Você também pode criar a tabela manualmente por meio da API `CreateTable` do AWS Glue. Para obter mais informações, consulte [Criar tabelas do Apache Iceberg](https://docs.aws.amazon.com/lake-formation/latest/dg/creating-iceberg-tables.html).
**nota**  
No momento, a API `UpdateTable` não oferece suporte ao formato de tabela do Iceberg como entrada para a operação.

1. Conceda permissão do Lake Formation para o perfil do IAM do trabalho. É possível conceder permissões no console do Lake Formation ou usando a AWS CLI. Para obter mais informações, consulte: https://docs.aws.amazon.com/lake-formation/latest/dg/granting-table-permissions.html

1. Leia uma tabela do Iceberg registrada no Lake Formation. O código é o mesmo que o da leitura de uma tabela do Iceberg não registrada. Observe que o perfil do IAM do trabalho do AWS Glue precisa ter a permissão SELECT para que a leitura seja bem-sucedida.

   ```
   # Example: Read an Iceberg table from the AWS Glue Data Catalog
   from awsglue.context import GlueContextfrom pyspark.context import SparkContext
   
   sc = SparkContext()
   glueContext = GlueContext(sc)
   
   df = glueContext.create_data_frame.from_catalog(
       database="<your_database_name>",
       table_name="<your_table_name>",
       additional_options=additional_options
   )
   ```

1. Escreva em uma tabela do Iceberg registrada no Lake Formation. O código é o mesmo que o da escrita em uma tabela do Iceberg não registrada. Observe que o perfil do IAM do trabalho do AWS Glue precisa ter a permissão SUPER para que a escrita seja bem-sucedida.

   ```
   glueContext.write_data_frame.from_catalog(
       frame=dataFrame,
       database="<your_database_name>",
       table_name="<your_table_name>",
       additional_options=additional_options
   )
   ```