SQL-Oberfläche öffnen

Mit der semantischen Modellierungsebene LookML von Looker können Datenanalysten Dimensionen, Summen, Berechnungen und Datenbeziehungen in einer SQL-Datenbank definieren. LookML-Modelle bieten die Wiederverwendbarkeit von Code und die Git-Integration. Ein gut strukturiertes LookML-Modell ermöglicht es Nutzern, ihre eigenen explorativen Datenanalysen und Berichte im Self-Service zu erstellen.

Das LookML-Modell bildet die Grundlage aller Daten, die von Looker angefordert werden. Dies gilt unabhängig davon, ob die Anfrage von der Looker Explore-Oberfläche in der Looker-Benutzeroberfläche, einer eingebetteten Visualisierung in Ihrem Unternehmensportal, einer anderen Drittanbieteranwendung oder einer benutzerdefinierten Anwendung stammt, die mit der Looker API entwickelt wurde. Die Open SQL-Schnittstelle bietet Zugriff auf die LookML-Modelle für alle Drittanbieteranwendungen, die Java Database Connectivity (JDBC) unterstützen. Anwendungen können wie eine Datenbank eine Verbindung zu einem LookML-Modell herstellen, sodass die Benutzer die gesamte Arbeit nutzen können, die ihre Datenanalysten im LookML-Modell erledigen, während sie gleichzeitig die Tools verwenden, mit denen sie am besten vertraut sind.

Wie die Open SQL-Schnittstelle LookML-Projektelemente anzeigt

Um zu verstehen, wie die Open SQL-Schnittstelle die Elemente eines LookML-Projekts darstellt, ist es wichtig zu wissen, wie LookML-Projekte strukturiert sind.

Ein LookML-Projekt ist eine Sammlung von Dateien, die die Objekte, Datenbankverbindungen und Benutzeroberflächenelemente beschreiben, die zum Ausführen von SQL-Abfragen in Looker verwendet werden. Weitere Informationen finden Sie unter LookML-Begriffe und ‑Konzepte. Die folgenden LookML-Projektkonzepte beziehen sich auf die Open SQL-Oberfläche:

  • In einem LookML-Modell werden eine Datenbankverbindung und ein oder mehrere Explores angegeben. Die Open SQL-Oberfläche stellt Modelle als Datenbankschemas bereit.
  • Ein Explore ist eine logische Gruppierung einer oder mehrerer Ansichten und der Join-Beziehungen zwischen diesen Ansichten. In der Open SQL-Oberfläche werden Explores als Datenbanktabellen angezeigt.
  • Eine Ansicht definiert eine Sammlung von Feldern (Dimensionen und Kennzahlen). Eine Ansicht basiert in der Regel auf einer Tabelle in Ihrer Datenbank oder einer abgeleiteten Tabelle. Ansichten können die Spalten aus der zugrunde liegenden Datenbanktabelle sowie alle benutzerdefinierten Dimensionen oder Messwerte enthalten, die Ihre Endnutzer benötigen. In der Open SQL-Oberfläche wird die Kombination aus einem Ansichtsnamen und einem Feldnamen als Datenbankspaltenname angezeigt. Die Dimension id in der Ansicht order_items wird beispielsweise von der Open SQL-Schnittstelle als Datenbankspalte namens order_items.id angezeigt.

Mit einem Looker-Explore können Join-Beziehungen zwischen mehreren Ansichten definiert werden. Da es möglich ist, dass eine Ansicht ein Feld mit dem gleichen Namen wie ein Feld in einer anderen Ansicht enthält, enthält die Open SQL-Schnittstelle beim Verweis auf eine Spalte sowohl den Ansichtsnamen als auch den Feldnamen. Verwenden Sie daher dieses Format, um beim Senden von Abfragen an die Open SQL-Schnittstelle auf einen Spaltennamen zu verweisen:

`<view_name>.<field_name>`

