[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC):2025-08-28。"],[],[],null,["# Use BigLake metastore with the Iceberg REST catalog\n===================================================\n\n|\n| **Preview**\n|\n|\n| This 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 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| **Note:** To request feedback or support for this feature, send an email to [biglake-help@google.com](mailto:biglake-help@google.com).\n\nThe managed Apache Iceberg REST catalog in BigLake metastore creates\ninteroperability between all your query engines by offering a single source of\ntruth for all your Iceberg data. It lets query engines,\nsuch as Apache Spark, discover, read metadata from, and manage\nIceberg tables in a consistent way.\n\nThe Iceberg tables that you use with the\nIceberg REST catalog are called\nBigLake tables for Apache Iceberg (preview). These are Iceberg\ntables that you create from open source engines and store in Cloud Storage.\nThey can be read by open source engines or BigQuery. Writes are only\nsupported from open source engines. In this document, we refer to these tables\nas BigLake Iceberg tables.\n\nBefore you begin\n----------------\n\n1.\n [Verify that billing is enabled for your Google Cloud project](/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project).\n\n Learn how to [check if billing is enabled on a project](/billing/docs/how-to/verify-billing-enabled).\n2.\n\n\n Enable the BigLake API.\n\n\n [Enable the API](https://console.cloud.google.com/flows/enableapi?apiid=biglake.googleapis.com)\n3. Optional: Understand [how BigLake metastore works](/bigquery/docs/about-blms) and why you should use it.\n\n### Required roles\n\n\nTo get the permissions that\nyou need to use the Iceberg REST catalog in BigLake metastore,\n\nask your administrator to grant you the\nfollowing IAM roles on your project or service account:\n\n- [BigLake Admin](/iam/docs/roles-permissions/biglake#biglake.admin) (`roles/biglake.admin`)\n- [Storage Admin](/iam/docs/roles-permissions/storage#storage.admin) (`roles/storage.admin`)\n\n\nFor more information about granting roles, see [Manage access to projects, folders, and organizations](/iam/docs/granting-changing-revoking-access).\n\n\nYou might also be able to get\nthe required permissions through [custom\nroles](/iam/docs/creating-custom-roles) or other [predefined\nroles](/iam/docs/roles-overview#predefined).\n\nLimitations\n-----------\n\nThe Iceberg REST catalog is subject to the following\nlimitations:\n\n- [Multi-region buckets](/storage/docs/locations#location-mr), [dual-region buckets](/storage/docs/locations#location-dr), and buckets with custom region placement aren't supported.\n\nConfigure a query engine with the Iceberg REST catalog\n------------------------------------------------------\n\n```python\nimport pyspark\nfrom pyspark.context import SparkContext\nfrom pyspark.sql import SparkSession\n\ncatalog_name = \"\u003cvar translate=\"no\"\u003eCATALOG_NAME\u003c/var\u003e\"\nspark = SparkSession.builder.appName(\"\u003cvar translate=\"no\"\u003eAPP_NAME\u003c/var\u003e\") \\\n .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \\\n .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \\\n .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1beta/restcatalog') \\\n .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://\u003cvar translate=\"no\"\u003eSTORAGE_URI\u003c/var\u003e') \\\n .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', '\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e') \\\n .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \\\n .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.hadoop.HadoopFileIO') \\\n .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \\\n .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \\\n .getOrCreate()\n```\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eCATALOG_NAME\u003c/var\u003e: a name for your Iceberg REST catalog.\n- \u003cvar translate=\"no\"\u003eAPP_NAME\u003c/var\u003e: a name for your Spark session.\n- \u003cvar translate=\"no\"\u003eSTORAGE_URI\u003c/var\u003e: the URI of the Cloud Storage bucket that contains your BigLake Iceberg tables.\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: the project that is billed for using the Iceberg REST catalog, which might be different from the project that owns the Cloud Storage bucket. For details about project configuration when using a REST API, see [System parameters](/apis/docs/system-parameters).\n\nCreate a namespace\n------------------\n\n```python\nspark.sql(\"CREATE NAMESPACE IF NOT EXISTS \u003cvar translate=\"no\"\u003eNAMESPACE_NAME\u003c/var\u003e;\")\n\nspark.sql(\"USE \u003cvar translate=\"no\"\u003eNAMESPACE_NAME\u003c/var\u003e;\")\n```\n\nReplace \u003cvar translate=\"no\"\u003eNAMESPACE_NAME\u003c/var\u003e with a name for your namespace.\n\nCreate a table\n--------------\n\n```python\nspark.sql(\"CREATE TABLE \u003cvar translate=\"no\"\u003eTABLE_NAME\u003c/var\u003e (id int, data string) USING ICEBERG;\")\n\nspark.sql(\"DESCRIBE \u003cvar translate=\"no\"\u003eNAMESPACE_NAME\u003c/var\u003e.\u003cvar translate=\"no\"\u003eTABLE_NAME\u003c/var\u003e\").show()\n```\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eNAMESPACE_NAME\u003c/var\u003e: the name of your namespace\n- \u003cvar translate=\"no\"\u003eTABLE_NAME\u003c/var\u003e: a name for your table\n\nList tables\n-----------\n\n```python\nspark.sql(\"SHOW TABLES\").show()\n```\n\nInsert data into the table\n--------------------------\n\nThe following example inserts sample data into the table: \n\n```python\nspark.sql(\"INSERT INTO \u003cvar translate=\"no\"\u003eTABLE_NAME\u003c/var\u003e VALUES (1, \\\"first row\\\"), (2, \\\"second row\\\"), (3, \\\"third row\\\");\")\n```\n\nQuery a table\n-------------\n\nThe following example selects all data from the table: \n\n```python\nspark.sql(\"SELECT * FROM \u003cvar translate=\"no\"\u003eTABLE_NAME\u003c/var\u003e;\").show()\n```\n\nThe following example queries the same table from BigQuery: \n\n```googlesql\nSELECT * FROM `\u003cvar translate=\"no\"\u003eCLOUD_STORAGE_BUCKET_NAME\u003c/var\u003e\u003e\u003cvar translate=\"no\"\u003eNAMESPACE_NAME\u003c/var\u003e.\u003cvar translate=\"no\"\u003eTABLE_NAME\u003c/var\u003e`;\n```\n\nReplace \u003cvar translate=\"no\"\u003eCLOUD_STORAGE_BUCKET_NAME\u003c/var\u003e with the name of the\nCloud Storage bucket for your Iceberg REST\ncatalog. For example, if your URI is `gs://iceberg_bucket`, use\n`iceberg_bucket`.\n\nAlter a table schema\n--------------------\n\nThe following example adds a column to the table: \n\n```python\nspark.sql(\"ALTER TABLE \u003cvar translate=\"no\"\u003eTABLE_NAME\u003c/var\u003e ADD COLUMNS ( desc string);\")\nspark.sql(\"DESCRIBE \u003cvar translate=\"no\"\u003eNAMESPACE_NAME\u003c/var\u003e.\u003cvar translate=\"no\"\u003eTABLE_NAME\u003c/var\u003e\").show()\n```\n\nDelete a table\n--------------\n\nThe following example deletes the table from the given namespace: \n\n```python\nspark.sql(\"DROP TABLE \u003cvar translate=\"no\"\u003eTABLE_NAME\u003c/var\u003e;\")\n```\n\nPricing\n-------\n\nFor pricing details, see [BigLake pricing](/biglake#pricing).\n\nWhat's next\n-----------\n\n- Learn more about [managing Iceberg resources with BigLake metastore](/bigquery/docs/blms-manage-resources).\n- Learn about [additional BigLake metastore features](/bigquery/docs/blms-features)."]]