Cursor Object¶

Cursor.__enter__()¶

punkt wejścia kursora jako menedżer kontekstu. Powraca sama.

Cursor.__exit__()¶

punkt wyjścia dla kursora jako menedżera kontekstu. Zamyka kursor.

Cursor.arraysize¶

ten atrybut odczytu i zapisu może być użyty do dostrojenia liczby wierszy wewnętrznychfetchowanych i buforowanych przez wewnętrzne wywołania do bazy danych podczas pobierania wierszy z instrukcji SELECT i kursorów REF. Wartość może drastycznie wpłynąć na wydajność zapytania, ponieważ bezpośrednio wpływa na liczbę podróży sieciowych między Pythonem a bazą danych. Dla metod takich jakfetchone() i fetchall() nie zmienia sięjak wiele wierszy jest zwracanych do aplikacji. Dlafetchmany() jest to domyślna liczba wierszy do pobrania.

ze względu na korzyści z wydajności, domyślną wartością Cursor.arraysizejest 100 zamiast 1 zalecanego przez DB API. Wartość ta oznacza, że każde wewnętrzne wywołanie do bazy danych pobiera 100 wierszy.

Zobacz strojenie wydajności pobierania, aby uzyskać więcej informacji.

Cursor.bindarraysize¶

ten atrybut odczytu i zapisu określa liczbę wierszy do powiązania w danym momencie i jest używany podczas tworzenia zmiennych poprzez setinputsizes()lubvar(). Domyślnie 1 oznacza związanie jednego wiersza naraz.

Cursor.arrayvar(dataType, value)¶

wytworzy zmienną tablicową powiązaną z kursorem o podanym typie i rozmiarze oraz zwróci obiekt zmiennej. Wartość jest albo liczbą określającą liczbę elementów do przydzielenia, albo jest listą iliczba przydzielonych elementów jest pobierana z wielkości listy. Jeżeli thevalue jest listą, zmienna jest również ustawiana z zawartością listy. Jeśli rozmiar nie jest określony, A typ jest łańcuchem lub binarnym, przydzielono 4000 bajtów. Jest to potrzebne do przekazywania tablic do PL / SQL (w przypadkach, gdy lista może być pusta, A Typ nie może być określony automatycznie) lub do zwracania tablic z PL/SQL.

zmienne tablicy mogą być używane tylko dla tablic asocjacyjnych PL/SQL z kluczami ciągłymi. W przypadku tablic asocjacyjnych PL / SQL ze słabo zaludnionym kluczem dla varrays i tabel zagnieżdżonych należy zastosować podejście pokazane w tym przykładzie.

Cursor.bindnames()¶

zwraca listę nazw zmiennych bind powiązanych z instrukcją. Zauważ, że wypowiedź musiała być przygotowana jako pierwsza.

Cursor.bindvars¶

ten atrybut Tylko do odczytu dostarcza zmiennych bind używanych dla lastexecute. Wartość będzie listą lub słownikiem w zależności od tego, czy Wiązanie zostało wykonane przez pozycję lub nazwę. Należy zachować ostrożność przy określaniu tego atrybutu. W szczególności nie należy usuwać ani wymieniać elementów.

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

wywołanie funkcji o podanej nazwie. Typ zwracany jest określony w notacji nazw, tak jak jest to wymagane przez setinputsizes(). Sekwencja parametrów musi zawierać jeden wpis dla każdego parametru, którego oczekuje funkcja. Wszelkie parametry słowa kluczowego zostaną uwzględnione po parametrachpozycyjnych. Wynikiem wywołania jest wartość zwracana funkcji.

patrz przykład funkcji przechowywanych w PL/SQL.

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

wywołanie procedury o podanej nazwie. Sekwencja parametrów musi zawierać jeden wpis dla każdego parametru, którego oczekuje procedura. Wynikiem wywołania jest zmodyfikowana Kopia sekwencji wejściowej. Parametry wejściowe są nietknięte; parametry wyjściowe i wejściowe/wyjściowe są zastępowane potencjalnie nowymi wartościami. Parametry słowa kluczowego zostaną uwzględnione po parametrachpozycyjnych i nie są zwracane jako część sekwencji wyjściowej.

zobacz procedury składowane PL/SQL jako przykład.

Cursor.close()¶

Zamknij kursor teraz, a nie kiedykolwiek zostanie wywołane _ _ del__. Od tego momentu kursor będzie bezużyteczny; pojawi się wyjątek błędu, jeśli jakakolwiek operacja zostanie wykonana przy użyciu kursora.

