Unity Catalog でテーブルを作成するCreate tables in Unity Catalog

この記事では、Unity Catalogのマネージドテーブルおよび外部テーブルの概念と、Unity Catalogでテーブルを作成する方法について説明します。

テーブルを作成するときは、必ず Unity Catalog によって管理されるカタログを参照するか、デフォルト カタログを Unity Catalog によって管理される カタログ に設定してください。 「デフォルト カタログの管理」を参照してください。

カタログ hive_metastore はカタログ エクスプローラーに表示されますが、Unity Catalog によって管理されているとは見なされません。 これは、Databricks ワークスペースの Hive metastoreによって管理されます。 一覧表示されている他のすべてのカタログは、Unity Catalog によって管理されます。

Unity Catalogテーブルアップグレードインターフェイスを使用して、Hive metastoreに登録されている既存のテーブルをUnity Catalogにアップグレードできます。「テーブルとビューをUnity Catalogにアップグレード」を参照してください。

マネージドテーブル

マネージドテーブルは、Unity Catalogでテーブルを作成する既定の方法です。Unity Catalogは、これらのテーブルのライフサイクルとファイルレイアウトを管理します。Databricks外部でツールを使用してこれらのテーブル内のファイルを直接操作しないでください。

マネージド テーブルは、スキーマとカタログの構成方法に応じて、メタストア、カタログ、またはスキーマ レベルで マネージド ストレージに格納されます。 「 Unity Catalog で管理対象ストレージの場所を指定する」を参照してください。

マネージドテーブルでは常にDeltaテーブル形式が使用されます。

マネージドテーブルが削除されると、その基になるデータは30日以内にクラウドテナントから削除されます。

外部テーブル

外部テーブルは、メタストア、カタログ、またはスキーマに指定された管理ストレージの場所の外部にデータが格納されているテーブルです。外部テーブルは、DatabricksクラスターまたはDatabricks SQLウェアハウスの外部にあるデータに直接アクセスする必要がある場合にのみ使用してください。

外部テーブルでDROP TABLEを実行しても、Unity Catalogは基になるデータを削除しません。テーブルを削除するには、その所有者である必要があります。外部テーブルに対する権限を管理し、マネージドテーブルと同じ方法でクエリで使用できます。SQLを使用して外部テーブルを作成するには、CREATE TABLEステートメントでLOCATIONパスを指定します。外部テーブルでは、次のファイル形式を使用できます。

  • DELTA

  • CSV

  • JSON

  • AVRO

  • PARQUET

  • ORC

  • TEXT

外部テーブルの基になるクラウドストレージへのアクセスを管理するには、ストレージ資格情報と外部ロケーションを設定する必要があります。

詳細については、「外部テーブルの作成」を参照してください。

要件

表を作成するスキーマに対するCREATE TABLE権限、およびスキーマに対するUSE SCHEMA権限、および親カタログに対する USE CATALOG権限が必要です。

外部テーブルを作成する場合は、「外部テーブルの作成」を参照してその他の要件を確認してください。

マネージドテーブルの作成

マネージドテーブルを作成するには、次のSQLコマンドを実行します。サンプルノートブックを使用してテーブルを作成することもできます。括弧内の項目はオプションです。プレースホルダーの値を置き換えます。

  • <catalog-name>: テーブルを含むカタログの名前。

    これは、Databricks ワークスペースに関連付けられている Hive metastore に対して自動的に作成されるhive_metastoreカタログにすることはできません。 ワークスペースのデフォルト カタログにテーブルを作成する場合は、 カタログ名を削除できます。

  • <schema-name>: テーブルを含むスキーマの名前。

  • <table-name>:テーブルの名前。

  • <column-specification>:各列の名前とデータ型。

CREATE TABLE <catalog-name>.<schema-name>.<table-name>
(
  <column-specification>
);
spark.sql("CREATE TABLE <catalog-name>.<schema-name>.<table-name> "
  "("
  "  <column-specification>"
  ")")
library(SparkR)

sql(paste("CREATE TABLE <catalog-name>.<schema-name>.<table-name> ",
  "(",
  "  <column-specification>",
  ")",
  sep = ""))
spark.sql("CREATE TABLE <catalog-name>.<schema-name>.<table-name> " +
  "(" +
  "  <column-specification>" +
  ")")