Beispiel: Wenn es ein Explore namens order_items gibt, das eine Ansicht namens customer mit einer Ansicht namens product verbindet und beide Datenansichten eine id-Dimension haben, würden Sie die beiden id-Felder mit `customer.id` und `product.id` bezeichnen. Wenn Sie den voll qualifizierten Namen auch mit dem Explore-Namen verwenden möchten, müssen Sie die beiden Felder als `order_items`.`customer.id` und `order_items`.`product.id` bezeichnen. Informationen darüber, wo beim Verweisen auf Datenbankkennungen die Graviszeichen einzufügen sind, finden Sie unter Gravis um Datenbankkennungen verwenden.

Open SQL-Schnittstelle einrichten

Führen Sie die folgenden Schritte aus, um die Open SQL-Schnittstelle zu verwenden:

  1. Prüfen Sie, ob die Anforderungen erfüllt sind.
  2. Laden Sie die JDBC-Treiberdatei der Open SQL-Schnittstelle herunter.

Diese Schritte werden in den folgenden Abschnitten beschrieben.

Voraussetzungen

Für die Verwendung der Open SQL-Schnittstelle sind die folgenden Komponenten erforderlich:

JDBC-Treiber für die Open SQL-Schnittstelle herunterladen

Der JDBC-Treiber für die Open SQL-Schnittstelle von Looker heißt avatica-<release_number>-looker.jar. Laden Sie die neueste Version von GitHub unter https://github.com/looker-open-source/calcite-avatica/releases herunter.

Der JDBC-Treiber erwartet das folgende URL-Format:

jdbc:looker:url=https://Looker instance URL

Beispiel:

jdbc:looker:url=https://myInstance.cloud.looker.com

Die JDBC-Treiberklasse ist:

org.apache.calcite.avatica.remote.looker.LookerDriver

Bei der Open SQL-Schnittstelle authentifizieren

Die Open SQL-Schnittstelle unterstützt drei Authentifizierungsmethoden:

OAuth

JDBC-Clients, die OAuth unterstützen, können so konfiguriert werden, dass sie den OAuth-Server einer Looker-Instanz verwenden. So konfigurieren Sie die OAuth-Authentifizierung:

  1. Verwenden Sie die API Explorer-Erweiterung, um den JDBC-OAuth-Client bei Ihrer Looker-Instanz zu registrieren, damit die Looker-Instanz OAuth-Anfragen erkennen kann. Eine Anleitung dazu finden Sie unter OAuth-Clientanwendung registrieren.
  2. Melden Sie sich mit OAuth in Looker an, um ein Zugriffstoken anzufordern. Ein Beispiel finden Sie unter Nutzeranmeldung mit OAuth durchführen.
  3. Verwenden Sie ein Properties-Objekt, um die OAuth-Anmeldedaten zu übergeben, wenn die JDBC-Verbindung zur Open SQL-Schnittstelle geöffnet wird.

Im folgenden Beispiel wird DriverManager#getConnection(<String>, <Properties>`) verwendet:

String access_token = getAccessToken() //uses the Looker OAuth flow to get a token
String URL = "jdbc:looker:url=https://myInstance.cloud.looker.com"
Properties info = new Properties( );
info.put("token", access_token);
Connection conn = DriverManager.getConnection(URL, info);

Zugriffstoken mithilfe von API-Schlüsseln generieren

Anstatt den standardmäßigen OAuth-Ablauf zum Generieren eines Zugriffstokens zu verwenden, können Sie die folgenden Schritte ausführen, um mit der Looker-API ein Zugriffstoken zu generieren, das an den JDBC-Treiber der Open SQL-Schnittstelle übergeben werden kann:

  1. Generieren Sie API-Schlüssel für Ihren Looker-Nutzer wie auf der Seite Verwaltungseinstellungen – Nutzer beschrieben.

  2. Verwenden Sie den login API-Endpunkt für Ihre Looker-Instanz. Die Antwort enthält ein Zugriffstoken im Format Authorization: token <access_token>. Im Folgenden finden Sie ein Beispiel für den curl-Befehl, mit dem Sie diese Anfrage stellen können:

      curl -k -d "client_id=<client_id>&client_secret=<client_secret>" https://<looker_host>/login\

  3. Übergeben Sie den <access_token>-Wert der Antwort als Token im Properties-Objekt, um beim Öffnen der JDBC-Verbindung zur Open SQL Interface die OAuth-Anmeldedaten zu übergeben.

