Cursor-Objekt¶

Cursor.__enter__()¶

Der Einstiegspunkt für den Cursor als Kontextmanager. Es kehrt selbst zurück.

Cursor.__exit__()¶

Der Austrittspunkt für den Cursor als Kontextmanager. Es schließt den Cursor.

Cursor.arraysize¶

Dieses Schreib- / Leseattribut kann verwendet werden, um die Anzahl der Zeilen intern abzustimmen, die durch interne Aufrufe der Datenbank abgerufen und gepuffert werden, wenn Zeilen aus SELECT-Anweisungen und REF-CURSOR abgerufen werden. Der Wert kann die Leistung einer Abfrage drastisch beeinflussen, da er sich direkt auf die Anzahl der Netzwerkrundfahrten zwischen Python und der Datenbank auswirkt. Bei Methoden wiefetchone() und fetchall() ändert sich nicht, wie viele Zeilen an die Anwendung zurückgegeben werden. Fürfetchmany() ist dies die Standardanzahl der abzurufenden Zeilen.

Aufgrund der Leistungsvorteile ist der Standardwert Cursor.arraysize 100 anstelle der von der DB-API empfohlenen 1. Dieser Wert bedeutet, dass 100 Zeilen von jedem internen Aufruf der Datenbank abgerufen werden.

Weitere Informationen finden Sie unter Optimieren der Abrufleistung.

Cursor.bindarraysize¶

Dieses Schreib-Lese-Attribut gibt die Anzahl der Zeilen an, die gleichzeitig gebunden werden sollen, und wird beim Erstellen von Variablen über setinputsizes() odervar() verwendet. Standardmäßig ist 1, was bedeutet, dass jeweils eine einzelne Zeile gebunden wird.

Cursor.arrayvar( Datentyp, Wert)¶

Erstellen Sie eine Array-Variable, die dem Cursor des angegebenen Typs und der angegebenen Größe zugeordnet ist, und geben Sie ein Variablenobjekt zurück. Der Wert ist entweder ein Integer, der die Anzahl der zuzuweisenden Elemente angibt, oder es handelt sich um eine Liste, und die Anzahl der zugewiesenen Elemente wird aus der Größe der Liste gezogen. Wenn thevalue eine Liste ist, wird die Variable auch mit dem Inhalt der Liste festgelegt. Wenn die Größe nicht angegeben ist und der Typ ein String oder binär ist, werden 4000 Bytes zugewiesen. Dies wird benötigt, um Arrays an PL / SQL zu übergeben (in Fällen, in denen die Liste leer ist und der Typ nicht automatisch bestimmt werden kann) oder Arrays aus PL / SQL zurückzugeben.

Array-Variablen können nur für assoziative PL / SQL-Arrays mit zusammenhängenden Schlüsseln verwendet werden. Für assoziative PL / SQL-Arrays mit dünn besiedelten Schlüsseln oder für Varrays und verschachtelte Tabellen muss der in diesem Beispiel gezeigte Ansatz verwendet werden.

Cursor.bindnames()¶

Gibt die Liste der an die Anweisung gebundenen Bind-Variablennamen zurück. Beachten Sie, dass astatement zuerst vorbereitet worden sein muss.

Cursor.bindvars¶

Dieses schreibgeschützte Attribut stellt die für lastexecute verwendeten Bindungsvariablen bereit. Der Wert wird entweder eine Liste oder ein Wörterbuch sein, abhängig vonob die Bindung nach Position oder Name erfolgte. Vorsicht ist geboten, wennreferenzierung dieses Attributs. Insbesondere sollten Elemente nicht entfernt werdenoder ersetzt.

Cursor.callfunc( name, ReturnType, parameters=, keywordParameters={})¶

Ruft eine Funktion mit dem angegebenen Namen auf. Der Rückgabetyp wird in derselben Notation angegeben, wie sie von setinputsizes() benötigt wird. Thesequence von Parametern muss einen Eintrag für jeden Parameter enthalten, die thefunction erwartet. Alle Schlüsselwortparameter werden nach den Positionsparametern eingefügt. Das Ergebnis des Aufrufs ist der Rückgabewert von thefunction.

