Referenz der Abfrageverlaufsystemtabelle

Important

Diese Systemtabelle befindet sich in der Public Preview.

Dieser Artikel enthält Informationen zur Abfrageverlaufs-Systemtabelle, einschließlich einer Gliederung des Schemas der Tabelle.

Tabellenbereichspfad: Diese Systemtabelle befindet sich bei system.query.history.

Verwenden der Abfrageverlaufstabelle

Die Abfrageverlaufstabelle enthält Datensätze für Abfragen, die mithilfe von SQL-Warehouses oder serverlosem Computing für Notebooks und Aufträge ausgeführt wurden. Die Tabelle enthält kontoweite Datensätze aus allen Arbeitsbereichen in derselben Region, aus der Sie auf die Tabelle zugreifen.

Standardmäßig haben nur Administratoren Zugriff auf die Systemtabelle. Wenn Sie die Daten der Tabelle für einen Benutzer oder eine Gruppe freigeben möchten, empfiehlt Databricks, eine dynamische Ansicht für jeden Benutzer oder jede Gruppe zu erstellen. Weitere Informationen finden Sie unter Erstellen einer dynamischen Ansicht.

Schema der Abfrageverlaufs-Systemtabelle

Die Abfrageverlaufstabelle verwendet das folgende Schema:

Spaltenname	Datentyp	Description	Example
account_id	string	ID des Kontos	11e22ba4-87b9-4cc2 -9770-d10b894b7118
workspace_id	string	ID des Arbeitsbereichs, in dem die Abfrage ausgeführt wurde.	1234567890123456
statement_id	string	ID, die die Ausführung der Anweisung eindeutig identifiziert. Sie können diese ID verwenden, um die Ausführung der Anweisung in der Benutzeroberfläche Abfrageverlauf zu finden.	7a99b43c-b46c-432b -b0a7-814217701909
session_id	string	ID der Spark-Sitzung.	01234567-cr06-a2mp -t0nd-a14ecfb5a9c2
execution_status	string	Beendigungszustand der Anweisung. Mögliche Werte: FINISHED: Die Ausführung war erfolgreich. FAILED: Fehler bei der Ausführung mit dem Grund für fehler, der in der zugehörigen Fehlermeldung beschrieben wird. CANCELED: Die Ausführung wurde abgebrochen.	FINISHED
compute	struct	Eine Struktur, die den Typ der für die Ausführung der Anweisung verwendeten Computeressource und ggf. die ID der Ressource darstellt. Der Wert type ist entweder WAREHOUSE oder SERVERLESS_COMPUTE.	{ type: WAREHOUSE, cluster_id: NULL, warehouse_id: ec58ee3772e8d305 }
executed_by_user_id	string	ID des Benutzers, der die Anweisung ausgeführt hat.	2967555311742259
executed_by	string	E-Mail-Adresse oder Benutzername des Benutzers, der die Anweisung ausgeführt hat.	example@databricks.com
statement_text	string	Text der SQL-Anweisung. Wenn Sie kundenseitig verwaltete Schlüssel konfiguriert haben, ist statement_text leer. Aufgrund von Speicherbeschränkungen werden textwerte für längere Anweisungen komprimiert. Selbst bei der Komprimierung erreichen Sie möglicherweise ein Zeichenlimit.	SELECT 1
statement_type	string	Der Anweisungstyp. Beispiel: ALTER, COPY und INSERT.	SELECT
error_message	string	Meldung mit einer Beschreibung der Fehlerbedingung. Wenn Sie kundenseitig verwaltete Schlüssel konfiguriert haben, ist error_message leer.	[INSUFFICIENT_PERMISSIONS] Insufficient privileges: User does not have permission SELECT on table 'default.nyctaxi_trips'.
client_application	string	Clientanwendung, die die Anweisung ausgeführt hat. Beispiel: Databricks SQL Editor, Tableau und Power BI. Dieses Feld wird von Informationen abgeleitet, die von Clientanwendungen bereitgestellt werden. Werte werden zwar im Laufe der Zeit statisch bleiben, dies kann jedoch nicht garantiert werden.	Databricks SQL Editor
client_driver	string	Der Connector, der für die Verbindung zu Azure Databricks verwendet wird, um die Anweisung auszuführen. Zum Beispiel: Databricks SQL-Treiber für Go, Databricks ODBC-Treiber, Databricks JDBC-Treiber.	Databricks JDBC Driver
cache_origin_statement_id	string	Bei Abfrageergebnissen, die aus dem Cache abgerufen wurden, enthält dieses Feld die Anweisungs-ID der Abfrage, die das Ergebnis ursprünglich in den Cache eingefügt hat. Wenn das Abfrageergebnis nicht aus dem Cache abgerufen wird, enthält dieses Feld die eigene Statement-ID der Abfrage.	01f034de-5e17-162d -a176-1f319b12707b
total_duration_ms	bigint	Gesamtausführungszeit der Anweisung in Millisekunden (ohne Ergebnisabrufzeit).	1
waiting_for_compute_duration_ms	bigint	Mit Warten auf die Bereitstellung von Computeressourcen zugebrachte Zeit in Millisekunden.	1
waiting_at_capacity_duration_ms	bigint	Mit Warten auf verfügbare Computekapazität in der Warteschlange verbrachte Zeit in Millisekunden.	1
execution_duration_ms	bigint	Mit der Ausführung der Anweisung in Millisekunden zugebrachte Zeit.	1
compilation_duration_ms	bigint	Für das Laden von Metadaten und das Optimieren der Abfrage benötigte Zeit in Millisekunden.	1
total_task_duration_ms	bigint	Gesamtdauer aller Aufgaben in Millisekunden. Diese Zeit ist die insgesamt zum Ausführen der Abfrage auf allen Kernen aller Knoten benötigte Zeit. Diese Zeit kann deutlich länger als die Gesamtbetrachtungszeit sein, wenn mehrere Aufgaben parallel ausgeführt werden. Sie kann kürzer als die Gesamtbetrachtungszeit sein, wenn Aufgaben auf verfügbare Knoten warten müssen.	1
result_fetch_duration_ms	bigint	Für das Abrufen der Anweisungsergebnisse nach Abschluss der Ausführung zugebrachte Zeit in Millisekunden.	1
start_time	timestamp	Der Zeitpunkt, zu dem Databricks die Anforderung erhalten hat. Zeitzoneninformationen werden am Ende des Werts aufgezeichnet, wobei +00:00 die UTC darstellt.	2022-12-05T00:00:00.000+0000
end_time	timestamp	Der Zeitpunkt, zu dem die Ausführung der Anweisung beendet wurde, ohne die Zeit für das Abrufen der Ergebnisse. Zeitzoneninformationen werden am Ende des Werts aufgezeichnet, wobei +00:00 die UTC darstellt.	2022-12-05T00:00:00.000+00:00
update_time	timestamp	Der Zeitpunkt, zu dem die Anweisung zuletzt eine Fortschrittsaktualisierung erhalten hat. Zeitzoneninformationen werden am Ende des Werts aufgezeichnet, wobei +00:00 die UTC darstellt.	2022-12-05T00:00:00.000+00:00
read_partitions	bigint	Anzahl der nach Bereinigung gelesenen Partitionen.	1
pruned_files	bigint	Anzahl bereinigter Dateien.	1
read_files	bigint	Anzahl der nach Bereinigung gelesenen Dateien.	1
read_rows	bigint	Gesamtzahl der von der Anweisung gelesenen Zeilen.	1
produced_rows	bigint	Gesamtanzahl der von der Anweisung zurückgegebenen Zeilen.	1
read_bytes	bigint	Gesamtgröße der von der Anweisung gelesenen Daten in Byte.	1
read_io_cache_percent	int	Prozentsatz an Bytes persistenter Daten, die aus dem E/A-Cache gelesen wurden.	50
from_result_cache	boolean	TRUE gibt an, dass das Anweisungsergebnis aus dem Cache abgerufen wurde.	TRUE
spilled_local_bytes	bigint	Größe der Daten in Byte, die während der Ausführung der Anweisung vorübergehend auf die Festplatte geschrieben werden.	1
written_bytes	bigint	Größe der in den Cloudobjektspeicher geschriebenen persistenten Daten in Byte.	1
written_rows	bigint	Die Anzahl der Zeilen persistenter Daten, die in den Cloudobjektspeicher geschrieben wurden.	1
written_files	bigint	Die Anzahl der Dateien von persistenten Daten, die in den Cloudobjektspeicher geschrieben wurden.	1
shuffle_read_bytes	bigint	Die Gesamtmenge der über das Netzwerk gesendeten Daten in Bytes.	1
query_source	struct	Eine Struktur, die Schlüsselwertpaare enthält, die Databricks-Entitäten darstellen, die an der Ausführung dieser Anweisung beteiligt waren, z. B. Aufträge, Notizbücher oder Dashboards. Dieses Feld zeichnet nur Databricks-Entitäten auf.	{ alert_id: 81191d77-184f-4c4e-9998-b6a4b5f4cef1, sql_query_id: null, dashboard_id: null, notebook_id: null, job_info: { job_id: 12781233243479, job_run_id: null, job_task_run_id: 110373910199121 }, legacy_dashboard_id: null, genie_space_id: null }
query_parameters	struct	Eine Struktur, die benannte und positionale Parameter enthält, die in parametrisierten Abfragen verwendet werden. Benannte Parameter werden als Schlüsselwertpaare dargestellt, die Parameternamen zu Werten zuordnen. Positionsparameter werden als Liste dargestellt, in der der Index die Parameterposition angibt. Es kann jeweils nur ein Typ (benannt oder positionell) vorhanden sein.	{ named_parameters: { "param-1": 1, "param-2": "hello" }, pos_parameters: null, is_truncated: false }
executed_as	string	Der Name des Benutzers oder Dienstprinzipals, dessen Berechtigung zum Ausführen der Anweisung verwendet wurde.	example@databricks.com
executed_as_user_id	string	Die ID des Benutzers oder Dienstprinzipals, dessen Berechtigung zum Ausführen der Anweisung verwendet wurde.	2967555311742259

