Zum Inhalt springen
DuckDBDuckDBDuckDB
Deutsch

ODBC-Erweiterungsfunktionen

odbc_begin_transaction

odbc_begin_transaction(conn_handle BIGINT) -> VARCHAR

Setzt das Attribut SQL_ATTR_AUTOCOMMIT auf SQL_AUTOCOMMIT_OFF auf der angegebenen Verbindung und startet damit effektiv eine implizite Transaktion. odbc_commit oder odbc_rollback müssen auf einer solchen Verbindung aufgerufen werden, um die Transaktion abzuschließen. Der Abschluss startet eine weitere implizite Transaktion auf dieser Verbindung. Siehe Transaktionsverwaltung für Details.

Parameter:

  • conn_handle (BIGINT): ODBC-Verbindungshandle, erzeugt mit odbc_connect

Rückgabewert:

Gibt immer NULL (VARCHAR) zurück.

Beispiel:

SELECT odbc_begin_transaction(getvariable('conn'))

odbc_bind_params

odbc_bind_params(conn_handle BIGINT, params_handle BIGINT, params STRUCT) -> BIGINT

Bindet die angegebenen Parameterwerte an das angegebene Parameter-Handle. Nur bei zweistufiger Parameterbindung erforderlich, siehe Abfrageparameter für Details.

Parameter:

  • conn_handle (BIGINT): ODBC-Verbindungshandle, erzeugt mit odbc_connect
  • params_handle (BIGINT): Parameter-Handle, erzeugt mit odbc_create_params
  • params (STRUCT): Parameterwerte

Rückgabewert:

Parameter-Handle (BIGINT), dasselbe, das als zweites Argument übergeben wurde.

Beispiel:

SELECT odbc_bind_params(getvariable('conn'), getvariable('params1'), row(42, 'foo'))

odbc_close

odbc_close(conn_handle BIGINT) -> VARCHAR

Schließt die angegebene ODBC-Verbindung zu einer Remote-DB. Wirft keine Fehler, wenn die Verbindung bereits geschlossen ist.

Parameter:

  • conn_handle (BIGINT): ODBC-Verbindungshandle, erzeugt mit odbc_connect

Rückgabewert:

Gibt immer NULL (VARCHAR) zurück.

Beispiel:

SELECT odbc_close(getvariable('conn'))

odbc_commit

odbc_commit(conn_handle BIGINT) -> VARCHAR

Ruft SQLEndTran mit dem Argument SQL_COMMIT auf der angegebenen Verbindung auf und schließt die aktuelle Transaktion ab. odbc_begin_transaction muss vor diesem Aufruf auf dieser Verbindung aufgerufen worden sein, damit der Abschluss wirksam wird. Siehe Transaktionsverwaltung für Details.

Parameter:

  • conn_handle (BIGINT): ODBC-Verbindungshandle, erzeugt mit odbc_connect

Rückgabewert:

Gibt immer NULL (VARCHAR) zurück.

Beispiel:

SELECT odbc_commit(getvariable('conn'))

odbc_connect

odbc_connect(conn_string VARCHAR) -> BIGINT
odbc_connect(conn_string VARCHAR, username VARCHAR, password VARCHAR) -> BIGINT

Öffnet eine ODBC-Verbindung zu einer Remote-DB.

Wenn die (positionalen) Parameter username und password angegeben sind, werden sie als UID und PWD an die Verbindungszeichenkette angehängt.

Parameter:

  • conn_string (VARCHAR): ODBC-Verbindungszeichenkette, die an den Treiber-Manager übergeben wird.

Rückgabewert:

Verbindungshandle, das in einer VARIABLE abgelegt werden kann. Die Verbindung wird nicht automatisch geschlossen und muss mit odbc_close geschlossen werden.

Beispiel:

SET VARIABLE conn = odbc_connect('Driver={Oracle Driver};DBQ=//127.0.0.1:1521/XE;UID=scott;PWD=tiger')
SET VARIABLE conn = odbc_connect('Driver={Oracle Driver};DBQ=//127.0.0.1:1521/XE', 'scott', 'tiger')

odbc_copy

odbc_copy(conn_handle BIGINT, [, <optional named parameters>]) -> TABLE
odbc_copy(conn_string VARCHAR, [, <optional named parameters>]) -> TABLE

Kopiert Zeilen aus einer für DuckDB zugänglichen Datei oder Tabelle in die Remote-DB.

Warning Verwendung von odbc_copy über die Python Relational API.