Databricks Terraformプロバイダーdatabricks_tableを使用して、マネージドテーブルを作成することもできます。databricks_tablesを使用して、テーブルの完全な名前の一覧を取得できます。

たとえば、テーブルmain.default.departmentを作成し、そこに5つの行を挿入するには、次のようにします。

CREATE TABLE main.default.department
(
  deptcode  INT,
  deptname  STRING,
  location  STRING
);

INSERT INTO main.default.department VALUES
  (10, 'FINANCE', 'EDINBURGH'),
  (20, 'SOFTWARE', 'PADDINGTON'),
  (30, 'SALES', 'MAIDSTONE'),
  (40, 'MARKETING', 'DARLINGTON'),
  (50, 'ADMIN', 'BIRMINGHAM');
spark.sql("CREATE TABLE main.default.department "
  "("
  "  deptcode  INT,"
  "  deptname  STRING,"
  "  location  STRING"
  ")"
  "INSERT INTO main.default.department VALUES "
  "  (10, 'FINANCE', 'EDINBURGH'),"
  "  (20, 'SOFTWARE', 'PADDINGTON'),"
  "  (30, 'SALES', 'MAIDSTONE'),"
  "  (40, 'MARKETING', 'DARLINGTON'),"
  "  (50, 'ADMIN', 'BIRMINGHAM')")
library(SparkR)

sql(paste("CREATE TABLE main.default.department ",
  "(",
  "  deptcode  INT,",
  "  deptname  STRING,",
  "  location  STRING",
  ")",
  "INSERT INTO main.default.department VALUES ",
  "  (10, 'FINANCE', 'EDINBURGH'),",
  "  (20, 'SOFTWARE', 'PADDINGTON'),",
  "  (30, 'SALES', 'MAIDSTONE'),",
  "  (40, 'MARKETING', 'DARLINGTON'),",
  "  (50, 'ADMIN', 'BIRMINGHAM')",
  sep = ""))
spark.sql("CREATE TABLE main.default.department " +
  "(" +
  "  deptcode  INT," +
  "  deptname  STRING," +
  "  location  STRING" +
  ")" +
  "INSERT INTO main.default.department VALUES " +
  "  (10, 'FINANCE', 'EDINBURGH')," +
  "  (20, 'SOFTWARE', 'PADDINGTON')," +
  "  (30, 'SALES', 'MAIDSTONE')," +
  "  (40, 'MARKETING', 'DARLINGTON')," +
  "  (50, 'ADMIN', 'BIRMINGHAM')")

ノートブックの例: マネージド テーブル を作成する

次のノートブックの例を使用して、カタログ、スキーマ、マネージドテーブルを作成し、それらに対する権限を管理できます。

Python ノートブック を使用して Unity Catalog でテーブルを作成および管理する

ノートブックを新しいタブで開く

SQL ノートブック を使用して Unity Catalog でテーブルを作成および管理する

ノートブックを新しいタブで開く

マネージドテーブルの削除

テーブルを削除するには、テーブルの所有者である必要があります。マネージドテーブルを削除するには、次のSQLコマンドを実行します。

DROP TABLE IF EXISTS catalog_name.schema_name.table_name;

マネージドテーブルが削除されると、その基になるデータは30日以内にクラウドテナントから削除されます。

外部テーブルの作成

外部テーブルのデータは、クラウドテナントのパスに格納されます。外部テーブルを操作するため、Unity Catalogには外部クラウドストレージにアクセスして操作するための2つのオブジェクトが導入されています。

  • ストレージ資格情報には、クラウドストレージの場所にアクセスするための認証方法が含まれています。ストレージ資格情報には、アクセスを許可するパスへのマッピングは含まれていません。ストレージ資格情報はアクセス制御されており、資格情報を使用できるユーザーを決定します。

  • 外部ロケーションは、ストレージ資格情報を、アクセスを許可するクラウドストレージパスにマップします。外部ロケーションは、そのクラウドストレージパスとそのコンテンツへのアクセスのみを許可します。外部ロケーションはアクセス制御されており、使用できるユーザーを決定します。外部ロケーションは、SQLコマンドにLOCATION句が含まれている場合に自動的に使用されます。

要件

