Cursor Object¶
Cursor.
__enter__
()¶
het invoerpunt voor de cursor als contextbeheerder. Het keert zichzelf terug.
Noot
deze methode is een uitbreiding van de DB API-definitie.
Cursor.
__exit__
()¶
het exitpunt voor de cursor als contextbeheerder. Het sluit de cursor.
Noot
deze methode is een uitbreiding van de DB API-definitie.
Cursor.
arraysize
¶
dit read-write attribuut kan worden gebruikt om het aantal rijen intern af te stemmen geetched en gebufferd door interne aanroepen naar de database bij het ophalen van rijen uit SELECT statements en REF CURSORS. De waarde kan drastisch beà nvloeden de prestaties van een query omdat het direct van invloed op het aantal netwerkround trips tussen Python en de database. Voor methoden alsfetchone()
en fetchall()
verandert het niet hoe veel rijen worden geretourneerd naar de toepassing. Voorfetchmany()
is dit het standaard aantal rijen dat moet worden opgehaald.
vanwege de prestatievoordelen is de standaard Cursor.arraysize
100 in plaats van de 1 die de DB API aanbeveelt. Deze waarde betekent dat 100 rijen worden opgehaald door elke interne aanroep naar de database.
zie Tuning Fetch Performance voor meer informatie.
Cursor.
bindarraysize
¶
dit read-write attribuut specificeert het aantal rijen om op een bepaald moment te binden en wordt gebruikt bij het aanmaken van variabelen via setinputsizes()
ofvar()
. Het staat standaard op 1, Wat betekent dat een enkele rij tegelijk wordt gebonden.
opmerking
de DB API-definitie definieert Dit kenmerk niet.
Cursor.
arrayvar
(datatype, value)¶
Maak een array variabele geassocieerd met de cursor van het gegeven type andsize en retourneer een variabel object. De waarde is ofwel eeninteger die het aantal toe te wijzen elementen specificeert of het is een lijst en het aantal toegewezen elementen wordt getrokken uit de grootte van de lijst. Als de waarde een lijst is, wordt de variabele ook ingesteld met de inhoud van de lijst. Als de grootte niet is opgegeven en het type is een string of binair, 4000 bytesis toegewezen. Dit is nodig om arrays door te geven aan PL/SQL (in gevallen waarin de lijst leeg kan zijn en het type niet automatisch kan worden bepaald) of om arrays van PL / SQL te keren.
Array variabelen kunnen alleen gebruikt worden voor PL/SQL associatieve arrays met aaneengesloten sleutels. Voor PL / SQL associatieve arrays met dunbevolkte keys of voor varrays en geneste tabellen, moet de in dit voorbeeld getoonde aanpak worden gebruikt.
Noot
de DB API-definitie definieert deze methode niet.
Cursor.
bindnames
()¶
retourneer de lijst van bind variabele namen gebonden aan het statement. Merk op dat eerst een verklaring moet zijn opgesteld.
Noot
de DB API-definitie definieert deze methode niet.
Cursor.
bindvars
¶
dit alleen-lezen attribuut bevat de bind variabelen die gebruikt worden voor de lastexecute. De waarde zal ofwel een lijst of een woordenboek zijn, afhankelijk vanof de binding werd gedaan door positie of naam. Voorzichtigheid is geboden bij het verwijzen naar Dit kenmerk. In het bijzonder mogen elementen niet worden verwijderdof vervangen.
opmerking
de DB API-definitie definieert Dit kenmerk niet.
Cursor.
callfunc
(name, returnType, parameters=, keywordParameters = {})¶
roep een functie aan met de opgegeven naam. Het retourtype wordt in dezelfde notatie gespecificeerd zoals vereist door setinputsizes()
. De reeks parameters moet één regel bevatten voor elke parameter die de functie verwacht. Alle trefwoord parameters zullen worden opgenomen na depositionele parameters. Het resultaat van de oproep is de retourwaarde van de functie.
zie PL / SQL opgeslagen functies voor een voorbeeld.
Noot
de DB API-definitie definieert deze methode niet.
opmerking
als u van plan bent Cursor.setinputsizes()
aan te roepen op de cursorprior om deze aan te roepen, merk dan op dat het eerste item in deparameterlijst verwijst naar de retourwaarde van de functie.
Cursor.
callproc
(name, parameters=, keywordParameters = {})¶
roep een procedure aan met de opgegeven naam. De reeks parameters moet één regel bevatten voor elke parameter die de procedure verwacht. Het resultaat van de aanroep is een gewijzigde kopie van de invoerreeks. Inputparameters zijn links onaangeroerd; output en input/output parameters worden vervangen door mogelijk nieuwe waarden. Keyword parameters zullen worden opgenomen na depositionele parameters en worden niet geretourneerd als onderdeel van de output sequence.
zie PL / SQL opgeslagen Procedures voor een voorbeeld.
Noot
de DB API-definitie staat geen sleutelwoordparameters toe.
Cursor.
close
()¶
sluit de cursor nu, in plaats van wanneer _ _ del _ _ wordt aangeroepen. De cursorzal vanaf dit punt onbruikbaar zijn; er zal een Foutenuitzondering ontstaan als een operatie wordt geprobeerd met de cursor.
Cursor.
connection
¶
dit alleen-lezen attribuut geeft een verwijzing terug naar het verbindingsobject waarop de cursor is gemaakt.
Note
deze eigenschap is een uitbreiding van de DB API-definitie, maar wordt in PEP 249 vermeld als een optionele uitbreiding.
Cursor.
description
¶
dit alleen-lezen attribuut is een reeks van 7-item sequenties. Elk van deze sequences bevat informatie die een resultaatkolom beschrijft: (naam, type, display_size, internal_size, precision, scale, null_ok). Deze toewijzing zal geen zijn voor bewerkingen die geen rijen retourneren of als de cursor nog geen bewerking heeft gehad die is aangeroepen via de execute()
methode.
het type zal een van het databasetype constants zijn gedefinieerd op moduleniveau.
Cursor.
execute
(statement, * * keywordParameters)¶
voer een statement uit tegen de database. Zie SQL uitvoering.
Parameters kunnen worden doorgegeven als een woordenboek of sequentie of als sleutelwoordparameters. Als de parameters een woordenboek zijn, worden de waarden gebonden door naam en als de parameters een reeks zijn, worden de waarden gebonden door positie. Merk op dat als de waarden gebonden zijn door positie, de volgorde van de variabelen van links naar rechts is zoals ze worden aangetroffen in de statement en SQL statements anders worden verwerkt dan PL/SQL statements. Om deze reden wordt het over het algemeen aanbevolen om parameters op naam te binden in plaats van OP positie.
Parameters doorgegeven als een woordenboek zijn naam en waarde paren. De naam Maps naar de bind variabele naam die wordt gebruikt door het statement en de waarde maps naar de thon waarde die u wilt gebonden aan die bind variabele.
een verwijzing naar het statement blijft behouden door de cursor. Als er geen of hetzelfde string object opnieuw wordt doorgegeven, zal de cursor die statement opnieuw uitvoeren zonder een prepare of rebinding en herdefiniëring uit te voeren.Dit is het meest effectief voor algoritmen waar hetzelfde statement wordt gebruikt, maar verschillende parameters zijn er (vele malen) aan gebonden. Merk op dat parametersdie niet worden doorgegeven tijdens de volgende executies de waarde behouden die is ingevoerd tijdens de laatste executie die ze bevatte.
voor maximale efficiëntie bij het hergebruiken van een statement, is het het beste om desetinputsizes()
methode te gebruiken om de parametertypen en-afmetingen van tevoren te specificeren; in het bijzonder wordt er niet van uitgegaan dat het een reeks van lengte 1 is, dus alle waarden die later als getallen of datums worden gebonden, zullen een TypeError-uitzondering oproepen.
als het statement Een query is, wordt de cursor geretourneerd voor het gemak van thecaller (zodat het direct kan worden gebruikt als een iterator over de rijen in thecursor); anders wordt None
geretourneerd.
Noot
de DB API-definitie definieert de retourwaarde van deze methode niet.
Cursor.
executemany
(statement, parameters, batcherrors=False, arraydmrowcounts=False)¶
Maak een statement klaar voor uitvoering tegen een database en voer het vervolgens uit tegen alle parametertoewijzingen of sequenties die in de sequenceparameters zijn gevonden. Zie Batch Statement Execution and Bulk Loading.
het statement wordt beheerd op dezelfde manier als de execute()
methode het beheert. Als de grootte van de buffers toegewezen voor een van de parameters groter is dan 2 GB, ontvangt u de fout ” DPI-1015: array sizeof <n> is te groot”, waarbij <n> varieert met de grootte van elk element dat in de buffer wordt toegewezen. Als u deze fout ontvangt, verlaag dan het aantal elementen in de sequentieparameters.
als er geen parameters zijn, of als parameters eerder zijn gebonden, kan het aantal iteraties worden opgegeven als een geheel getal in plaats van een lijst met lege toewijzingen of sequenties te verstrekken.
Indien ingeschakeld, maakt de parameter batcherrors ondersteuning voor batchfouten mogelijk metinoracle en zorgt ervoor dat de aanroep slaagt, zelfs als er een uitzondering wordt geplaatst in een of meer van de parameters. De fouten kunnen dan worden hersteld met getbatcherrors()
.
indien waar, schakelt de parameter arraydmlrowcounts DML-rijtellingen in om van Oracle te beretrieved nadat de methode is voltooid. Het aantal rijen kan dan worden opgevraagd met getarraydmlrowcounts()
.
zowel de batcherrors-parameter als de arraydmgrowcounts-parameter kunnen alleen waar zijn bij het uitvoeren van een invoegen, bijwerken, verwijderen of samenvoegen; in alle andere gevallen zal een fout worden gemaakt.
voor maximale efficiëntie is het het beste om desetinputsizes()
methode te gebruiken om de parametertypes en-maten van tevoren te specificeren; in het bijzonder wordt aangenomen dat geen enkele reeks lengte 1 is, zodat alle waarden die later als getallen of datums worden gebonden, een TypeError-uitzondering vormen.
Cursor.
executemanyprepared
(numIters)¶
voer het eerder opgestelde en gebonden statement uit op het gegeven aantal keren. De variabelen die gebonden zijn moeten al ingesteld zijn op hun gewenste waarde voordat deze aanroep wordt gedaan. Deze methode is ontworpen voor de zaak waar optimale prestaties vereist zijn omdat het ten koste gaat van de compatibiliteit met de DB API.
Noot
de DB API-definitie definieert deze methode niet.
verouderd sinds versie 6.4: gebruik executemany()
in plaats daarvan met None Voor het statementargument en een integer voor het parameter argument.
Cursor.
fetchall
()¶
haal alle (resterende) rijen van een queryresultaat op en retourneer ze als een lijst met veelvouden. Een lege lijst wordt geretourneerd als er geen rijen meer beschikbaar zijn. Merk op dat de cursor ‘ s arraysize attribuut de prestaties van deze operatie kan beà nvloeden, zoals intern leest uit de database worden gedaan in batchescorresponsing naar de arraysize.
een uitzondering wordt gemaakt als de vorige call naar execute()
geen resultaat heeft opgeleverd of nog geen call heeft plaatsgevonden.
zie methoden voor ophalen voor een voorbeeld.
Cursor.
fetchmany
()¶
haal de volgende reeks rijen van een queryresultaat op, met een lijst van tuples.An lege lijst wordt geretourneerd als er geen rijen meer beschikbaar zijn. Merk op dat het attribuut arraysize van de cursor de uitvoering van deze operatie kan beïnvloeden.
het aantal op te halen rijen wordt opgegeven door de parameter. Als het niet wordt gegeven, bepaalt het arraysize-attribuut van de cursor het aantal rijen dat moet worden vervetched. Als het aantal beschikbare rijen dat opgehaald moet worden kleiner is dan de gevraagde hoeveelheid, worden minder rijen geretourneerd.
een uitzondering wordt gemaakt als de vorige call naar execute()
geen resultaat heeft opgeleverd of nog geen call heeft plaatsgevonden.
zie methoden voor ophalen voor een voorbeeld.
Cursor.
fetchone
()¶
haal de volgende rij van een query resultaat set, retourneren van een enkele tupel of Nonewhen no more data is available.
een uitzondering wordt gemaakt als de vorige call naar execute()
geen resultaat heeft opgeleverd of nog geen call heeft plaatsgevonden.
zie methoden voor ophalen voor een voorbeeld.
Cursor.
fetchraw
()¶
haal de volgende reeks rijen van een query-resultaat op in de interne buffers van de gedefinieerde variabelen voor de cursor. Het aantal rijen dat daadwerkelijk is opgehaald, wordt geretourneerd. Deze methode is ontworpen voor het geval waar optimalperformance is vereist als het gaat ten koste van de compatibiliteit met DB API.
een uitzondering wordt gemaakt als de vorige call naar execute()
geen resultaat heeft opgeleverd of nog geen call heeft plaatsgevonden.
Noot
de DB API-definitie definieert deze methode niet.
Cursor.
fetchvars
¶
dit alleen-lezen attribuut specificeert de lijst met variabelen die zijn aangemaakt voor de laatste query die is uitgevoerd op de cursor. Voorzichtigheid is geboden bij het verwijzen naar Dit kenmerk. In het bijzonder mogen elementen niet worden verwijderdof vervangen.
opmerking
de DB API-definitie definieert Dit kenmerk niet.
Cursor.
getarraydmlrowcounts
()¶
haal de DML-rijtellingen op na een aanroep naar executemany()
met arraydmlrowcounts ingeschakeld. Dit retourneert een lijst met integerscoreantwoord op het aantal rijen dat wordt beïnvloed door het DML-statement voor elk element van de array die wordt doorgegeven aan executemany()
.
opmerking
de DB API-definitie definieert deze methode niet en is alleen beschikbaar voor Oracle 12.1 en hoger.
Cursor.
getbatcherrors
()¶
haal de uitzonderingen op die plaatsvonden na een aanroep naarexecutemany()
met batcherrors ingeschakeld. Dit retourneert een lijst van Foutobjecten, één fout voor elke iteratie die is mislukt. De offset kan worden bepaald door te kijken naar het offset attribuut van het error object.
Noot
de DB API-definitie definieert deze methode niet.
Cursor.
getimplicitresults
()¶
retourneer een lijst met cursors die overeenkomen met Impliciete resultaten die beschikbaar zijn gemaakt vanuit een PL/SQL blok of procedure zonder het gebruik van out refcursor parameters. Het PL / SQL blok of procedure opent de cursors en markeert ze voor terugkeer naar de client met behulp van de proceduredbms_sql.return_result. Cursors die op deze manier terugkeren, mogen niet worden gesloten. Ze worden automatisch gesloten door de bovenliggende cursor wanneer deze gesloten is. Het sluiten van de bovenliggende cursor zal de cursors ongeldig maken die door deze methode worden geretourneerd.
nieuw in versie 5.3.
opmerking
de DB API-definitie definieert deze methode niet en is alleen beschikbaar voor Oracle Database 12.1 (zowel client als server moeten op dit niveau of hoger zijn). Het is het meest als de DB API methode nextset (), maarun zoals die methode (die vereist dat de volgende resultaat set overschrijft de huidige resultaat set), deze methode retourneert cursors die onafhankelijk van elkaar kunnen befetched.
Cursor.
inputtypehandler
¶
dit lezen-schrijven-kenmerk specificeert een methode die wordt aangeroepen voor elke waarde die wordt gebonden aan een statement dat op de cursor wordt uitgevoerd en die de attribuut met dezelfde naam op de verbinding overschrijft, indien opgegeven. De methode signature ishandler(cursor, value, arraysize) en de return waarde wordt verwacht avariable object of geen in welk geval een standaard variabele object zal worden aangemaakt. Als dit attribuut geen is, wordt de waarde van het attribuut met dezelfde naam op de verbinding gebruikt.
Note
deze eigenschap is een uitbreiding van de DB API-definitie.
Cursor.
__iter__
()¶
geeft de cursor zelf terug om te worden gebruikt als een iterator.
Noot
deze methode is een uitbreiding van de DB API-definitie, maar wordt in PEP 249 vermeld als een facultatieve uitbreiding.
Cursor.
lastrowid
¶
dit alleen-lezen attribuut retourneert de rowid van de laatste rij gewijzigd door thecursor. Als er geen rij is gewijzigd door de laatste bewerking die op de cursor is uitgevoerd, wordt de waarde None geretourneerd.
nieuw in versie 7.3.
Cursor.
outputtypehandler
¶
dit read-write attribuut specificeert een methode die wordt aangeroepen voor elke kolom die van deze cursor moet worden opgehaald. De methode handtekening ishandler (cursor, naam, defaultType, lengte, precisie, schaal) en de returnvalue wordt verwacht een variabel object of geen in welk geval een defaultvariable object zal worden gemaakt. Als dit attribuut geen is, wordt in plaats daarvan de waarde van het attribuut met dezelfde naam op de verbinding gebruikt.
zie opgehaalde gegevenstypen wijzigen met Handlers van het uitvoertype.
Note
deze eigenschap is een uitbreiding van de DB API-definitie.
Cursor.
parse
( ¶
dit kan worden gebruikt om een statement te ontleden zonder het daadwerkelijk uit te voeren (dit wordt automatisch gedaan door Oracle wanneer een statement wordt uitgevoerd).
Noot
de DB API-definitie definieert deze methode niet.
opmerking
u kunt elk DML-of DDL-statement ontleden. DDL-statements worden onmiddellijk uitgevoerd en er vindt een impliciete commit plaats.
Cursor.
prefetchrows
¶
dit read-write attribuut kan worden gebruikt om het aantal rijen af te stemmen dat theOracle Client library ophaalt wanneer een SELECT statement wordt uitgevoerd. Deze waarde kan het aantal round-trips naar de database verminderen die nodig zijn om rijen op te halen, maar ten koste van extra geheugen. Het instellen van deze waarde op 0 kan nuttig zijn wanneer de timing van fetches expliciet gecontroleerd moet worden.
zie Tuning Fetch Performance voor meer informatie.
Noot
de DB API-definitie definieert deze methode niet.
Cursor.
prepare
(statement)¶
dit kan worden gebruikt voor een aanroep naar execute()
om de taak te definiëren die zal worden uitgevoerd. Als dit gedaan is, zal de voorbereidingsfase niet worden uitgevoerd wanneer de aanroep naar execute()
wordt gedaan met geen of hetzelfde stringobject als het statement. Indien opgegeven zal de statement worden geretourneerd naar de statement cache met de opgegeven tag. Zie de Oracle documentatie voor meer informatie over de statement cache.
zie Statement Caching voor meer informatie.
Noot
de DB API-definitie definieert deze methode niet.
Cursor.
rowcount
¶
dit alleen-lezen attribuut specificeert het aantal rijen dat op dit moment van de cursor is opgehaald( voor SELECT statements), die zijn beïnvloed door de operatie (voor invoegen, bijwerken, verwijderen en mergestatements), of het aantal succesvolle uitvoeringen van de statement(voor PL/SQL statements).
Cursor.
rowfactory
¶
Dit kenmerk lezen-schrijven specificeert een methode om te bellen voor elke rij die uit de database wordt geretrieerd. Gewoonlijk wordt voor elke rij een tupel geretourneerd, maar als dit attribuut is ingesteld, wordt de methode aangeroepen met de tupel die normaal zou worden geretourneerd, en wordt het resultaat van de methode geretourneerd in plaats van.
zie zoekresultaten wijzigen met Rowfactories.
opmerking
de DB API-definitie definieert Dit kenmerk niet.
Cursor.
scroll
(value = 0, mode= “relative”)¶
Schuif de cursor in het resultaat naar een nieuwe positie volgens de modus.
als de modus “relatief” is (de standaardwaarde), wordt de waarde genomen als een compensatie voor de huidige positie in de resultaatset. Indien ingesteld op “absoluut”, geeft value een absolute doelpositie aan. Indien ingesteld op” eerste”, wordt de cursor geplaatst op de eerste rij en indien ingesteld op” laatste”, wordt de cursor ingesteld op de laatste rij in de resultaatset.
een fout wordt weergegeven als de modus “relatief” of “absoluut” is en de schuifhandeling de cursor buiten de resultaatset plaatst.
nieuw in versie 5.3.
Noot
deze methode is een uitbreiding van de DB API-definitie, maar wordt in PEP 249 vermeld als een facultatieve uitbreiding.
Cursor.
scrollable
¶
dit lezen-schrijven Booleaanse attribuut specificeert of de cursor kan bescrolled of niet. Cursors zijn standaard niet scrollable, omdat de serverresources en responstijden groter zijn dan niet-scrollable cursors. Dit attribute wordt gecontroleerd en de bijbehorende modus wordt ingesteld in Oracle wanneer de methode execute()
wordt aangeroepen.
nieuw in versie 5.3.
opmerking
de DB API-definitie definieert Dit kenmerk niet.
Cursor.
setinputsizes
(*args, * * keywordArgs)¶
dit kan gebruikt worden voor een aanroep naar execute()
,callfunc()
of callproc()
naar vooraf gedefinieerde gebieden voor de parameters van de operatie. Elke parameter zou atype object moeten zijn dat overeenkomt met de invoer die zal worden gebruikt of het zou eeninteger moeten zijn die de maximale lengte van een string parameter specificeert. Gebruik keywordparameters bij Binding op naam en positionele parameters bij binding byposition. De singleton None kan worden gebruikt als een parameter bij het gebruik vanpositionele parameters om aan te geven dat er geen ruimte moet worden gereserveerd voor diepositie.
Note
als u callfunc()
wilt gebruiken, moet u zich ervan bewust zijn dat de eerste parameter in de lijst verwijst naar de retourwaarde van de functie.
Cursor.
setoutputsize
(grootte)¶
deze methode doet niets en wordt uitsluitend gebruikt voor compatibiliteit met de DB API. De module wijst automatisch zoveel ruimte toe als nodig is voor fetchLONG en LONG RAW kolommen (of CLOB als string en BLOB als bytes).
Cursor.
statement
¶
dit alleen-lezen attribuut biedt het string object dat eerder werd voorbereid met prepare()
of uitgevoerd metexecute()
.
opmerking
de DB API-definitie definieert Dit kenmerk niet.
Cursor.
var
(datatype)¶
Maak een variabele met de opgegeven kenmerken. Deze methode werd ontworpen voor gebruik met PL / SQL in / out variabelen waar de lengte of type niet automatisch kan worden bepaald van het Python object doorgegeven in of voor gebruik in input en output type handlers gedefinieerd op cursors of verbindingen.
de parameter dataType specificeert het type gegevens dat in de variabele moet worden opgeslagen. Dit moet een van de databasetype constanten zijn, DB API constanten, een objecttype geretourneerd van de methode Connection.gettype()
of een van de volgende Python types:
Python-Type | Databasetype |
---|---|
bool | cx_Oracle.DB_TYPE_BOOLEAN |
bytes | cx_Oracle.DB_TYPE_RAW |
datetime.datum | cx_Oracle.DB_TYPE_DATE |
datetime.datumtijd | cx_Oracle.DB_TYPE_DATE |
datetime.timedelta | cx_Oracle.DB_TYPE_INTERVAL_DS |
decimaal.Decimaal | cx_Oracle.DB_TYPE_NUMBER |
zwevend | cx_Oracle.DB_TYPE_NUMBER |
int | cx_Oracle.DB_TYPE_NUMBER |
str | cx_Oracle.DB_TYPE_VARCHAR |
de Parameter Grootte specificeert de lengte van string en ruwe variabelen en issigned in alle andere gevallen. Indien niet opgegeven voor string en raw variabelen,wordt de waarde 4000 gebruikt.
de arraysize parameter specificeert het aantal elementen dat de variabele zal hebben. Indien niet opgegeven wordt de BIND array grootte (meestal 1) gebruikt. Wanneer avariable wordt gemaakt in een Uitvoer Type handler moet deze parameter worden ingesteld op de array grootte van de cursor.
de parameters inconverter en outconverter specificeren de methoden die worden gebruikt voor het converteren van waarden naar/van de database. Meer informatie is te vinden in het gedeelte over variabele objecten.
de parameter typename specificeert de naam van een SQL-objecttype en moet worden gespecificeerd wanneer type cx_Oracle.OBJECT
wordt gebruikt, tenzij het type object direct als de eerste parameter is doorgegeven.
de parameter codingerrors specificeert wat er moet gebeuren wanneer decodingbyte-strings uit de database worden opgehaald in strings. Het zou een van de waarden moeten zijn die in de gebouwindecodefunctie worden genoteerd.
Noot
de DB API-definitie definieert deze methode niet.