本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Iceberg 中繼資料管理
<a name="feature-store-iceberg-metadata-management"></a>

當您使用 Iceberg 資料表格式建立功能群組時，Amazon SageMaker Feature Store 會使用預設組態值代表您建立和管理基礎 Iceberg 資料表。您可以在特徵群組建立時設定 Iceberg 資料表屬性、更新現有特徵群組上的屬性，以及檢視目前在資料表上設定的屬性。這些設定可讓您控制組態參數，例如快照保留、中繼資料檔案管理和寫入行為，以管理離線儲存資料表的整體大小和效能。

只有一部分的 Iceberg 資料表屬性已驗證與特徵商店的相容性。設定此支援集以外的屬性並不保證行為正確。如需支援屬性的完整清單，請參閱 [允許 Iceberg 屬性](#feature-store-iceberg-allowed-properties)。

**先決條件：**您的功能群組必須使用 Iceberg 資料表格式具有離線存放區。

**重要**  
如果變更不允許的 Iceberg 屬性，特徵商店無法保證持續相容性，並可能導致無法寫入離線存放區。

## IcebergProperties 類型
<a name="feature-store-iceberg-properties-type"></a>

`IcebergProperties` 類型為 Iceberg 屬性組態提供經過驗證的包裝函式，確保所有金鑰都屬於允許的集合，並防止重複的項目。

```
class IcebergProperties(Base):
    """Configuration for Iceberg table properties in a Feature Group offline store."""
    properties: Optional[Dict[str, str]] = None
```

### 驗證屬性
<a name="feature-store-iceberg-validating-properties"></a>

當傳遞給建立或更新函數時，無效和重複的金鑰會導致錯誤。您可以選擇性地使用 `validate_property_keys()`方法驗證金鑰。這在從現有`IcebergProperties`物件新增或移除屬性時很有用。

```
iceberg_properties = IcebergProperties(  # Validates on creation
    properties={
        "write.target-file-size-bytes": "268435456",
        "write.delete.mode": "merge-on-read",
    }
)

# Add non-allowed property
iceberg_properties.properties.update({"write.delete.isolation-level": "Snapshot"})

# Validate again — throws error because of non-allowed property
iceberg_properties.validate_property_keys()
```

## 建立具有 Iceberg 屬性的功能群組
<a name="feature-store-iceberg-create"></a>

`FeatureGroupManager.create` 函數接受 類型的 `iceberg_properties` 參數`IcebergProperties`。它會建立特徵群組，並等待建立完成，然後再更新基礎 AWS Glue 資料表上的 Iceberg 屬性。

或者，您可以建立 `FeatureGroup`、呼叫 `create`，然後將特徵群組物件傳遞至 `FeatureGroupManager`類別，並在特徵群組完成建立時呼叫 `update`以避免封鎖。

```
fg = FeatureGroupManager.create(
    # ...other parameters...
    offline_store_config=OfflineStoreConfig(
        s3_storage_config=S3StorageConfig(s3_uri="s3://my-bucket/features/"),
        table_format="Iceberg",  # Must use Iceberg table format
    ),
    iceberg_properties=IcebergProperties(
        properties={
            "write.target-file-size-bytes": "536870912",
            "history.expire.min-snapshots-to-keep": "3",
        }
    ),
)
```

## 更新現有功能群組上的 Iceberg 屬性
<a name="feature-store-iceberg-update"></a>

`update` 函數接受 類型的 `iceberg_properties` 參數`IcebergProperties`。它需要已建立的功能群組、擷取離線存放 AWS Glue Data Catalog 區的 ，並設定指定的 Iceberg 屬性。

```
fg = FeatureGroupManager.get(feature_group_name="my-feature-group")
fg.update(
    iceberg_properties=IcebergProperties(
        properties={
            "write.target-file-size-bytes": "268435456",
            "write.delete.mode": "merge-on-read",
        }
    ),
)
```

## 檢視特徵群組上的 Iceberg 屬性
<a name="feature-store-iceberg-get"></a>

`FeatureGroupManager.get` 函數接受 `include_iceberg_properties` 參數。當設定為 時`True`，它會擷取已手動設定且為允許清單一部分的 Iceberg 屬性，並將其新增至傳回物件中的 `iceberg_properties` 欄位。

這只會傳回屬於允許清單一部分的集合屬性。若要取得所有 AWS Glue 資料表屬性，請直接使用 AWS Glue API。如果允許的 Iceberg 屬性未顯示，表示尚未明確設定並使用其預設值。

```
fg = FeatureGroupManager.get(
    feature_group_name="my-feature-group",
    include_iceberg_properties=True,
)
print(fg.iceberg_properties.properties)
# e.g. {"write.target-file-size-bytes": "536870912"}
```

## 所需的許可
<a name="feature-store-iceberg-permissions"></a>

確保 [AmazonSageMakerFeatureStoreAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonSageMakerFeatureStoreAccess.html) 和 [AmazonSageMakerFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonSageMakerFullAccess.html) 受管政策都連接到您正在使用的 IAM 角色。根據您的存取模式管理您的政策。

## 允許 Iceberg 屬性
<a name="feature-store-iceberg-allowed-properties"></a>

下表列出已驗證可搭配 Feature Store 使用的 Iceberg 資料表屬性。如需這些屬性的詳細資訊，請參閱 Apache Iceberg 文件中的[資料表組態](https://iceberg.apache.org/docs/latest/configuration/)。


**允許 Iceberg 資料表屬性**  

| 屬性 | 預設值 | 說明 | 
| --- | --- | --- | 
| write.metadata.delete-after-commit.enabled | false | 控制是否要在每個資料表遞交之後刪除最舊的追蹤版本中繼資料檔案。 | 
| write.metadata.previous-versions-max | 100 | 要追蹤的先前版本中繼資料檔案數目上限。 | 
| history.expire.max-snapshot-age-ms | 432000000 (5 天） | 快照的預設最長存留期，以在快照過期時保留在資料表及其所有分支上。 | 
| history.expire.min-snapshots-to-keep | 1 | 過期快照時，要保留在資料表及其所有分支上的預設快照數目下限。 | 
| history.expire.max-ref-age-ms | Long.MAX\_VALUE （永遠） | 對於 main分支以外的快照參考，預設快照參考的最長存留期，以在到期快照時保留。main 分支永遠不會過期。 | 
| write.target-file-size-bytes | 536870912 (512 MB) | 控制產生的檔案大小，以將此位元組設為目標。 | 
| write.delete.target-file-size-bytes | 67108864 (64 MB) | 控制產生的刪除檔案大小，以針對此許多位元組。 | 
| write.delete.mode | copy-on-write | 用於刪除命令的模式： copy-on-write或 merge-on-read(v2 及更高版本）。 | 
| write.update.mode | copy-on-write | 用於更新命令的模式： copy-on-write或 merge-on-read(v2 及更高版本）。 | 
| write.delete.granularity | partition | 控制產生的刪除檔案的精細程度： partition或 file。 | 
| write.parquet.row-group-size-bytes | 134217728 (128 MB) | Parquet 資料列群組大小。 | 
| read.split.target-size | 134217728 (128 MB) | 合併資料輸入分割時的目標大小。 | 
| read.split.metadata-target-size | 33554432 (32 MB) | 合併中繼資料輸入分割時的目標大小。 | 
| read.split.open-file-cost | 4194304 (4 MB) | 開啟檔案的預估成本，做為合併分割時的最小權重。 |