外部テーブルを作成するには、次が必要です。

  • 外部テーブルがアクセスする LOCATION へのアクセスを許可する外部ロケーションに対する CREATE EXTERNAL TABLE 特権。

  • テーブルの親スキーマに対するUSE SCHEMA権限。

  • テーブルの親カタログに対するUSE CATALOG権限。

  • テーブルの親スキーマに対するCREATE TABLE権限。

外部ロケーションとストレージの資格情報は、カタログではなくメタストア レベルで格納されます。 ストレージ資格情報を作成するには、アカウント管理者であるか、 CREATE STORAGE CREDENTIAL 権限を持っている必要があります。 外部ロケーションを作成するには、メタストア管理者であるか、 CREATE EXTERNAL LOCATION 権限を持っている必要があります。 「 Unity Catalog を使用したクラウド オブジェクト ストレージへの接続」を参照してください。

テーブルの作成

ノートブックまたはSQLクエリエディタで次のいずれかのコマンド例を使用して、外部テーブルを作成します。

また、サンプルノートブックを使用して、ストレージ資格情報、外部ロケーション、外部テーブルを作成し、それらの権限を管理することもできます。

次の例で、プレースホルダーの値を置き換えます。

  • <catalog>:テーブルを格納するカタログの名前。

    これは、Databricks ワークスペースに関連付けられている Hive metastore に対して自動的に作成されるhive_metastoreカタログにすることはできません。 ワークスペースのデフォルト カタログにテーブルを作成する場合は、 カタログ名を削除できます。

  • <schema>:テーブルを格納するスキーマの名前。

  • <table-name>:テーブルの名前。

  • <column-specification>:各列の名前とデータ型。

  • <bucket-path>: テーブルが作成されるクラウドストレージバケットへのパス。

  • <table-directory>:テーブルが作成されるディレクトリ。テーブルごとに一意のディレクトリを使用します。

重要

パスにテーブルが作成されると、ユーザーは、外部ロケーションまたはストレージ資格情報に対する権限が与えられていても、Databricksからそのパス内のファイルに直接アクセスできなくなります。これは、ユーザーがクラウドテナントから直接ファイルを読み取ることによってテーブルに適用されるアクセス制御を回避できないようにするためです。

CREATE TABLE <catalog>.<schema>.<table-name>
(
  <column-specification>
)
LOCATION 'gs://<bucket-path>/<table-directory>';
spark.sql("CREATE TABLE <catalog>.<schema>.<table-name> "
  "("
  "  <column-specification>"
  ") "
  "LOCATION 'gs://<bucket-path>/<table-directory>'")
library(SparkR)

sql(paste("CREATE TABLE <catalog>.<schema>.<table-name> ",
  "(",
  "  <column-specification>",
  ") ",
  "LOCATION 'gs://<bucket-path>/<table-directory>'",
  sep = ""))
spark.sql("CREATE TABLE <catalog>.<schema>.<table-name> " +
  "(" +
  "  <column-specification>" +
  ") " +
  "LOCATION 'gs://<bucket-path>/<table-directory>'")

Unity Catalogで、次の権限があることがチェックされます。

  • CREATE EXTERNAL TABLE :指定したクラウドストレージパスを参照する外部ロケーション上。

  • CREATE TABLE :親スキーマ上。

  • USE SCHEMA :親スキーマ上。

  • USE CATALOG :親カタログ上。

これらの権限がある場合、外部テーブルが作成されます。ない場合はエラーが発生し、外部テーブルは作成されません。

代わりに、 Hive metastore内の既存の外部テーブルを、データを複製せずにUnity Catalogに移行できます。「単一の外部テーブルをUnity Catalogにアップグレード」を参照してください。

Databricks Terraformプロバイダーdatabricks_tableを使用して外部テーブルを作成することもできます。databricks_tablesを使用して、テーブルの完全な名前の一覧を取得できます。

ノートブックの例: 外部テーブル を作成する

次のノートブックの例を使用して、カタログ、スキーマ、および外部テーブルを作成し、それらに対するアクセス許可を管理できます。

ノートブック での外部テーブルの作成と管理 Unity Catalog

ノートブックを新しいタブで開く

クラウドテナントに格納されているファイルからテーブルを作成

マネージドテーブルまたは外部テーブルに、クラウドテナントに格納されているファイルのレコードを設定できます。Unity Catalogは、その場所にあるファイルを読み取り、その内容をテーブルに挿入します。Unity Catalogでは、これをパスベースアクセスと呼びます。