odbc_copy ist eine Tabellenfunktion, die eine Zeile für jeweils 2048 kopierte Zeilen zurückgibt. Bei Verwendung aus Python mit duckdb.sql() greift die Lazy Evaluation. Es werden also keine Zeilen kopiert, bis eine Methode, die die Ausführung auslöst auf der resultierenden Relation aufgerufen und alle Ergebniszeilen verarbeitet wurden.

Parameter:

  • conn_handle_or_string (BIGINT oder VARCHAR), eines von:
    • ODBC-Verbindungshandle, erzeugt mit odbc_connect
    • ODBC-Verbindungszeichenkette, vorgesehen für einmalige Abfragen; in diesem Fall wird eine neue ODBC-Verbindung geöffnet und nach Abschluss der Abfrage automatisch geschlossen

Optionale benannte Parameter (Quelle):

Die Quellabfrage wird über eine separate DB-Instanz ausgeführt, nicht über die Instanz, auf der odbc_copy aufgerufen wird. Daher kann sich source_query nicht auf bereits vorhandene In-Memory-Tabellen beziehen und kann derzeit geöffnete DuckDB-Dateien nicht öffnen. Als Workaround wird für komplexe Quellabfragen empfohlen, das Abfrageergebnis zuerst in eine lokale Parquet-Datei zu exportieren und anschließend odbc_copy auf dieser Datei auszuführen.

  • source_conn_string (VARCHAR, Standard: :memory:): DuckDB-Verbindungszeichenkette zur Quell-DB, Beispiel: ducklake:postgres:postgresql://username:[email protected]:5432/lake1
  • source_file (VARCHAR): Pfad zu einer Parquet-, CSV- oder JSON-Datei (remote oder lokal), die mit DuckDB gelesen werden soll, Beispiel: https://blobs.duckdb.org/nl_stations.csv, entspricht source_query='SELECT * FROM '<source_file>'
  • source_query (VARCHAR): DuckDB-SQL-Abfrage zum Lesen der Daten, Beispiel: FROM nl_train_stations
  • source_queries (LIST(VARCHAR)): mehrere DuckDB-SQL-Abfragen, die nacheinander ausgeführt werden; die letzte Abfrage muss die zu kopierende Ergebnismenge liefern, Ergebnisse vorheriger Abfragen werden verworfen, Ergebnisse aller Abfragen werden im Speicher materialisiert, Beispiel:
source_queries=[
  'CREATE SECRET s (TYPE s3 [...])',
  'FROM nl_train_stations'
],
  • source_limit (UBIGINT, Standard: 0): die Anzahl der Datensätze, die auf einmal aus der Quellabfrage/-datei gelesen werden sollen; wenn diese Option angegeben ist, wird die Quellabfrage mehrfach ausgeführt und dabei LIMIT <limit> OFFSET <offset> angehängt; muss größer oder gleich 2048 sein, 2048 muss ohne Rest durch diesen Wert teilbar sein

Optionale benannte Parameter (Ziel):

  • dest_table (VARCHAR): Zieltabellenname in der Remote-DB, wird in INSERT- und CREATE TABLE-Abfragen verwendet, darf nicht angegeben werden, wenn dest_query angegeben ist; verschiedene DBs haben unterschiedliche Regeln zur Groß-/Kleinschreibung und zur Standardschreibweise, daher muss der Name der Zieltabelle möglicherweise in Großbuchstaben angegeben werden: TAB1 oder in zitierter Form: "tab1" (oder mit Schema-Namen: "schema1"."tab1")
  • dest_query (VARCHAR): Abfrage, die in der Remote-DB für jeden Quellbatch ausgeführt werden soll; muss die Anzahl der ODBC-Parameterplatzhalter ? gleich source_columns_count * batch_size haben, darf nicht angegeben werden, wenn dest_table angegeben ist, Beispiel: CALL import_city(?,?,?,?)
  • dest_query_single (VARCHAR): wird nur verwendet, wenn batch_size>0 und die Anzahl der im letzten Quellbatch gelesenen Zeilen kleiner als batch_size ist; in diesem Fall statt dest_query verwendet, muss die Anzahl der ODBC-Parameterplatzhalter ? gleich source_columns_count haben