Cursor.connection¶

ten atrybut Tylko do odczytu zwraca odniesienie do obiektu connection, na którym kursor został utworzony.

Cursor.description¶

ten atrybut Tylko do odczytu jest sekwencją sekwencji 7-elementowych. Każda z tych sekwencji zawiera informacje opisujące jedną kolumnę wyników: (name, type, display_size, internal_size, precision, scale, null_ok). Ten atrybut będzie None dla operacji, które nie zwracają wierszy lub jeśli kursor nie miał jeszcze operacji wywołanej za pomocą metody execute().

Typ będzie jednym ze stałych typu bazy danych zdefiniowanych na poziomie modułu.

Cursor.execute(statement, * * keywordParameters)¶

wykonuje polecenie przeciwko bazie danych. Zobacz wykonanie SQL.

parametry mogą być przekazywane jako słownik lub Sekwencja lub jako parametry słów kluczowych. Jeśli parametry są słownikiem, wartości będą powiązane przez nazwę, a jeśli parametry są sekwencją, wartości będą powiązane przez położenie. Zauważ, że jeśli wartości są związane pozycją, kolejność zmiennych jest od lewej do prawej, ponieważ są spotykane w instrukcji, a instrukcje SQL są przetwarzane inaczej niż instrukcje PL/SQL. Z tego powodu zaleca się Wiązanie parametrów przez nazwę zamiast przez pozycję.

parametry przekazywane jako słownik to pary nazwa i wartość. Nazwa mapuje nazwę zmiennej bind używanej przez instrukcję i wartość mapuje do wartości, którą chcesz powiązać z tą zmienną bind.

odwołanie do instrukcji zostanie zachowane przez kursor. Jeśli obiekt None lub theame string zostanie ponownie przekazany, kursor wykona thatstatement ponownie bez wykonywania prepare lub rebindingu i przedefiniowania.Jest to najbardziej skuteczne w przypadku algorytmów, w których używane jest to samo polecenie, ale różne parametry są z nim powiązane (wiele razy). Należy pamiętać, że parametry, które nie są przekazywane podczas kolejnych egzekucji, zachowają wartość, która została przekazana podczas ostatniej egzekucji, która je zawierała.

aby uzyskać maksymalną wydajność podczas ponownego użycia instrukcji, najlepiej jest użyć metodysetinputsizes(), aby określić typy parametrów i ich rozmiary z wyprzedzeniem; w szczególności zakłada się, że none jest ciągiem długości 1, więc wszelkie wartości, które są później związane jako liczby lub daty, będą powodowały wyjątek TypeError.

jeśli polecenie jest zapytaniem, kursor jest zwracany jako wygoda dla kallera (więc może być użyty bezpośrednio jako iterator nad wierszami w cursor); w przeciwnym razie zwracana jest None.

Cursor.executemany(statement, parameters, batcherrors=False, arraydmlrowcounts=False)¶

przygotuj instrukcję do wykonania w bazie danych, a następnie wykonaj ją ze wszystkimi mapowaniami parametrów lub sekwencjami znajdującymi się w sequenceparametrach. Zobacz Wykonywanie instrukcji partii i ładowanie zbiorcze.

instrukcja jest zarządzana w taki sam sposób, jak zarządza nią metoda execute(). Jeśli rozmiar buforów przydzielonych dla któregokolwiek z parametrów przekroczy 2 GB, pojawi się błąd ” DPI-1015: rozmiar tablicy < n> jest zbyt duży”, gdzie <n> zmienia się wraz z rozmiarem każdego elementu umieszczonego w buforze. Jeśli pojawi się ten błąd, zmniejsz liczbęelementy w parametrach sekwencji.

jeśli nie ma żadnych parametrów lub parametry zostały wcześniej powiązane, to liczba iteracji może być określona jako liczba całkowita, zamiast potrzeby dostarczania listy pustych mapowań lub sekwencji.

gdy true, parametr batcherrors włącza obsługę błędów wsadowych withinOracle i zapewnia, że wywołanie powiedzie się, nawet jeśli wystąpi wyjątek w jednej lub kilku sekwencjach parametrów. Błędy można następnie odczytać za pomocą getbatcherrors().

gdy wartość true, parametr arraydmlrowcounts włącza liczenie wierszy DML do odczytu z Oracle po zakończeniu metody. Wiersz liczy canthen być pobierane za pomocą getarraydmlrowcounts().