Ein Beispiel finden Sie unter Gespeicherte PL/SQL-Funktionen.

Cursor.callproc( name, parameters=, keywordParameters={})¶

Rufen Sie eine Prozedur mit dem angegebenen Namen auf. Die Reihenfolge der Parameter mussenthalten Sie einen Eintrag für jeden Parameter, den die Prozedur erwartet. Das Ergebnis des Aufrufs ist eine modifizierte Kopie der Eingabesequenz. Eingabeparameter bleiben unberührt; Ausgabe- und Eingabe- / Ausgabeparameter werden durch möglicherweise neue Werte ersetzt. Schlüsselwortparameter werden nach den Positionsparametern eingefügt und nicht als Teil der Ausgabesequenz zurückgegeben.

Ein Beispiel finden Sie unter Gespeicherte PL/SQL-Prozeduren.

Cursor.close()¶

Schließen Sie den Cursor jetzt und nicht jedes Mal, wenn __del__ aufgerufen wird. Der Cursorwird von diesem Punkt an unbrauchbar sein; Eine Fehlerausnahme wird ausgelöst, wenn eine Operation mit dem Cursor versucht wird.

Cursor.connection¶

Dieses schreibgeschützte Attribut gibt einen Verweis auf das Verbindungsobjekt zurück, auf dem der Cursor erstellt wurde.

Cursor.description¶

Dieses schreibgeschützte Attribut ist eine Sequenz von Sequenzen mit 7 Elementen. Jede dieser Sequenzen enthält Informationen, die eine Ergebnisspalte beschreiben: (name, type,display_size, internal_size, precision, scale, null_ok). Dieses Attribut ist None für Operationen, die keine Zeilen zurückgeben, oder wenn der Cursor noch keine Operation über die execute() -Methode aufgerufen hat.

Der Typ ist eine der auf Modulebene definierten Datenbanktypkonstanten.

Cursor.execute( anweisung, **keywordParameters)¶

Führt eine Anweisung für die Datenbank aus. Siehe SQL-Ausführung.

Parameter können als Wörterbuch oder Sequenz oder als Schlüsselwortparameter übergeben werden. Wenn die Parameter ein Wörterbuch sind, werden die Werte an name gebunden, und wenn die Parameter eine Sequenz sind, werden die Werte an position gebunden. Beachten Sie, dass, wenn die Werte an Position gebunden sind, die Reihenfolge der Variablen von links nach rechts ist, wie sie in der Anweisung vorkommen, und SQL-Anweisungen anders verarbeitet werden als PL / SQL-Anweisungen. Aus diesem Grund wird im Allgemeinen empfohlen, Parameter nach Namen anstatt nach Position zu binden.

Parameter, die als Wörterbuch übergeben werden, sind Name- und Wertepaare. Der Name wird dem von der Anweisung verwendeten Namen der Bindungsvariablen zugeordnet, und der Wert wird dem Python-Wert zugeordnet, den Sie an diese Bindungsvariable binden möchten.

Ein Verweis auf die Anweisung wird vom Cursor beibehalten. Wenn None oder thesame string Objekt erneut übergeben wird, führt der Cursor thatstatement erneut aus, ohne eine Vorbereitung oder Neubindung und Neudefinition durchzuführen.Dies ist am effektivsten für Algorithmen, bei denen dieselbe Anweisung verwendet wird, aberverschiedene Parameter sind daran gebunden (viele Male). Beachten Sie, dass Parameter, die bei nachfolgenden Ausführungen nicht übergeben werden, den Wert behalten, der bei der letzten Ausführung übergeben wurde, die sie enthielt.

Für maximale Effizienz bei der Wiederverwendung einer Anweisung ist es am besten, die Methodesetinputsizes() zu verwenden, um die Parametertypen und-größen im Voraus anzugeben; insbesondere wird angenommen, dass None eine Zeichenfolge der Länge 1 ist, sodass alle Werte, die später als Zahlen oder Datumsangaben gebunden werden, eine TypeError-Ausnahme auslösen.

Wenn es sich bei der Anweisung um eine Abfrage handelt, wird der Cursor als Annehmlichkeit an thecaller zurückgegeben (sodass er direkt als Iterator über die Zeilen in thecursor verwendet werden kann); Andernfalls wird None zurückgegeben.