Optionale benannte Parameter (Tabelle erstellen):

  • create_table (BOOLEAN, Standard: FALSE): ob in der Remote-Zieldatenbank eine Tabelle anhand der Spaltennamen und Spaltentypen der Quellabfrage erstellt werden soll; implementiert effektiv CTAS (create table as select)
  • column_types (MAP(VARCHAR, VARCHAR)): wenn create_table=TRUE angegeben ist, ermöglicht das Bereitstellen/Überschreiben der Typzuordnung zwischen Quell-DuckDB-Typen und Ziel-RDBMS-Typen, Beispiel:
create_table=TRUE,
column_types=MAP {
    'DUCKDB_TYPE_VARCHAR': 'VARCHAR2(10)',
    'DUCKDB_TYPE_DECIMAL': 'NUMBER({typmod1},{typmod2})'}
  • column_quotes (VARCHAR, Standard: "): Anführungszeichen (oder Zeichenkette), mit dem Spaltennamen in den erzeugten CREATE TABLE- und INSERT-Abfragen zitiert werden
  • commit_after_create_table (BOOLEAN, Standard: FALSE): ob nach dem Ausführen von CREATE TABLE ein COMMIT ausgegeben werden soll; für Firebird automatisch aktiviert

Optionale benannte Parameter (Behandlung von Abfrageparametern):

  • decimal_params_as_chars (BOOLEAN, Standard: false): DECIMAL-Parameter als VARCHARs übergeben
  • integral_params_as_decimals (BOOLEAN, Standard: false): (vorzeichenlose) TINYINT-, SMALLINT-, INTEGER- und BIGINT-Parameter als SQL_C_NUMERIC übergeben.

Optionale benannte Parameter (weitere):

  • batch_size (UINTEGER, Standard: 16): Anzahl der Datensätze, die in einem einzelnen SQLExecute-ODBC-Aufruf in die Remote-DB eingefügt (oder im Fall von dest_query ausgeführt) werden; erlaubte Werte: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048
  • use_insert_all (BOOLEAN, Standard: FALSE): Batch-Insert-Abfrage INSERT ALL statt Batch-Insert mit INSERT ... VALUES (...), (...), ... (...) erzeugen; für Oracle automatisch aktiviert
  • use_insert_union (BOOLEAN, Standard: FALSE): Batch-Insert-Abfrage INSERT ... SELECT FROM ... UNION ALL ... statt Batch-Insert mit INSERT ... VALUES (...), (...), ... (...) erzeugen; für Firebird automatisch aktiviert
  • dummy_table_name (VARCHAR): Name der Dummy-Tabelle für INSERT ALL- und INSERT UNION-Abfragen, dual für Oracle
  • copy_in_transaction (BOOLEAN, Standard: TRUE): eine Transaktion in der Remote-DB für diesen Copy-Aufruf beginnen, die Transaktion committen, wenn alle Zeilen verarbeitet sind, bei Fehler zurückrollen
  • max_records_in_transaction (UBIGINT, Standard: 0): wenn angegeben, wird die Remote-Transaktion jedes Mal committet, nachdem die angegebene Anzahl von Zeilen verarbeitet wurde
  • close_connection (BOOLEAN, Standard: false): schließt die übergebene Verbindung nach Abschluss des Funktionsaufrufs; vorgesehen für einmalige Aufrufe von odbc_copy

Rückgabewert:

Eine Tabelle mit den folgenden Spalten:

  • completed (BOOLEAN): Flag, ob diese Ausgabezeile die letzte Zeile in der Ergebnismenge ist
  • rows_processed (UBIGINT): Anzahl der aus der Quelle gelesenen Zeilen
  • elapsed_seconds (FLOAT): Anzahl der Sekunden seit Beginn des Kopiervorgangs
  • rows_per_second (FLOAT): Anzahl der in einer Sekunde verarbeiteten Zeilen
  • table_ddl (VARCHAR): erzeugte CREATE TABLE-Abfrage, die in der Remote-DB vor Beginn des Kopiervorgangs ausgeführt wurde

Eine Ergebniszeile wird für jeweils 2048 aus der Quelle gelesene Zeilen ausgegeben. Nur die letzte Zeile hat completed=TRUE und einen nicht-null table_ddl-Wert (nur wenn create_table=TRUE angegeben ist).

Beispiele:

FROM odbc_copy(getvariable('conn'),
  source_file='https://blobs.duckdb.org/nl_stations.csv',
  dest_table='NL_TRAIN_STATIONS',
  create_table=TRUE)
FROM odbc_copy(getvariable('conn'),
  source_conn_string='ducklake:postgres:postgresql://username:[email protected]:5432/lake1',
  source_queries=[
    'CREATE SECRET s (TYPE s3 [...])',
    'FROM nl_train_stations'
  ],
  dest_table='NL_TRAIN_STATIONS',
  create_table=TRUE,
  batch_size=32,
  max_records_in_transaction=42);

odbc_create_params

odbc_create_params() -> BIGINT

Erzeugt ein Parameter-Handle. Nur bei zweistufiger Parameterbindung erforderlich, siehe Abfrageparameter für Details.

Parameter:

Keine.

Rückgabewert:

Parameter-Handle (BIGINT). Wenn das Handle an odbc_query übergeben wird, wird es an das zugrunde liegende Prepared Statement gebunden und automatisch geschlossen, wenn das Statement geschlossen wird.

Beispiel:

SET VARIABLE params1 = odbc_create_params()

odbc_list_data_sources

odbc_list_data_sources() -> TABLE(name VARCHAR, description VARCHAR, type VARCHAR)

Gibt die Liste der im Betriebssystem registrierten ODBC-Datenquellen zurück. Verwendet den Treiber-Manager-Aufruf SQLDataSources.

Parameter:

Keine.

Rückgabewert:

Eine Tabelle mit den folgenden Spalten:

  • name (VARCHAR): Datenquellenname
  • description (VARCHAR): Datenquellenbeschreibung
  • type (VARCHAR): Datenquellentyp, USER oder SYSTEM

Beispiel:

FROM odbc_list_data_sources()

odbc_list_drivers

odbc_list_drivers() -> TABLE(description VARCHAR, attributes MAP(VARCHAR, VARCHAR))

Gibt die Liste der im Betriebssystem registrierten ODBC-Treiber zurück. Verwendet den Treiber-Manager-Aufruf SQLDrivers.

Parameter:

Keine.

Rückgabewert:

Eine Tabelle mit den folgenden Spalten:

  • description (VARCHAR): Treiberbeschreibung
  • attributes (MAP(VARCHAR, VARCHAR)): Treiberattribute als name->value-Map

Beispiel:

FROM odbc_list_drivers()

odbc_query

odbc_query(conn_handle BIGINT, query VARCHAR[, <optional named parameters>]) -> TABLE
odbc_query(conn_string VARCHAR, query VARCHAR[, <optional named parameters>]) -> TABLE

Führt die angegebene Abfrage in einer Remote-DB aus und gibt die Ergebnistabelle der Abfrage zurück.

Parameter:

  • conn_handle_or_string (BIGINT oder VARCHAR), eines von:
    • ODBC-Verbindungshandle, erzeugt mit odbc_connect
    • ODBC-Verbindungszeichenkette, vorgesehen für einmalige Abfragen; in diesem Fall wird eine neue ODBC-Verbindung geöffnet und nach Abschluss der Abfrage automatisch geschlossen
  • query (VARCHAR): SQL-Abfrage, die an das Remote-DBMS übergeben wird

Optionale benannte Parameter zur Übergabe von Abfrageparametern:

  • params (STRUCT): Abfrageparameter, die an das Remote-DBMS übergeben werden
  • params_handle (BIGINT): Parameter-Handle, erzeugt mit odbc_create_params. Nur bei zweistufiger Parameterbindung verwendet, siehe Abfrageparameter für Details.

Optionale benannte Parameter, die die Typzuordnung ändern können:

Die Erweiterung unterstützt eine Reihe von Optionen, mit denen gesteuert werden kann, wie Abfrageparameter übergeben und wie die Ergebnisdaten behandelt werden. Für bekannte DBs werden diese Optionen automatisch gesetzt. Sie können auch als benannte Parameter an die Funktion odbc_query übergeben werden, um die Autokonfiguration zu überschreiben:

  • decimal_columns_as_chars (BOOLEAN, Standard: false): DECIMAL-Werte als VARCHARs lesen, die vor der Rückgabe an den Client wieder in DECIMALs geparst werden
  • decimal_columns_precision_through_ard (BOOLEAN, Standard: false): beim Lesen eines DECIMAL dessen precision und scale über den „Application Row Descriptor“ angeben
  • decimal_columns_as_ard_type (BOOLEAN, Standard: false): beim Lesen eines DECIMAL SQL_ARD_TYPE statt SQL_C_NUMERIC verwenden
  • decimal_params_as_chars (BOOLEAN, Standard: false): DECIMAL-Parameter als VARCHARs übergeben
  • integral_params_as_decimals (BOOLEAN, Standard: false): (vorzeichenlose) TINYINT-, SMALLINT-, INTEGER- und BIGINT-Parameter als SQL_C_NUMERIC übergeben.
  • reset_stmt_before_execute (BOOLEAN, Standard: false): das Prepared Statement vor der Ausführung zurücksetzen (mit SQLFreeStmt(h, SQL_CLOSE))
  • time_params_as_ss_time2 (BOOLEAN, Standard: false): TIME-Parameter als TIME2-Werte von SQL Server übergeben
  • timestamp_columns_as_timestamp_ns (BOOLEAN, Standard: false): TIMESTAMP-ähnliche Spalten (TIMESTAMP WITH LOCAL TIME ZONE, DATETIME2, TIMESTAMP_NTZ usw.) mit Nanosekunden-Präzision lesen (mit neun Nachkommastellen)
  • timestamp_columns_with_typename_date_as_date (BOOLEAN, Standard: false): TIMESTAMP-Spalten mit dem Typnamen DATE als DuckDB-DATEs lesen
  • timestamp_max_fraction_precision (UTINYINT, Standard: 9): maximale Anzahl der Nachkommastellen beim Lesen einer TIMESTAMP-Spalte mit Nanosekunden-Präzision
  • timestamp_params_as_sf_timestamp_ntz (BOOLEAN, Standard: false): TIMESTAMP-Parameter als TIMESTAMP_NTZ von Snowflake übergeben
  • timestamptz_params_as_ss_timestampoffset (BOOLEAN, Standard: false): TIMESTAMP_TZ-Parameter als DATETIMEOFFSET von SQL Server übergeben
  • var_len_data_single_part (BOOLEAN, Standard: false): lange VARCHAR- oder VARBINARY-Werte in einem einzigen Lesevorgang lesen (wird verwendet, wenn ein Treiber Retrieving Variable-Length Data in Parts nicht unterstützt)
  • var_len_params_long_threshold_bytes (UINTEGER, Standard: 4000): Längenschwelle, ab der SQL_WVARCHAR-Parameter als SQL_WLONGVARCHAR übergeben werden
  • enable_columns_binding (BOOLEAN, Standard: false): ob SQLBindCol statt SQLGetData für festgrößenbasierte Spalten verwendet werden darf

Weitere optionale benannte Parameter:

  • ignore_exec_failure (BOOLEAN, Standard: false): wenn eine Abfrage, die in der Remote-DB ausgeführt wird, erfolgreich vorbereitet werden kann, aber zur Ausführungszeit fehlschlagen kann oder nicht (zum Beispiel wegen des Schema-Zustands wie der Existenz einer Tabelle), kann dieses Flag verwendet werden, um bei fehlgeschlagener Ausführung keinen Fehler zu werfen. Bei fehlgeschlagener Ausführung wird eine leere Ergebnismenge zurückgegeben.
  • close_connection (BOOLEAN, Standard: false): schließt die übergebene Verbindung nach Abschluss des Funktionsaufrufs; vorgesehen für einmalige Aufrufe von odbc_query, Beispiel:
FROM odbc_query(
   odbc_connect('Driver={Oracle Driver};DBQ=//127.0.0.1:1521/XE', 'scott', 'tiger'),
   'SELECT 42 FROM dual',
   close_connection=TRUE);

Rückgabewert:

Eine Tabelle mit dem Abfrageergebnis.

Beispiel:

FROM odbc_query(getvariable('conn'),
  'SELECT CAST(? AS NVARCHAR2(2)) || CAST(? AS VARCHAR2(5)) FROM dual',
  params=row('🦆', 'quack')
)

odbc_rollback

odbc_rollback(conn_handle BIGINT) -> VARCHAR

Ruft SQLEndTran mit dem Argument SQL_ROLLBACK auf der angegebenen Verbindung auf und schließt die aktuelle Transaktion ab. odbc_begin_transaction muss vor diesem Aufruf auf dieser Verbindung aufgerufen worden sein, damit der Abschluss wirksam wird. Siehe Transaktionsverwaltung für Details.

Parameter:

  • conn_handle (BIGINT): ODBC-Verbindungshandle, erzeugt mit odbc_connect

Rückgabewert:

Gibt immer NULL (VARCHAR) zurück.

Beispiel:

SELECT odbc_rollback(getvariable('conn'))

Dies ist eine inoffizielle Website und nicht mit DuckDB verbunden. Offizielle Seite:duckdb.org.duckdb.ubitools.com · Übersetzt und erstellt mit Astro und daisyUI