zarówno parametr batcherrors, jak i parametr arraydmlrowcounts mogą mieć tylko wartość true podczas wykonywania instrukcji insert, update, delete lub merge; we wszystkich innych przypadkach zostanie zgłoszony błąd.

aby uzyskać maksymalną wydajność, najlepiej jest użyć metodysetinputsizes() do określenia typów parametrów i rozmiarów z wyprzedzeniem; w szczególności nie przyjmuje się, że żaden jest ciągiem długości 1, więc wszelkie wartości, które są później powiązane jako liczby lub daty, będą powodowały wyjątek TypeError.

Cursor.executemanyprepared(numeratory)¶

wykonuje wcześniej przygotowane i związane polecenie podaną ilość razy. Zmienne, które są powiązane, muszą być już ustawione na ich wartość przed wykonaniem tego wywołania. Metoda ta została zaprojektowana dla obszaru, w którym wymagana jest optymalna wydajność kosztem kompatybilności z API DB.

Cursor.fetchall()¶

pobiera wszystkie (pozostałe) wiersze wyniku zapytania, zwracając je jako listę wartości. Pusta lista jest zwracana, jeśli nie ma więcej wierszy. Zauważ, że atrybut arraysize kursora może wpływać na wydajność tej operacji, ponieważ wewnętrzne odczyty z bazy danych są wykonywane w batchescorresponding to the arraysize.

powstaje wyjątek, jeśli poprzednie wywołanie execute()nie przyniosło żadnego zestawu wyników lub nie zostało jeszcze wywołane.

patrz przykład metody pobierania.

Cursor.fetchmany()¶

pobiera następny zestaw wierszy wyniku zapytania, zwracając listę tuples.An pusta lista jest zwracana, jeśli nie ma więcej wierszy. Zauważ, że atrybut arraysize może mieć wpływ na wydajność tej operacji.

liczba wierszy do pobrania jest określona przez parametr. Jeśli nie jest to możliwe, atrybut arraysize kursora określa liczbę wierszy, które mają być ustawione. Jeśli liczba dostępnych wierszy do pobrania jest mniejsza niż wymagana ilość, zostanie zwróconych mniej wierszy.

powstaje wyjątek, jeśli poprzednie wywołanie execute()nie przyniosło żadnego zestawu wyników lub nie zostało jeszcze wywołane.

patrz przykład metody pobierania.

Cursor.fetchone()¶

pobiera następny wiersz zbioru wyników zapytania, zwracając pojedynczą krotkę lub nie, gdy nie są dostępne żadne dane.

powstaje wyjątek, jeśli poprzednie wywołanie execute()nie przyniosło żadnego zestawu wyników lub nie zostało jeszcze wywołane.

patrz przykład metody pobierania.

Cursor.fetchraw()¶

pobiera następny zestaw wierszy wyniku zapytania do wewnętrznych buforów zdefiniowanych zmiennych dla kursora. Liczba faktycznie pobranych wierszy jest zwracana. Metoda ta została zaprojektowana w przypadku, gdy wymagana jest optymalna wydajność kosztem kompatybilności z DB API.

powstaje wyjątek, jeśli poprzednie wywołanie execute()nie przyniosło żadnego zestawu wyników lub nie zostało jeszcze wywołane.

Cursor.fetchvars¶

ten atrybut Tylko do odczytu określa listę zmiennych utworzonych dla ostatniego zapytania wykonanego na kursorze. Należy zachować ostrożność przy określaniu tego atrybutu. W szczególności nie należy usuwać ani wymieniać elementów.

Cursor.getarraydmlrowcounts()¶

Pobierz liczniki wierszy DML po wywołaniu executemany() z włączoną arraydmlrowcounts. Zwróci To listę liczb całkowitych odpowiadającą liczbie wierszy, których dotyczy Instrukcja DML dla każdego elementu tablicy przekazanej do executemany().

Cursor.getbatcherrors()¶

pobiera wyjątki, które miały miejsce po wywołaniu executemany() z włączoną batcherrors. Spowoduje to zwrócenie listy obiektów błędu, jednego błędu dla każdej iteracji, która nie powiodła się. Przesunięcie można określić, patrząc na atrybut offset obiektu błędu.

Cursor.getimplicitresults()¶

