クエリ履歴システムテーブルリファレンス

プレビュー

このシステムテーブルは パブリック プレビュー段階です。 テーブルにアクセスするには、 system カタログでスキーマを有効にする必要があります。 詳細については、「 システムテーブル スキーマを有効にする」を参照してください。

この記事には、テーブルのスキーマの概要を含む、クエリ履歴システムテーブルに関する情報が含まれています。

重要

クエリ履歴システムテーブルにアクセスするには、 queryスキーマを有効にする必要があります。 システム スキーマを有効にする手順については、「システムテーブル スキーマを有効にする」を参照してください。

テーブルパス:このシステムテーブルは system.query.historyにあります。

クエリ履歴テーブルの使用

クエリ履歴テーブルには、 SQLウェアハウスまたはサーバレス コンピュート for ノートブック と ジョブ を使用して実行されたクエリのレコードが含まれます。 このテーブルには、テーブルへのアクセス元と同じリージョン内のすべてのワークスペースのアカウント全体のレコードが含まれます。

デフォルトにより、管理者のみがシステムテーブルにアクセスできます。 テーブルのデータをユーザーまたはグループと共有する場合、Databricks ではユーザーまたはグループごとに動的ビューを作成することをお勧めします。 「動的ビューの作成」を参照してください。

クエリ履歴システムテーブルスキーマ

クエリ履歴テーブルでは、次のスキーマが使用されます。