Cursor.executemany( anweisung, Parameter, batcherrors=False, arraydmlrowcounts=False)¶

Bereiten Sie eine Anweisung für die Ausführung in einer Datenbank vor und führen Sie sie dann gegen alle Parameterzuordnungen oder Sequenzen in den sequenceparameters aus. Siehe Ausführung von Batch-Anweisungen und Massenladen.

Die Anweisung wird auf dieselbe Weise verwaltet, wie sie von der Methode execute() verwaltet wird. Wenn die Größe der Puffer für einen derparameter überschreitet 2 GB, erhalten Sie den Fehler „DPI-1015: array sizeof <n> is too large“ , wobei <n> mit der Größe jedes Elements variiert, das im Puffer zugewiesen wird. Wenn Sie diesen Fehler erhalten, verringern Sie die Anzahl derElemente in den Sequenzparametern.

Wenn keine Parameter vorhanden sind oder Parameter zuvor gebunden wurden, kann die Anzahl der Iterationen als Ganzzahl angegeben werden, anstatt eine Liste leerer Zuordnungen oder Sequenzen bereitzustellen.

Wenn true, aktiviert der Parameter batcherrors die Unterstützung von Stapelfehlern innerhalb von Oracle und stellt sicher, dass der Aufruf auch dann erfolgreich ist, wenn eine Ausnahme in einem oder mehreren der Parameterfolgen auftritt. Die Fehler können dann mit getbatcherrors() behoben werden.

Wenn true, ermöglicht der Parameter arraydmlrowcounts, dass die Anzahl der DML-Zeilen nach Abschluss der Methode von Oracle abgerufen wird. Die Zeilenanzahl kann dann mit getarraydmlrowcounts() abgerufen werden.

Sowohl der Parameter batcherrors als auch der Parameter arraydmlrowcounts können nur wahr sein, wenn eine insert-, update-, delete- oder Merge-Anweisung ausgeführt wird; in allen anderen Fällen wird ein Fehler ausgelöst.

Für maximale Effizienz ist es am besten, diesetinputsizes() -Methode zu verwenden, um die Parametertypen und-größen im Voraus anzugeben. insbesondere wird angenommen, dass None eine Zeichenfolge der Länge 1 ist, sodass alle Werte, die später als Zahlen oder Datumsangaben gebunden werden, eine TypeError-Ausnahme auslösen.

Cursor.executemanyprepared( numIters)¶

Führen Sie die zuvor vorbereitete und gebundene Anweisung die angegebene Anzahl von Malen aus. Die Variablen, die gebunden sind, müssen bereits auf ihren gewünschten Wert gesetzt worden sein, bevor dieser Aufruf erfolgt. Diese Methode wurde für den Fall entwickelt, dass eine optimale Leistung erforderlich ist, da dies zu Lasten der Kompatibilität mit der DB-API geht.

Cursor.fetchall()¶

Ruft alle (verbleibenden) Zeilen eines Abfrageergebnisses ab und gibt sie als Liste von Tupeln zurück. Eine leere Liste wird zurückgegeben, wenn keine Zeilen mehr verfügbar sind. Beachten Sie, dass das Arraysize-Attribut des Cursors die Leistung dieser Operation beeinflussen kann, da intern Lesevorgänge aus der Datenbank in Batches ausgeführt werden, die der arraysize entsprechen.

Eine Ausnahme wird ausgelöst, wenn der vorherige Aufruf von execute()keine Ergebnismenge erzeugt hat oder noch kein Aufruf ausgegeben wurde.

Ein Beispiel finden Sie unter Abrufmethoden.

Cursor.fetchmany()¶

Ruft den nächsten Satz von Zeilen eines Abfrageergebnisses ab und gibt eine Liste von tuples.An leere Liste wird zurückgegeben, wenn keine Zeilen mehr verfügbar sind. Beachten Sie, dass das arraysize-Attribut von thecursor die Leistung dieses Vorgangs beeinflussen kann.

Die Anzahl der abzurufenden Zeilen wird durch den Parameter angegeben. Wenn dies nicht der Fall ist, bestimmt das arraysize-Attribut des Cursors die Anzahl der abzurufenden Zeilen. Wenn die Anzahl der zum Abrufen verfügbaren Zeilen geringer ist als die angeforderte Anzahl, werden weniger Zeilen zurückgegeben.