このセクションの例に従うか、データの追加UIを使用できます

ファイルの内容の探索

外部ロケーションに格納されているデータを、そのデータからテーブルを作成する前に探索するには、カタログ エクスプローラまたは次のコマンドを使用します。

必要な権限:クラウドストレージパスに関連付けられている外部ロケーションのREAD FILES権限。その場所にあるデータファイルの一覧を返す必要があるためです。

ファイルからのテーブルの作成

このセクションの例に従って、新しいテーブルを作成し、クラウドテナント上のデータファイルを設定します。

代わりに、 Hive metastore内の既存の外部テーブルを、データを複製せずにUnity Catalogに移行できます。「単一の外部テーブルをUnity Catalogにアップグレード」を参照してください。

重要

  • この方法を使用してテーブルを作成した場合、レコードの重複を防ぐために、ストレージパスの読み取りは一度だけです。ディレクトリの内容を再度読み取る場合は、テーブルを削除して再作成する必要があります。既存のテーブルの場合、ストレージパスからレコードを挿入できます。

  • テーブルを作成するバケットパスは、データファイルの読み取りまたは書き込みには使用できません。

  • 正確なディレクトリ内のファイルのみが読み取られます。読み取りは再帰的ではありません。

  • 次の権限が必要です。

    • USE CATALOG :親カタログ上。またスキーマにUSE SCHEMA

    • CREATE TABLE :親スキーマ上。

    • READ FILES :ファイルが配置されているバケットパスに関連付けられた外部ロケーション上、または外部ロケーションを使用していない場合はストレージ認証情報に直接。

    • 外部テーブルを作成する場合は、テーブルが作成されるバケットパスにCREATE EXTERNAL TABLEが必要です。

新しいマネージドテーブルを作成し、クラウドストレージ内のデータを設定するには、次の例を使用します。

CREATE TABLE <catalog>.<schema>.<table-name>
(
  <column-specification>
)
SELECT * from <format>.`gs://<path-to-files>`;
spark.sql("CREATE TABLE <catalog>.<schema>.<table-name> "
  "( "
  "  <column-specification> "
  ") "
  "SELECT * from <format>.`gs://<path-to-files>`")
library(SparkR)

sql(paste("CREATE TABLE <catalog>.<schema>.<table-name> ",
  "( ",
  "  <column-specification> ",
  ") ",
  "SELECT * from <format>.`gs://<path-to-files>`",
  sep = ""))
spark.sql("CREATE TABLE <catalog>.<schema>.<table-name> " +
  "( " +
  "  <column-specification> " +
  ") " +
  "SELECT * from <format>.`gs://<path-to-files>`")

外部テーブルを作成し、クラウドストレージ内のデータを設定するには、LOCATION句を追加します。

CREATE TABLE <catalog>.<schema>.<table-name>
(
    <column-specification>
)
USING <format>
LOCATION 'gs://<table-location>'
SELECT * from <format>.`gs://<path-to-files>`;
spark.sql("CREATE TABLE <catalog>.<schema>.<table-name> "
  "( "
  "  <column-specification> "
  ") "
  "USING <format> "
  "LOCATION 'gs://<table-location>' "
  "SELECT * from <format>.`gs://<path-to-files>`")
library(SparkR)

sql(paste("CREATE TABLE <catalog>.<schema>.<table-name> ",
  "( ",
  "  <column-specification> ",
  ") ",
  "USING <format> ",
  "LOCATION 'gs://<table-location>' ",
  "SELECT * from <format>.`gs://<path-to-files>`",
  sep = ""))
spark.sql("CREATE TABLE <catalog>.<schema>.<table-name> " +
  "( " +
  "  <column-specification> " +
  ") " +
  "USING <format> " +
  "LOCATION 'gs://<table-location>' " +
  "SELECT * from <format>.`s3://<path-to-files>`")

パスから既存のテーブルへのレコードの挿入

バケットパスから既存のテーブルにレコードを挿入するには、COPY INTOコマンドを使用します。次の例で、プレースホルダーの値を置き換えます。

  • <catalog>:テーブルの親カタログの名前。

  • <schema>:テーブルの親スキーマの名前。

  • <path-to-files>:データファイルを含むバケットパス。

  • <format>:ファイルの形式(deltaなど)。

  • <table-location>:テーブルが作成されるバケットパス。