列名	データ型	説明	例
account_id	文字列	アカウントのID。	11e22ba4-87b9-4cc2 -9770-d10b894b7118
workspace_id	文字列	クエリが実行されたワークスペースの ID。	1234567890123456
statement_id	文字列	文の実行を一意に識別する ID。 この ID を使用して、クエリー履歴UI でステートメントの実行を見つけることができます。	7a99b43c-b46c-432b -b0a7-814217701909
session_id	文字列	Spark セッション ID。	01234567-cr06-a2mp -t0nd-a14ecfb5a9c2
execution_status	文字列	文の終了状態。 可能な値は次のとおりです。 FINISHED: 実行は成功しました FAILED: 実行が失敗し、付随するエラーメッセージに記載されている失敗の理由があります CANCELED: 実行がキャンセルされました	FINISHED
compute	構造体	ステートメントの実行に使用されるコンピュート リソースのタイプと、該当する場合はリソースの ID を表す構造体。 type値は WAREHOUSE または SERVERLESS_COMPUTEになります。	{ type: WAREHOUSE, cluster_id: NULL, warehouse_id: ec58ee3772e8d305 }
executed_by_user_id	文字列	ステートメントを実行したユーザーの ID。	2967555311742259
executed_by	文字列	ステートメントを実行したユーザーの電子メールアドレスまたはユーザー名。	example@databricks.com
statement_text	文字列	SQL ステートメントのテキスト。 顧客管理キーを設定している場合、 statement_text空になります。	SELECT 1
statement_type	文字列	ステートメントのタイプ。 たとえば、 ALTER、 COPY、'INSERT' などです。	SELECT
error_message	文字列	エラー状態を説明するメッセージ。 顧客管理キーを設定している場合、 error_message空になります。	[INSUFFICIENT_PERMISSIONS] Insufficient privileges: User does not have permission SELECT on table 'default.nyctaxi_trips'.
client_application	文字列	文を実行したクライアント・アプリケーション。 たとえば、Databricks SQL エディター、Tableau、Power BI などです。 このフィールドは、クライアント アプリケーションによって提供される情報から取得されます。 値は時間の経過とともに静的なままであることが予想されますが、これは保証できません。	Databricks SQL Editor
client_driver	文字列	ステートメントを実行するために Databricks に接続するために使用されるコネクタ。 例: Databricks SQL Driver for Go、Databricks ODBC ドライバー、Databricks JDBC ドライバー。	Databricks JDBC Driver
total_duration_ms	bigint	ステートメントの合計実行時間(ミリ秒単位)(結果フェッチ時間を除く)。	1
waiting_for_compute_duration_ms	bigint	コンピュートリソースが失われるのを待つのに費やされた時間（ミリ秒単位）。	1
waiting_at_capacity_duration_ms	bigint	使用可能なコンピュート容量をキューで待機するのに費やされた時間（ミリ秒）。	1
execution_duration_ms	bigint	ステートメントの実行に費やされた時間 (ミリ秒単位)。	1
compilation_duration_ms	bigint	メタデータの読み込みとステートメントの最適化に費やされた時間 (ミリ秒単位)。	1
total_task_duration_ms	bigint	すべてのタスクの所要時間の合計（ミリ秒単位）。 この時間は、すべてのノードのすべてのコアでクエリを実行するのにかかった合計時間を表します。 複数のタスクが並行して実行される場合、実時間よりも大幅に長くなる可能性があります。 タスクが利用可能なノードを待機する場合、ウォールクロック期間よりも短くなることがあります。	1
result_fetch_duration_ms	bigint	実行の終了後に文の結果をフェッチするのに費やされた時間 (ミリ秒単位)。	1
start_time	timestamp	Databricks がリクエストを受信した時刻。 タイムゾーン情報は値の末尾に記録され、 +00:00は UTC を表します。	2022-12-05T00:00:00.000+0000
end_time	timestamp	文の実行が終了した時刻 (結果のフェッチ時刻を除く)。 タイムゾーン情報は、 +00:00 UTC を表す値の終わりに記録されます。	2022-12-05T00:00:00.000+00:00
update_time	timestamp	ステートメントが進行状況の更新を最後に受信した時刻。 タイムゾーン情報は値の末尾に記録され、 +00:00は UTC を表します。	2022-12-05T00:00:00.000+00:00
read_partitions	bigint	プルーニング後に読み取られたパーティションの数。	1
pruned_files	bigint	プルーニングされたファイルの数。	1
read_files	bigint	プルーニング後に読み取られたファイルの数。	1
read_rows	bigint	文によって読み取られたローの合計数。	1
produced_rows	bigint	文によって返されたローの合計数。	1
read_bytes	bigint	文によって読み取られたデータの合計サイズ (バイト単位)。	1
read_io_cache_percent	int	IO キャッシュから読み取られた永続データのバイト数の割合。	50
from_result_cache	ブーリアン	TRUE 文の結果がキャッシュからフェッチされたことを示します。	TRUE
spilled_local_bytes	bigint	文の実行中に一時的にディスクに書き込まれるデータのサイズ (バイト単位)。	1
written_bytes	bigint	クラウド オブジェクト ストレージに書き込まれる永続データのサイズ (バイト単位)。	1
shuffle_read_bytes	bigint	ネットワーク経由で送信されたデータの合計量 (バイト単位)。	1
query_source	構造体	このステートメントの実行に関与した 1 つ以上の Databricks エンティティ (ジョブ、ノートブック、ダッシュボードなど) を表すキーと値のペアを含む構造体。 このフィールドは、Databricks エンティティのみを記録します。	{ job_info: {     job_id: 64361233243479     job_run_id: 887406461287882     job_task_key: “job_task_1”     job_task_run_id: 110378410199121 }
executed_as	文字列	文の実行に権限が使用されたユーザーまたはサービスプリンシパルの名前。	example@databricks.com
executed_as_user_id	文字列	ステートメントの実行に特権が使用されたユーザーまたはサービスプリンシパルの ID。	2967555311742259

レコードのクエリ プロファイルを表示する

クエリ履歴テーブル内のレコードに基づくクエリのクエリプロファイルに移動するには、次の操作を行います。

1. 目的のレコードを特定し、レコードの statement_idをコピーします。

2. レコードのworkspace_idを参照して、レコードと同じワークスペースにログインしていることを確認します。

3. クリックワークスペースサイドバーのクエリ履歴。

4. [ステートメント ID] フィールドに、レコードのstatement_idを貼り付けます。

5. クエリの名前をクリックします。 クエリメトリクスの概要が表示されます。

6. [ クエリ プロファイルの表示] をクリックします。

メタストアからのクエリ履歴を具体化します

次のコードを使用して、メタストアからのクエリ履歴を具体化するために、毎時、毎日、または毎週実行されるジョブを作成できます。 それに応じて、 HISTORY_TABLE_PATH 変数と LOOKUP_PERIOD_DAYS 変数を調整します。

from delta.tables import *
from pyspark.sql.functions import *
from pyspark.sql.types import *

HISTORY_TABLE_PATH = "jacek.default.history"
# Adjust the lookup period according to your job schedule
LOOKUP_PERIOD_DAYS = 1

def table_exists(table_name):
    try:
        spark.sql(f"describe table {table_name}")
        return True
    except Exception:
        return False

def save_as_table(table_path, df, schema, pk_columns):
    deltaTable = (
        DeltaTable.createIfNotExists(spark)
        .tableName(table_path)
        .addColumns(schema)
        .execute()
    )

    merge_statement = " AND ".join([f"logs.{col}=newLogs.{col}" for col in pk_columns])

    result = (
        deltaTable.alias("logs")
        .merge(
            df.alias("newLogs"),
            f"{merge_statement}",
        )
        .whenNotMatchedInsertAll()
        .whenMatchedUpdateAll()
        .execute()
    )
    result.show()

def main():
    df = spark.read.table("system.query.history")
    if table_exists(HISTORY_TABLE_PATH):
        df = df.filter(f"update_time >= CURRENT_DATE() - INTERVAL {LOOKUP_PERIOD_DAYS} days")
    else:
        print(f"Table {HISTORY_TABLE_PATH} does not exist. Proceeding to copy the whole source table.")

    save_as_table(
        HISTORY_TABLE_PATH,
        df,
        df.schema,
        ["workspace_id", "statement_id"]
    )

main()