カタログ エクスプローラーでマークダウン コメントを使ってデータを文書化する

  • [アーティクル]

ユーザーは、カタログ エクスプローラーを使って、カタログ、スキーマ、テーブルなどのデータ資産に関するコメントを表示できます。 この記事では、オブジェクト所有者またはオブジェクトに対する変更アクセス許可を持つユーザーが、カタログ エクスプローラーを使ってこれらのコメントを手動で追加する方法について説明します。

Note

カタログ エクスプローラーでは、テーブルと列に対して、AI が生成したコメントの提案を確認して適用することもできます。 「AI によって生成されたコメントをテーブルに追加する」を参照してください。

Unity Catalog を使っている場合は、Delta Sharing カタログ内のものを除くすべてのオブジェクトについて、カタログ エクスプローラーを使ってコメントを追加および編集できます。

Hive メタストア内のデータの場合は、カタログ エクスプローラーを使用してテーブル コメントのみを編集できます。

Markdown には、データをドキュメント化するための堅牢なオプション セットが用意されており、共有データ資産の検出可能性を高めてその理解を深めるために Azure Databricks ユーザーが使用できるオプションが強化されます。 Markdown コメントを使っても、クエリのパフォーマンスには影響しません。 DESCRIBE ステートメントによって返されるときは、Markdown はレンダリングされません。

カタログ エクスプローラーを使ってデータ オブジェクトにマークダウン コメントを追加する

カタログ エクスプローラーでは、オブジェクト名の下にカタログ、スキーマ、テーブル、その他のアセットのコメントが表示されます。

  • コメントが存在しない場合は、[コメントの追加] オプションが表示されます。
  • [コメントを表示しない] と [コメントの表示] オプションを使って、コメントの表示を切り替えることができます。

テーブル コメントの Markdown は、変更を保存するとすぐにカタログ エクスプローラーにレンダリングされます。

  • コメントを変更するには、鉛筆アイコンをクリックします。
  • コメントを更新するには、[保存] をクリックします。

テーブルの作成または ALTER TABLE アクションの間に、SQL を使ってテーブル コメントを追加することもできます。

Delta Lake テーブルのコメントを変更すると、テーブル履歴の SET TBLPROPERTIES 操作によって、現在のテーブル コメントの定義に使われる SQL クエリが記録されます。

サポートされている Markdown ドキュメントの例

カタログ エクスプローラーでは、基本的な Markdown 構文がサポートされています。 絵文字、画像、レンダリングされた Markdown テーブルには、Markdown を使用できません。 カタログ エクスプローラーでレンダリングされる Markdown ヘッダーのレベルは 2 つだけです。

次の例では、生の Markdown のコード ブロックを示します。 プレビューするには、この Markdown をカタログ エクスプローラーのコメントにコピーして、[保存] をクリックします。

# Header 1
## Header 2

**bold text**

*italics text*

~~strikethrough text~~

`monospace text`

---

> Block quote

Ordered list:
1. Item 1
1. Item 2
1. Item 3

Unordered list:
- Item a
- Item b
- Item c

def my_function(): return my_value


[Link](https://www.markdownguide.org/cheat-sheet/#basic-syntax)

その他のリソース

次の機能を使って、データ オブジェクトにコメントを追加することもできます。

  • COMMENT ON コマンド。 このオプションは列のコメントをサポートしていません。
  • CREATE <object> または ALTER <object> コマンドを使う場合の COMMENT オプション。 たとえば、「CREATE TABLE [USING]」と「ALTER TABLE」を参照してください。 このオプションは列コメントをサポートしています。
  • カタログ エクスプローラーの AI 生成コメント (AI 生成ドキュメントとも呼ばれます)。 テーブル スキーマや列の名前などのテーブルのメタデータを考慮に入れた大規模言語モデル (LLM) によって提案されたコメントを表示できます。また、コメントを編集するか、そのまま受け入れて追加できます。 このオプションはテーブルと列のみをサポートしています。 「AI によって生成されたコメントをテーブルに追加する」を参照してください。