zwraca listę kursorów, które odpowiadają niejawnym wynikom uzyskanym z bloku lub procedury PL/SQL bez użycia zewnętrznych parametrów refcursor. Blok lub procedura PL/SQL otwiera kursory i zaznacza je do powrotu do klienta za pomocą procedury proceduredbms_sql.return_result. Kursory zwrócone w ten sposób nie powinny być blokowane. Zostaną one automatycznie zamknięte przez kursor nadrzędny po jego zamknięciu. Zamknięcie nadrzędnego kursora spowoduje unieważnienie kursorów zwracanych przez tę metodę.

Cursor.inputtypehandler¶

ten atrybut odczytu i zapisu określa metodę wywoływaną dla każdej wartości, która jest powiązana z instrukcją wykonywaną kursorem i nadpisuje atrybut z tą samą nazwą na połączeniu, jeśli jest określony. Method signature ishandler(cursor, value, arraysize) i zwracana wartość mają być obiektami zmiennymi lub żadnymi w takim przypadku zostanie utworzony obiekt zmiennej domyślnej. Jeśli ten atrybut jest None, używana jest wartość atrybutu z nazwą połączenia.

Cursor.__iter__()¶

zwraca sam kursor do wykorzystania jako iterator.

Cursor.lastrowid¶

ten atrybut Tylko do odczytu zwraca rowid ostatniego wiersza zmodyfikowanego przez thecursor. Jeśli ostatnia operacja wykonana na kreatorze nie zmodyfikowała żadnego wiersza, zwracana jest wartość None.

Cursor.outputtypehandler¶

ten atrybut odczytu i zapisu określa metodę wywołaną dla każdej kolumny, która jest pobierana z tego kursora. Sygnatura metody ishandler (cursor, name, defaultType, length, precision, scale) i returnvalue ma być obiektem zmiennej lub nie ma w takim przypadku zostanie utworzony obiekt zmiennej domyślnej. Jeśli ten atrybut nie ma wartości None, zamiast tego używana jest wartość atrybutu o tej samej nazwie na połączeniu.

Patrz Zmiana pobranych typów danych za pomocą obsługi typów wyjściowych.

Cursor.parse(Instrukcja)¶

to może być użyte do parsowania instrukcji bez faktycznego jej wykonania (ta czynność jest wykonywana automatycznie przez Oracle podczas wykonywania instrukcji).

Cursor.prefetchrows¶

ten atrybut odczytu i zapisu może być użyty do dostrojenia liczby wierszy pobieranych przez Bibliotekę theracle podczas wykonywania instrukcji SELECT. Wartość ta może zmniejszyć liczbę powrotów do bazy danych, które są wymagane do pobrania wierszy, ale kosztem dodatkowej pamięci. Ustawienie tej wartości na 0 może być użyteczne, gdy czas pobierania musi być jawnie kontrolowany.

Zobacz strojenie wydajności pobierania, aby uzyskać więcej informacji.

Cursor.prepare(polecenie)¶

to może być użyte przed wywołaniem execute() do zdefiniowania polecenia, które zostanie wykonane. Po wykonaniu tej czynności, Faza prepare nie będzie wykonywana, gdy wywołanie execute() zostanie wykonane z none lub tym samym obiektem łańcuchowym, co polecenie. Jeśli podano, to polecenie zostanie zwrócone do bufora instrukcji z podanym znacznikiem. Zapoznaj się z dokumentacją Oracle, aby uzyskać więcej informacji na temat pamięci podręcznej instrukcji.

Zobacz buforowanie instrukcji, aby uzyskać więcej informacji.

Cursor.rowcount¶

ten atrybut Tylko do odczytu określa liczbę wierszy, które zostały pobrane z kursora (dla poleceń select), na które wpłynęła operacja (dla poleceń insert, update, delete i mergestatements), lub liczbę pomyślnych wykonań instrukcji(dla poleceń PL/SQL).

Cursor.rowfactory¶

ten atrybut odczytu i zapisu określa metodę, która ma być wywołana dla każdego wiersza, który jest pobrany z bazy danych. Zwykle dla każdego wiersza zwracana jest krotka, jeśli ten atrybut jest ustawiony, metoda jest wywoływana z krotką, która normalnie powinna być zwrócona, a wynik metody jest zwracany zamiast.

zobacz Zmienianie wyników zapytań za pomocą katalogów wierszy.

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

Przewiń kursor w wyniku ustawiony na nową pozycję zgodnie z mode.