重要

  • この方法を使用してテーブルにレコードを挿入すると、レコードの重複を防ぐために、指定したバケットパスの読み取りは一度だけです。

  • テーブルを作成するバケットパスは、データファイルの読み取りまたは書き込みには使用できません。

  • 正確なディレクトリ内のファイルのみが読み取られます。読み取りは再帰的ではありません。

  • 次の権限が必要です。

    • USE CATALOG :親カタログ上。またスキーマにUSE SCHEMA

    • MODIFY :テーブル上。

    • READ FILES :ファイルが配置されているバケットパスに関連付けられた外部ロケーション上、または外部ロケーションを使用していない場合はストレージ認証情報に直接。

    • 外部テーブルにレコードを挿入するには、テーブルが配置されているバケットパスにCREATE EXTERNAL TABLEが必要です。

バケットパス内のファイルからマネージドテーブルにレコードを挿入し、外部ロケーションを使用してバケットパスから読み取るには、次の手順を実行します。

COPY INTO <catalog>.<schema>.<table>
FROM (
  SELECT *
  FROM 'gs://<path-to-files>'
)
FILEFORMAT = <format>;
spark.sql("COPY INTO <catalog>.<schema>.<table> "
  "FROM ( "
  "  SELECT * "
  "  FROM 'gs://<path-to-files>' "
  ") "
  "FILEFORMAT = <format>")
library(SparkR)

sql(paste("COPY INTO <catalog>.<schema>.<table> ",
  "FROM ( ",
  "  SELECT * ",
  "  FROM 'gs://<path-to-files>' ",
  ") ",
  "FILEFORMAT = <format>",
  sep = ""))
spark.sql("COPY INTO <catalog>.<schema>.<table> " +
  "FROM ( " +
  "  SELECT * " +
  "  FROM 'gs://<path-to-files>' " +
  ") " +
  "FILEFORMAT = <format>")

外部テーブルに挿入するには、次のようにLOCATION句を追加します。

COPY INTO <catalog>.<schema>.<table>
LOCATION 'gs://<table-location>'
FROM (
  SELECT *
  FROM 'gs://<path-to-files>'
)
FILEFORMAT = <format>;
spark.sql("COPY INTO <catalog>.<schema>.<table> "
  "LOCATION 'gs://<table-location>' "
  "FROM ( "
  "  SELECT * "
  "  FROM 'gs://<path-to-files>' "
  ") "
  "FILEFORMAT = <format>")
library(SparkR)

sql(paste("COPY INTO <catalog>.<schema>.<table> ",
  "LOCATION 'gs://<table-location>' ",
  "FROM ( ",
  "  SELECT * ",
  "  FROM 'gs://<path-to-files>' ",
  ") ",
  "FILEFORMAT = <format>",
  sep = ""))
spark.sql("COPY INTO <catalog>.<schema>.<table> " +
  "LOCATION 'gs://<table-location>' " +
  "FROM ( " +
  "  SELECT * " +
  "  FROM 'gs://<path-to-files>' " +
  ") " +
  "FILEFORMAT = <format>")

にコメントを追加する

テーブルの所有者またはテーブルに対する MODIFY 権限を持つユーザーは、テーブルとその列にコメントを追加できます。 次の機能を使用してコメントを追加できます。

  • COMMENT ON コマンド。このオプションでは、列のコメントはサポートされていません。

  • CREATE TABLE コマンドと ALTER TABLE コマンドを使用する場合のCOMMENTオプション。このオプションは、列のコメントをサポートします。

  • 「カタログエクスプローラ」(Catalog Explorer) の「手動」コメントフィールド。 このオプションは、列のコメントをサポートします。 「カタログエクスプローラでマークダウンコメントを使用してデータをドキュメント化する」を参照してください。

  • カタログエクスプローラの AI 生成コメント (AI 生成ドキュメントとも呼ばれます)。 テーブル スキーマや列名などのテーブル メタデータを取得する大規模言語モデル (LLM) によって提案されたコメントを表示し、コメントをそのまま編集または受け入れることで追加できます。 AIが生成したコメントを表に追加するを参照してください。