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にアップグレードできます。 「Hive テーブルとビューを 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')")
マネージドテーブルの削除
テーブルを削除するには、テーブルの所有者である必要があります。マネージドテーブルを削除するには、次の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に移行することもできます。 アップグレード ウィザードを使用して単一の Hive テーブルを Unity Catalog 外部テーブルにアップグレードするを参照してください。
Databricks Terraformプロバイダーとdatabricks_tableを使用して外部テーブルを作成することもできます。databricks_tablesを使用して、テーブルの完全な名前の一覧を取得できます。
クラウドテナントに格納されているファイルからテーブルを作成
マネージドテーブルまたは外部テーブルに、クラウドテナントに格納されているファイルのレコードを設定できます。Unity Catalogは、その場所にあるファイルを読み取り、その内容をテーブルに挿入します。Unity Catalogでは、これをパスベースアクセスと呼びます。
このセクションの例に従うか、データの追加UIを使用できます。
ファイルの内容の探索
外部ロケーションに格納されているデータを、そのデータからテーブルを作成する前に探索するには、カタログ エクスプローラまたは次のコマンドを使用します。
必要な権限:クラウドストレージパスに関連付けられている外部ロケーションのREAD FILES
権限。その場所にあるデータファイルの一覧を返す必要があるためです。
ファイルからのテーブルの作成
このセクションの例に従って、新しいテーブルを作成し、クラウドテナント上のデータファイルを設定します。
注
代わりに、 Hive metastore内の既存の外部テーブルを、そのデータを複製せずにUnity Catalogに移行することもできます。 アップグレード ウィザードを使用して単一の Hive テーブルを 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が生成したコメントを表に追加するを参照してください。