Eine Ausnahme wird ausgelöst, wenn der vorherige Aufruf von execute()keine Ergebnismenge erzeugt hat oder noch kein Aufruf ausgegeben wurde.

Ein Beispiel finden Sie unter Abrufmethoden.

Cursor.fetchone()¶

Ruft die nächste Zeile einer Abfrageergebnismenge ab und gibt ein einzelnes Tupel oder keines zurück, wenn keine Daten mehr verfügbar sind.

Eine Ausnahme wird ausgelöst, wenn der vorherige Aufruf von execute()keine Ergebnismenge erzeugt hat oder noch kein Aufruf ausgegeben wurde.

Ein Beispiel finden Sie unter Abrufmethoden.

Cursor.fetchraw()¶

Ruft den nächsten Satz von Zeilen eines Abfrageergebnisses in die internen Puffer der definierten Variablen für den Cursor ab. Die Anzahl der tatsächlich abgerufenen Zeilenwird zurückgegeben. Diese Methode wurde für den Fall entwickelt, in dem eine optimale Leistung erforderlich ist, da dies auf Kosten der Kompatibilität mit der DB-API geht.

Eine Ausnahme wird ausgelöst, wenn der vorherige Aufruf von execute()keine Ergebnismenge erzeugt hat oder noch kein Aufruf ausgegeben wurde.

Cursor.fetchvars¶

Dieses schreibgeschützte Attribut gibt die Liste der Variablen an, die für dieletzte Abfrage, die auf dem Cursor ausgeführt wurde. Vorsicht ist geboten, wennreferenzierung dieses Attributs. Insbesondere sollten Elemente nicht entfernt werdenoder ersetzt.

Cursor.getarraydmlrowcounts()¶

Rufen Sie die DML-Zeilenzahlen nach einem Aufruf von executemany()mit aktiviertem arraydmlrowcounts ab. Dies gibt eine Liste von Ganzzahlen zurück, die der Anzahl der Zeilen entspricht, die von der DML-Anweisung für jedes Element des an executemany() übergebenen Arrays betroffen sind.

Cursor.getbatcherrors()¶

Rufen Sie die Ausnahmen ab, die nach einem Aufruf vonexecutemany() mit aktivierten batcherrors stattgefunden haben. Dies gibt eine Liste von Fehlerobjekten zurück, einen Fehler für jede fehlgeschlagene Iteration. Der Offset kann durch Betrachten des Offset-Attributs des Fehlerobjekts ermittelt werden.

Cursor.getimplicitresults()¶

Gibt eine Liste von Cursorn zurück, die impliziten Ergebnissen entsprechen, die aus einem PL / SQL-Block oder einer Prozedur ohne Verwendung der Parameter refcursor verfügbar sind. Der PL/SQL-Block oder die PL/SQL-Prozedur öffnet die Cursor und bereitet sie mit der Prozedur dbms_sql auf die Rückgabe an den Client vor.return_result. Cursor, die auf diese Weise zurückgegeben werden, sollten nicht seingeschlossen. Sie werden automatisch vom übergeordneten Cursor geschlossen, wenn er geschlossen wird. Durch Schließen des übergeordneten Cursors werden die von dieser Methode zurückgegebenen Cursor ungültig.

Cursor.inputtypehandler¶

Dieses Lese-/ Schreibattribut gibt eine Methode an, die für jeden Wert aufgerufen wird, der an eine Anweisung gebunden ist, die auf dem Cursor ausgeführt wird, und überschreibt das Attribut mit demselben Namen in der Verbindung, falls angegeben. Die Methodensignatur ishandler(cursor, value, arraysize) und der Rückgabewert wird als avariable object oder None erwartet. Wenn dieses Attribut None ist, wird der Wert des Attributs mit demselben Namen in der Verbindung verwendet.

Cursor.__iter__()¶

Gibt den Cursor selbst zurück, der als Iterator verwendet werden soll.

Cursor.lastrowid¶

