ipython-sql#

ipython-sql führt die %sql oder %%sql-Magics für iPython und Jupyter Notebooks ein.

Installation#

Ihr könnt ipython-sql einfach in eurem Jupyter-Kernel installieren mit:

$ pipenv install ipython-sql

Erste Schritte#

  1. Zunächst wird ipython-sql in eurem Notebook aktiviert mit

    In [1]: %load_ext sql
    
  2. Für die Verbindung zur Datenbank wird die SQLAlchemy URL verwendet:

    In [2]: %sql postgresql://
    
  3. Anschließend könnt ihr eine Tabelle erstellen, z.B.:

    In [3]: %%sql postgresql://
       ....: CREATE TABLE accounts (login, name, email)
       ....: INSERT INTO accounts VALUES ('veit', 'Veit Schiele', veit@example.org);
    
  4. Die Inhalte der Tabelle accounts könnt ihr abfragen mit

    In [4]: result = %sql select * from accounts
    

Konfiguration#

Abfrageergebnisse werden als Liste geladen sodass sehr große Datenmengen den Arbeitsspeicher belegen können. Üblicherweise gibt es keine automatische Begrenzung, mit Autolimit lässt sich jedoch die Ergebnismenge limitieren.

Bemerkung

displaylimit begrenzt nur die Menge der angezeigten Ergebnisse, nicht jedoch den Speicherbedarf.

Mit %config SqlMagic könnt ihr Euch die aktuelle Konfiguration ausgeben lassen:

In [5]: %config SqlMagic
SqlMagic options
--------------
SqlMagic.autocommit=<Bool>
    Current: True
    Set autocommit mode
SqlMagic.autolimit=<Int>
    Current: 0
    Automatically limit the size of the returned result sets
SqlMagic.autopandas=<Bool>
    Current: False
    Return pandas DataFrames instead of regular result sets
...

Bemerkung

Wenn autopandas auf True gesetzt wurde, wird displaylimit nicht angewendet. In diesem Fall kann die max_rows-Option von pandas verwendet werden wie in der pandas-Dokumentation beschrieben.

pandas#

Wenn pandas installiert ist, kann die DataFrame-Methode verwendet werden:

In [6]: result = %sql SELECT * FROM accounts

In [7]: dataframe = result.DataFrame()

In [8]: %sql --persist dataframe

In [9]: %sql SELECT * FROM dataframe;
--persist

Argument mit dem Namen eines DataFrame-Objekts, erstellt aus diesem einen Tabellennahmen in der Datenbank.

--append

Argument um in einer vorhandenen Tabelle Zeilen mit diesem namen hinzuzufügen.

PostgreSQL-Funktionen#

Meta-Befehle von psql lassen sich auch in ipython-sql verwenden:

-l, --connections

listet alle aktiven Verbindungen auf

-x, --close SESSION-NAME

schließt benannte Verbindung

-c, --creator CREATOR-FUNCTION

gibt die Creator-Funktion für eine neue Verbindung an

-s, --section SECTION-NAME

gibt Abschnitt von dsn_file an, der in einer Verbindung verwendet werden soll

-p, --persist

erstellt aus einem benannten DataFrame eine Tabelle in der Datenbank

--append

ähnlich wie --persist, die Inhalte werden jedoch an die Tabelle angehängt

-a, --connection_arguments "{connection arguments}"

gibt ein Dict von Verbindungsargumenten an, die an den SQL-Treiber übergeben werden

-f, --file PATH

führt SQL aus der Datei unter diesem Pfad aus

Siehe auch

Warnung

Da ipython-sql ---Optionen wie z.B. --persist verarbeitet, und gleichzeitig -- als SQL-Kommentar akzeptiert, muss der Parser einige Annahmen treffen: so wird z.B. --persist is great in der ersten Zeile als Argument und nicht als Kommentar verarbeitet.