API-Schlüssel

Sie können auch API-Schlüssel anstelle eines Nutzernamens und Passworts verwenden, um sich zu authentifizieren. API-Schlüssel gelten als weniger sicher als OAuth und sind möglicherweise nur während der Vorabversion der Open SQL-Schnittstelle verfügbar. Informationen zum Erstellen von API-Schlüsseln für Ihre Looker-Instanz finden Sie unter API-Schlüssel.

Verwenden Sie den Teil Client-ID des Looker API-Schlüssels als Nutzernamen. Verwenden Sie den Abschnitt Client Secret (Client-Secret) als Passwort.

Abfragen mit der Open SQL-Schnittstelle ausführen

Beachten Sie die folgenden Richtlinien, wenn Sie Abfragen mit der Open SQL-Schnittstelle ausführen:

  • Über die Open SQL-Schnittstelle werden SQL-Abfragen akzeptiert, die der GoogleSQL-Syntax entsprechen.
  • Die Open SQL-Schnittstelle erfordert Graviszeichen (`) um Modell-, Explore- und Feldkennungen. Weitere Informationen und Beispiele finden Sie unter Backticks um Datenbank-IDs setzen.
  • Die Open SQL-Schnittstelle unterstützt die meisten BigQuery-Operatoren.
  • Mit der Open SQL-Schnittstelle müssen Sie alle LookML-Messwerte festlegen, die in einer Abfrage enthalten sind. Dazu setzen Sie den Messwert (einschließlich Gravis) in die spezielle Funktion AGGREGATE(). Weitere Informationen finden Sie im Abschnitt LookML-Messwerte mit AGGREGATE() angeben.

Einschränkungen von LookML

Beachten Sie beim Senden von Abfragen an die Open SQL-Schnittstelle Folgendes:

SQL-Einschränkungen

Beachten Sie die folgenden SQL-Einschränkungen beim Senden von Abfragen an die Open SQL-Schnittstelle:

Backticks um Datenbankkennungen verwenden

Verwenden Sie beim Senden von Abfragen an die Open SQL-Schnittstelle Graviszeichen um Schema-, Tabellen- und Spaltenkennungen. So geben Sie Datenbankelemente mithilfe von Graviszeichen mit Looker-Begriffen an:

  • Schema: `<model_name>`
  • table: `<explore_name>`

  • Spalte: `<view_name>.<field_name>`

Hier ist ein Beispiel für ein SELECT-Anweisungsformat mit diesen Elementen:

SELECT `view.field`
  FROM `model`.`explore`
  LIMIT 10;

LookML-Messwerte mit AGGREGATE() angeben

Datenbanktabellen enthalten in der Regel nur Dimensionen, also Daten, die ein einzelnes Attribut einer Zeile in der Tabelle beschreiben. LookML-Projekte können jedoch sowohl Dimensionen als auch Messwerte definieren. Ein Messwert ist eine Aggregation von Daten über mehrere Zeilen hinweg, wie z. B. SUM, AVG, MIN oder MAX. Andere Messwerttypen werden ebenfalls unterstützt. Eine vollständige Liste der unterstützten LookML-Messwerttypen finden Sie auf der Seite Messwerttypen.

Mit der Open SQL-Schnittstelle müssen Sie alle LookML-Messwerte festlegen, die in einer Abfrage enthalten sind. Dazu setzen Sie den Messwert (einschließlich Gravis) in die spezielle Funktion AGGREGATE(). So können Sie beispielsweise das Messwert-Element Anzahl aus der Ansicht Bestellungen angeben:

AGGREGATE(`orders.count`)

LookML-Messwerte müssen in die AGGREGATE()-Funktion eingeschlossen werden, unabhängig davon, ob sie sich in einer SELECT-, HAVING- oder ORDER BY-Klausel befinden.

Wenn Sie nicht sicher sind, ob es sich bei einem Feld um ein LookML-Maß handelt, können Sie mit der Methode DatabaseMetaData.getColumns auf die Metadaten für das LookML-Projekt zugreifen. In der Spalte IS_GENERATEDCOLUMN wird für alle LookML-Messwerte YES und für LookML-Dimensionen NO angezeigt. Weitere Informationen finden Sie im Abschnitt Auf Datenbankmetadaten zugreifen.

Beispiel

Hier ist eine Beispielabfrage, in der sowohl Dimensionen als auch Messwerte verwendet werden. Mit dieser Abfrage werden die Dimensionen Bundesland und Ort aus der Ansicht Kunden und der Messwert Gesamtbetrag aus der Ansicht Bestellungen abgerufen. Beide Ansichten sind im ecommerce-Modell mit dem Explore orders verknüpft. Für die Städte mit mehr als 10 Bestellungen zeigt diese Abfrageantwort die 5 wichtigsten Städte nach Bestellbetrag an:

SELECT `customers.state`, `customers.city`,
  AGGREGATE(`orders.total_amount`)
FROM `ecommerce`.`orders`
GROUP BY `customers.state`, `customers.city`
HAVING AGGREGATE(`orders.count`) > 10
ORDER BY 3 DESC LIMIT 5;

Nur-Filter-Felder und Parameter mit JSON_OBJECT angeben

Die Open SQL-Schnittstelle unterstützt Parameter und Nur-Filter-Felder.

Wenn Sie Abfragen mit der Open SQL-Schnittstelle ausführen, können Sie der Abfrage Parameter und nur-Filterfelder hinzufügen. Dazu fügen Sie einen JSON_OBJECT-Konstruktoraufruf mit folgendem Format ein:

JSON_OBJECT(
    '<view>.<parameter name>', '<parameter value>',
    '<view>.<filter name>', '<Looker filter expression>'
)

Das JSON-Objekt kann null oder mehr Filter-Schlüssel/Wert-Paare und null oder mehr Parameter-Schlüssel/Wert-Paare enthalten.

  • Der Schlüssel im Konstruktor von JSON_OBJECT muss der Name eines Nur-Filter-Felds oder -Parameters sein.
  • Bei Nur-Filter-Feldern muss der Wert für jeden Schlüssel ein Looker-Stringfilterausdruck sein.
  • Bei Parametern muss der Wert für jeden Schlüssel ein einfacher Wert sein, der in der parameter-Definition definiert ist.

In den folgenden Abschnitten finden Sie Beispiele für die Verwendung von Parametern und Nur-Filter-Feldern mit der Open SQL-Schnittstelle.

Parameterbeispiel

Beispiel für die Verwendung einer parameter mit Open SQL Interface: Die Ansicht customers hat in Looker einen Parameter, der so definiert ist:

parameter: segment {
  type: string
  allowed_value: {
    label: "Small (less than 500)"
    value: "small_customers"
  }
  allowed_value: {
    label: "Larger (greater than 10,000)"
    value: "large_customers"
  }
  allowed_value: {
    label: "Medium customers (Between 500 and 10,000)"
    value: "medium_customers"
  }
}

Sie könnten diese Abfrage an die Open SQL Interface senden, um den Parameterwert segment von medium_customers auf die Abfrage anzuwenden:

SELECT `customers.segment_size`,
  AGGREGATE(`orders.total_amount`)
FROM `ecommerce`.`orders`(JSON_OBJECT(
    'customers.segment', 'medium_customers'
))
GROUP BY `customers.state`, `customers.city`
HAVING AGGREGATE(`orders.count`) > 10
ORDER BY 3 DESC LIMIT 5;

Die Open SQL-Oberfläche übergibt diesen Parameterwert an die Abfrage in Looker. Looker wendet den Wert medium_customers auf alle Felder im Explore an, die für die Verwendung des Parameters segment konfiguriert sind. Informationen zur Funktionsweise von Parametern in Looker finden Sie in der parameter-Dokumentation.

Beispiel für ein reines Filterfeld

Sie können das Feld filter mit der Open SQL-Schnittstelle verwenden. Beispiel: Die Ansicht products enthält eine Dimension und ein reines Filterfeld, das in Looker so definiert ist:

filter: brand_select {
  type: string
  }

dimension: brand_comparitor {
  sql:
    CASE
      WHEN {% condition brand_select %} ${products.brand_name} {% endcondition %}
      THEN ${products.brand_name}
      ELSE "All Other Brands"
    END ;;
    }

Sie können den Filter brand_select mit der Open SQL-Schnittstelle verwenden, indem Sie eine Abfrage wie die folgende senden:

SELECT `products.brand_comparator`, `products.number_of_brands`,
  AGGREGATE(`products.total_revenue`)
FROM `ecommerce`.`orders`(JSON_OBJECT(
    'products.brand_select', '%Santa Cruz%'
))
GROUP BY `products.brand_comparator`
ORDER BY 3 DESC LIMIT 5;

In der Open SQL-Schnittstelle wird der Looker-Stringfilterausdruck %Santa Cruz% auf die Abfrage in Looker angewendet. Weitere Informationen zur Funktionsweise von Nur-Filter-Feldern in Looker finden Sie in der filter-Dokumentation.

Auf Datenbankmetadaten zugreifen

Die Open SQL-Schnittstelle unterstützt einen Teil der standardmäßigen JDBC-DatabaseMetaData-Schnittstelle, mit der Informationen zur zugrunde liegenden Datenbank abgerufen werden. Mit den folgenden Methoden der DatabaseMetaData-Schnittstelle können Sie Informationen zu Ihrem LookML-Modell abrufen:

DatabaseMetadata.getSchemas

In der folgenden Tabelle wird beschrieben, wie sich ein LookML-Modell mit den Standarddatenbankstrukturen in der Antwort der DatabaseMetadata.getSchemas-Schnittstellenmethode verhält.

getSchemas-Antwortspalte Beschreibung
TABLE_SCHEM Name des LookML-Modells
TABLE_CATALOG (null)

DatabaseMetadata.getTables

In der folgenden Tabelle wird beschrieben, wie sich ein LookML-Modell mit den Datenbankstrukturen in der Antwort der DatabaseMetaData.getTables-Schnittstellenmethode verhält. Die Antwort enthält JDBC-Standardmetadaten sowie Looker-spezifische Metadaten:

getTables Antwortspalte Beschreibung
JDBC-Standardmetadaten
TABLE_CAT (null)
TABLE_SCHEM Name des LookML-Modells
TABLE_NAME Name der LookML-Analyse
TABLE_TYPE Gibt immer den Wert TABLE_TYPE zurück
Looker-spezifische Metadaten
DESCRIPTION Beschreibung ansehen
LABEL Label für explorative Datenanalysen
TAGS Tags

DatabaseMetadata.getColumns

In der folgenden Tabelle wird beschrieben, wie ein LookML-Modell in der Antwort der DatabaseMetaData.getColumns-Schnittstellenmethode mit den Datenbankstrukturen in Beziehung steht. Die Antwort enthält JDBC-Standardmetadaten sowie Looker-spezifische Metadaten:

getColumns-Antwortspalte Beschreibung
JDBC-Standardmetadaten
TABLE_CAT (null)
TABLE_SCHEM Name des LookML-Modells
TABLE_NAME Name des LookML-Explores
COLUMN_NAME LookML-Feldname im Format `<view_name>.<field_name>`. Beispiel: `orders.amount`.
DATA_TYPE Der java.sql.Types-Code der Spalte. Die Looker-yesno-Felder haben beispielsweise den SQL-Typcode 16 (BOOLEAN).
ORDINAL_POSITION Die 1-basierte Ordinalzahl des Felds im Explore (Dimensionen und Messwerte werden alphabetisch nach Ansichts- und dann nach Feldnamen sortiert)
IS_NULLABLE Gibt immer den Wert YES zurück
IS_GENERATEDCOLUMN YES für Messwerte, NO für Dimensionen
Looker-spezifische Metadaten
DIMENSION_GROUP Name der Dimensionsgruppe, wenn das Feld zu einer Dimensionsgruppe gehört. Wenn das Feld nicht zu einer Dimensionsgruppe gehört, hat dieser Wert den Wert „null“.
DRILL_FIELDS Liste der für die Dimension oder den Messwert festgelegten Drilldown-Felder, falls vorhanden
FIELD_ALIAS Alias für das Feld, falls vorhanden
FIELD_CATEGORY Ob das Feld ein dimension- oder measure-Element ist
FIELD_DESCRIPTION Feld description
FIELD_GROUP_VARIANT Wenn das Feld unter einem Gruppenlabel angezeigt wird, wird mit FIELD_GROUP_VARIANT der kürzere Name des Felds angegeben, der unter dem Gruppenlabel angezeigt wird.
FIELD_LABEL Feld label
FIELD_NAME Name der Dimension oder des Messwerts
HIDDEN Ob das Feld im Field Picker in Explores ausgeblendet ist (TRUE) oder ob es im Field Picker in Explores sichtbar ist (FALSE).
LOOKER_TYPE LookML-Feldtyp für die Dimension oder den Messwert
REQUIRES_REFRESH_ON_SORT Gibt an, ob die SQL-Abfrage aktualisiert werden muss, um die Werte des Felds neu zu sortieren (TRUE), oder ob die Werte des Felds neu sortiert werden können, ohne dass die SQL-Abfrage aktualisiert werden muss (FALSE).
SORTABLE Gibt an, ob das Feld sortiert werden kann (TRUE) oder nicht (FALSE).
TAGS Feld-Tags
USE_STRICT_VALUE_FORMAT Ob für das Feld das strenge Format (TRUE) verwendet wird oder nicht (FALSE)
VALUE_FORMAT String für das Wertformat des Felds
VIEW_LABEL Label für das Feld ansehen
VIEW_NAME Name der Ansicht, in der das Feld im LookML-Projekt definiert ist

Abfragen der Open SQL-Oberfläche in der Looker-Benutzeroberfläche identifizieren

Looker-Administratoren können über die Looker-Benutzeroberfläche ermitteln, welche Abfragen von der Open SQL-Schnittstelle stammen:

  • Auf der Verwaltungsseite Abfragen haben Abfragen der Open SQL-Schnittstelle den Wert „Sql Interface“ als Source. Der Wert Nutzer enthält den Namen des Looker-Nutzers, der die Abfrage ausgeführt hat. Sie können bei einer Abfrage auf die Schaltfläche Details klicken, um zusätzliche Informationen zu dieser Abfrage aufzurufen. Klicken Sie im Dialogfeld Details auf SQL-Schnittstellenabfrage, um die SQL-Abfrage aufzurufen, die von der Open SQL-Schnittstelle an Looker gesendet wurde.

  • Im explorativen Analysetool Systemaktivitätsverlauf haben Abfragen aus der Open SQL-Schnittstelle den Wert „sql_interface“ für die Quelle. Der Wert Nutzer-E-Mail-Adresse enthält die E-Mail-Adresse des Looker-Nutzers, der die Abfrage ausgeführt hat. Sie können direkt zum Explore Verlauf gehen, gefiltert nach „sql_interface“ indem Sie die Adresse Ihrer Looker-Instanz am Anfang dieser URL einfügen:

    https://Looker instance URL/explore/system__activity/history?fields=history.source,history.completed_date&f[history.source]=sql_interface

Repository für Abhängigkeiten von Drittanbietern

Über den folgenden Link erhalten Sie Zugriff auf das von Google gehostete Repository für Drittanbieterabhängigkeiten, die vom Looker JDBC-Treiber verwendet werden:

https://third-party-mirror.googlesource.com/looker_sql_interface/+/refs/heads/master/third_party/