Anzeigen des Abfrageprofils für einen Datensatz

Gehen Sie wie folgt vor, um zu dem Abfrageprofil einer Abfrage zu navigieren, das auf einem Datensatz in der Abfrageverlaufstabelle basiert:

1. Identifizieren Sie den relevanten Datensatz und kopieren Sie dann dessen statement_id.
2. Verweisen Sie auf die workspace_id des Datensatzes, um sicherzustellen, dass Sie im Arbeitsbereich des Datensatzes angemeldet sind.
3. Wählen Sie in der Randleiste des Arbeitsbereichs Abfrageverlauf aus.
4. Fügen Sie in das Feld Anweisungs-ID die statement_id des Datensatzes ein.
5. Wählen Sie den Namen einer Abfrage. Es wird eine Übersicht über Abfragemetriken angezeigt.
6. Wählen Sie Siehe Abfrageprofil aus.

Grundlegendes zur Spalte query_source

Die query_source Spalte enthält eine Reihe eindeutiger Bezeichner von Azure Databricks-Entitäten, die an der Ausführung der Anweisung beteiligt sind.

Wenn die query_source Spalte mehrere IDs enthält, bedeutet dies, dass die Ausführung der Anweisung durch mehrere Entitäten ausgelöst wurde. Beispielsweise kann ein Auftragsergebnis eine Warnung auslösen, die eine SQL-Abfrage aufruft. In diesem Beispiel werden alle drei IDs innerhalb von query_source eingetragen. Die Werte dieser Spalte werden nicht nach Ausführungsreihenfolge sortiert.

Mögliche Abfragequellen sind:

• alert_id: Aus einer Warnung ausgelöste Aussage
• sql_query_id: Anweisung, die in dieser SQL-Editorsitzung ausgeführt wird
• dashboard_id: Aus einem Dashboard ausgeführte Anweisung
• legacy_dashboard_id: Anweisung, die von einem Legacy-Dashboard ausgeführt wurde
• genie_space_id: Aus einem Genie-Raum ausgeführte Erklärung
• notebook_id: Anweisung, die aus einem Notebook ausgeführt wird.
• job_info.job_id: Anweisung, die in einem Auftrag ausgeführt wird
• job_info.job_run_id: Anweisung, die in einer Jobausführung ausgeführt wird
• job_info.job_task_run_id: Anweisung, die in einer Auftragsaufgabe ausgeführt wird

Gültige Kombinationen von query_source

Die folgenden Beispiele zeigen, wie die query_source Spalte je nach Ausführung der Abfrage aufgefüllt wird:

• Abfragen, die während einer Auftragsausführung ausgeführt werden, umfassen eine aufgefüllte job_info Struktur:

  {
alert_id: null,
sql_query_id: null,
dashboard_id: null,
notebook_id: null,
job_info: {
job_id: 64361233243479,
job_run_id: null,
job_task_run_id: 110378410199121
},
legacy_dashboard_id: null,
genie_space_id: null
}

• Abfragen aus älteren Dashboards umfassen ein sql_query_id und legacy_dashboard_id:

  {
alert_id: null,
sql_query_id: 7336ab80-1a3d-46d4-9c79-e27c45ce9a15,
dashboard_id: null,
notebook_id: null,
job_info: null,
legacy_dashboard_id: 1a735c96-4e9c-4370-8cd7-5814295d534c,
genie_space_id: null
}

• Abfragen aus Warnungen umfassen eine sql_query_id und eine alert_id.

  {
alert_id: e906c0c6-2bcc-473a-a5d7-f18b2aee6e34,
sql_query_id: 7336ab80-1a3d-46d4-9c79-e27c45ce9a15,
dashboard_id: null,
notebook_id: null,
job_info: null,
legacy_dashboard_id: null,
genie_space_id: null
}

• Abfragen aus Dashboards umfassen eine dashboard_id, aber keine job_info:

  {
alert_id: null,
sql_query_id: null,
dashboard_id: 887406461287882,
notebook_id: null,
job_info: null,
legacy_dashboard_id: null,
genie_space_id: null
}

Materialisieren des Abfrageverlaufs aus Ihrem Metastore

Der folgende Code kann verwendet werden, um einen Auftrag zu erstellen, der stündlich, täglich oder wöchentlich ausgeführt wird, um den Abfrageverlauf aus einem Metaspeicher zu materialisieren. Passen Sie die variablen HISTORY_TABLE_PATH und LOOKUP_PERIOD_DAYS entsprechend an.

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()

Analysieren der Tabellenpopularität einschließlich zwischengespeicherter Abfragen

Die Tabellenherkunftssystemtabelle gibt keine Einträge für Abfrageergebnisse aus dem Ergebnis-Cache aus. Aus diesem Gründen müssen Sie die Abfrageverlaufstabelle mit der Tabellenzeilensystemtabelle verbinden, um zwischengespeicherte Abfragen in Ihre Analyse einzuschließen.

Die folgende Abfrage ruft z. B. Tabellen mit Abfragen ab, die eine Stunde Der Ausführungszeit in den letzten 7 Tagen überschreiten:

SELECT
    t.source_table_full_name,
    COUNT(*) AS num_of_queries_over_hour
FROM
    system.query.history h
    INNER JOIN system.access.table_lineage t
        ON t.statement_id = h.cache_origin_statement_id
WHERE
    h.total_duration_ms > 3600000
    AND t.event_time > CURRENT_TIMESTAMP() - INTERVAL 7 DAYS
    AND t.source_table_full_name IS NOT NULL
GROUP BY t.source_table_full_name
ORDER BY 2 DESC;