jeśli tryb jest „względny” (wartość domyślna), wartość jest pobierana jako przesunięcie bieżącej pozycji w zestawie wyników. Jeśli ustawiona jest wartość „absolutna”, valuestates absolutna pozycja docelowa. Jeśli ustawiony jest na „pierwszy”, kursor jest ustawiony w pierwszym wierszu, a jeśli ustawiony na „ostatni”, kursor jest ustawiony na ostatni wiersz w zestawie wyników.

pojawia się błąd, jeśli tryb jest „względny” lub „bezwzględny”, a przewijanie pozycjonuje kursor poza zestawem wyników.

Cursor.scrollable¶

ten boolean do odczytu i zapisu określa, czy kursor może być przewijany, czy nie. Domyślnie Kursory nie są przewijalne, ponieważ zasoby serwera i czas odpowiedzi są większe niż Kursory nieobrotowe. Thisattribute jest sprawdzane i odpowiedni tryb ustawiany w Oracle podczas wywoływania metody execute().

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

to może być użyte przed wywołaniem execute(),callfunc() lub callproc() do predefiniowania obszarów pamięci dla parametrów operacji. Każdy parametr powinien być obiektem typu odpowiadającym wejściu, które będzie użyte lub powinien być liczbą całkowitą określającą maksymalną długość parametru łańcuchowego. Używaj parametrów słów kluczowych podczas wiązania według nazwy i parametrów pozycyjnych podczas wiązania byposition. Singleton None może być użyty jako parametr podczas używania parametrówpositional, aby wskazać, że nie należy zarezerwować spacji dla tej pozycji.

Cursor.setoutputsize(size)¶

ta metoda nic nie robi i jest zachowana wyłącznie dla kompatybilności z API db. Moduł automatycznie przydziela tyle miejsca, ile potrzeba do fetchLONG i LONG raw columns (lub CLOB jako string i BLOB jako bajty).

Cursor.statement¶

ten atrybut Tylko do odczytu dostarcza obiekt Łańcuchowy, który został wcześniej zreformowany za pomocą prepare() lub wykonany za pomocąexecute().

Cursor.var(dataType)¶

wytworzy zmienną o określonej charakterystyce. Metoda ta została zaprojektowana do użytku ze zmiennymi PL/SQL in / out, w których długość lub typ nie może być określana automatycznie z obiektu Pythona przekazanego lub używanego w instrukcjach obsługi typów wejściowych i wyjściowych zdefiniowanych na kursorach lub połączeniach.

parametr dataType określa typ danych, które mają być zapisane w zmiennej. Powinna to być jedna ze stałych typu database, stałe API DB, typ obiektu zwracany z metody Connection.gettype() lub jeden z następujących typów Pythona:

Typ Python	Typ bazy danych
bool	cx_Oracle.DB_TYPE_BOOLEAN
bajty	cx_Oracle.DB_TYPE_RAW
datetime.Data	cx_Oracle.DB_TYPE_DATE
datetime.datetime	cx_Oracle.DB_TYPE_DATE
datetime.timedelta	cx_Oracle.DB_TYPE_INTERVAL_DS
dziesiętne.Dziesiętne	cx_Oracle.DB_TYPE_NUMBER
float	cx_Oracle.DB_TYPE_NUMBER
int	cx_Oracle.DB_TYPE_NUMBER
str	cx_Oracle.DB_TYPE_VARCHAR

parametr size określa długość zmiennych string i raw i jest przypisany we wszystkich pozostałych przypadkach. Jeżeli dla zmiennych string i raw nie jest określona, to zostanie użyta wartość 4000.

parametr arraysize określa ilość elementów, które będzie miała zmienna. Jeśli nie podano, używany jest rozmiar tablicy bind (zwykle 1). Gdy avariable jest tworzony w output type handler ten parametr powinien być ustawiony na rozmiar tablicy kursora.

parametry inconverter i outconverter określają metody używane do konwertowania wartości do / z bazy danych. Więcej informacji można znaleźć w rozdziale o obiektach zmiennych.

parametr typename określa nazwę typu obiektu SQL i musi być określony przy użyciu typu cx_Oracle.OBJECT, chyba że obiekt typu został przekazany bezpośrednio jako pierwszy parametr.

parametr encodingErrors określa, co powinno się stać podczas dekodowania łańcuchów Byte pobranych z bazy danych do łańcuchów. Powinna to być jedna z wartości odnotowanych w wbudowanej funkcji kodowania.