Dieses schreibgeschützte Attribut gibt die rowid der letzten von thecursor geänderten Zeile zurück. Wenn keine Zeile durch die letzte auf thecursor durchgeführte Operation geändert wurde, wird der Wert None zurückgegeben.

Cursor.outputtypehandler¶

Dieses Read-Write-Attribut gibt eine Methode an, die für jede Spalte aufgerufen wird, die von diesem Cursor abgerufen werden soll. Die Methodensignatur ishandler(cursor, name, defaultType, length, precision, scale) und der returnvalue wird als Variablenobjekt oder None erwartet. Wenn dieses Attribut None ist, wird stattdessen der Wert des Attributs mit demselben Namen in der Verbindung verwendet.

Siehe Ändern abgerufener Datentypen mit Ausgabetyphandlern.

Cursor.parse( anweisung)¶

Dies kann verwendet werden, um eine Anweisung zu analysieren, ohne sie tatsächlich auszuführen (dieser Schritt wird von Oracle automatisch ausgeführt, wenn eine Anweisung ausgeführt wird).

Cursor.prefetchrows¶

Dieses Schreib-/ Leseattribut kann verwendet werden, um die Anzahl der Zeilen zu optimieren, die die Pinnacle-Clientbibliothek abruft, wenn eine SELECT-Anweisung ausgeführt wird. Thisvalue kann die Anzahl der Roundtrips zur Datenbank reduzieren, die zum Abrufen von Zeilen erforderlich sind, jedoch auf Kosten des zusätzlichen Speichers. Das Setzen dieses Werts auf 0 kann nützlich sein, wenn das Timing von Abrufen explizit gesteuert werden muss.

Weitere Informationen finden Sie unter Optimieren der Abrufleistung.

Cursor.prepare( anweisung)¶

Dies kann vor einem Aufruf von execute() verwendet werden, um die auszuführende Anweisung zu definieren. Wenn dies erledigt ist, wird die Vorbereitungsphase nicht ausgeführt, wenn der Aufruf von execute() mit keinem oder demselben String-Objekt wie die Anweisung erfolgt. Wenn angegeben, wird thestatement mit dem angegebenen Tag an den Anweisungscache zurückgegeben. Weitere Informationen zum Anweisungscache finden Sie in der Oracle-Dokumentation.

Weitere Informationen finden Sie unter Zwischenspeichern von Anweisungen.

Cursor.rowcount¶

Dieses schreibgeschützte Attribut gibt die Anzahl der Zeilen an, die aktuell vom Cursor abgerufen wurden (für select-Anweisungen), die von der Operation betroffen waren (für insert, update, delete und mergestatements) oder die Anzahl der erfolgreichen Ausführungen der Anweisung (für PL / SQL-Anweisungen).

Cursor.rowfactory¶

Dieses Lese-/ Schreibattribut gibt eine Methode an, die für jede Zeile aufgerufen werden soll, die aus der Datenbank abgerufen wird. Normalerweise wird für jede Zeile ein Tupel zurückgegeben, aber wenn dieses Attribut festgelegt ist, wird die Methode mit dem Tupel aufgerufen, das normalerweise zurückgegeben werden würde, und das Ergebnis der Methode wird stattdessen zurückgegeben.

Siehe Ändern von Abfrageergebnissen mit Rowfactories.

Cursor.scroll( value=0, mode=“relative“)¶

Scrollen Sie den Cursor in der Ergebnismenge an eine neue Position entsprechend dermode.

Wenn mode „relativ“ ist (der Standardwert), wird der Wert als Offset zur aktuellen Position in der Ergebnismenge genommen. Wenn auf „absolut“ gesetzt, gibt valuestates eine absolute Zielposition an. Wenn auf „first“ gesetzt, wird der Cursor in der ersten Zeile positioniert und wenn auf „last“ gesetzt, wird der Cursor auf die letzte Zeile in der Ergebnismenge gesetzt.

Ein Fehler wird ausgelöst, wenn der Modus „relativ“ oder „absolut“ ist und die scrolloperation den Cursor außerhalb der Ergebnismenge positionieren würde.

Cursor.scrollable¶

Dieses boolesche Attribut zum Lesen und Schreiben gibt an, ob der Cursor gescrollt werden kann oder nicht. Standardmäßig sind Cursor nicht scrollbar, da die Serverressourcen und Antwortzeiten größer sind als nicht scrollbare Cursor. Dieses Attribut wird beim Aufruf der Methode execute() überprüft und der entsprechende Modus in Oracle festgelegt.

Cursor.setinputsizes(* args, **keywordArgs)¶

Dies kann vor einem Aufruf von execute(),callfunc() oder callproc() verwendet werden, um Speicherbereiche für die Parameter der Operation vorzudefinieren. Jeder Parameter sollte atype Objekt sein, das der zu verwendenden Eingabe entspricht, oder aninteger , das die maximale Länge eines Zeichenfolgenparameters aninteger . Verwenden Sie keywordparameters beim Binden nach Name und Positionsparameter beim Binden nachposition. Der Singleton None kann als Parameter verwendet werden, wenn usingpositional Parameter , um anzuzeigen, dass kein Platz für thatposition reserviert werden soll.

Cursor.setoutputsize( size)¶

Diese Methode bewirkt nichts und wird ausschließlich aus Gründen der Kompatibilität mit der SQL-API beibehalten. Das Modul weist automatisch so viel Speicherplatz zu, wie benötigt wird, um lange und LANGE Rohspalten (oder CLOB als String und BLOB als Bytes) abzurufen.

Cursor.statement¶

Dieses schreibgeschützte Attribut stellt das String-Objekt bereit, das zuvor mit prepare() vorbereitet oder mitexecute() ausgeführt wurde.

Cursor.var( Datentyp)¶

Erstellen Sie eine Variable mit den angegebenen Eigenschaften. Diese Methode wurde für die Verwendung mit PL / SQL In / Out-Variablen entwickelt, bei denen die Länge oder der Typ nicht automatisch aus dem übergebenen Python-Objekt bestimmt werden kann, oder für die Verwendung in Eingabe- und Ausgabetyphandlern, die für Cursor oder Verbindungen definiert sind.

Der Parameter DataType gibt den Datentyp an, der in der Variablen gespeichert werden soll. Dies sollte eine der Database-Typkonstanten, DB API-Konstanten, ein von der Methode Connection.gettype() zurückgegebener Objekttyp oder einer der folgenden Python-Typen sein:

Python-Typ	Datenbanktyp
bool	cx_Oracle.DB_TYPE_BOOLEAN
bytes	cx_Oracle.DB_TYPE_RAW
datum / Uhrzeit.datum	cx_Oracle.DB_TYPE_DATE
datum / Uhrzeit.datetime	cx_Oracle.DB_TYPE_DATE
datum / Uhrzeit.timedelta	cx_Oracle.DB_TYPE_INTERVAL_DS
dezimal.Dezimal	cx_Oracle.DB_TYPE_NUMBER
schwimmer	cx_Oracle.DB_TYPE_NUMBER
int	cx_Oracle.DB_TYPE_NUMBER
str	cx_Oracle.DB_TYPE_VARCHAR

Der Parameter size gibt die Länge von String- und Rohvariablen an und wird in allen anderen Fällen ignoriert. Wenn nicht für String- und Raw-Variablen angegeben, wird der Wert 4000 verwendet.

Der Parameter arraysize gibt die Anzahl der Elemente an, die die Variable haben soll. Wenn nicht angegeben, wird die Bind-Array-Größe (normalerweise 1) verwendet. Wenn avariable in einem Ausgabetyphandler erstellt wird, sollte dieser Parameter auf die Array-Größe des Cursors gesetzt werden.

Die Parameter inconverter und outconverter geben Methoden zum Konvertieren von Werten in/aus der Datenbank an. Weitere Informationen finden Sie im Abschnitt über variable Objekte.

Der Parameter typename gibt den Namen eines SQL-Objekttyps an und muss bei Verwendung des Typs cx_Oracle.OBJECT angegeben werden, es sei denn, der Typ objectwurde direkt als erster Parameter übergeben.

Der Parameter encodingErrors gibt an, was passieren soll, wenn aus der Datenbank abgerufene Byte-Zeichenfolgen in Zeichenfolgen dekodiert werden. Es sollte einer der in der builtindecodefunction angegebenen Werte sein.