Automatyczne providery zapytań

Dostępne od wersji 2.384.99 poprzez fasadę skoroszytu XLSX w Windows; automatyczny wybór providera następuje wyłącznie podczas jawnego odświeżenia zapytania

Odświeżanie istniejącego zapytania

Workbook.QueryProviders.BaseDirectory := 'C:\Data';
Workbook.QueryProviders.MaxInputBytes := 64 * 1024 * 1024;
Workbook.QueryProviders.MaxResultCells := 2000000;
Workbook.QueryProviders.TimeoutSeconds := 30;
Status := Sheet.RefreshQueryTable('ImportedData', 1000000);

TXLSXWorkbook.QueryProviders: TXLSQueryProviderDispatcher udostępnia dispatcher należący do skoroszytu, pochodzący z lxQueryProviders; nie zwalniaj tego dispatchera samodzielnie

TXLSXWorksheet.RefreshQueryTable(const AName: WideString; AMaxRows: Integer = 1000000; AOnProgress: TXLSQueryRefreshProgress = nil): Integer oraz przeciążenie przyjmujące numerowane od zera AIndex wybierają istniejące zapytanie i korzystają z tego dispatchera

Istniejące przeciążenia przyjmujące jawny TXLSQueryTableProvider dalej używają tego providera bezpośrednio, łącznie z dotychczasowym odrzucaniem brakującego providera; nie przechodzą one na automatyczny dispatch

Odświeżenie zwraca 1 po sukcesie, 0 po anulowaniu albo -1 po błędzie, z kodami diagnostycznymi 1401 i 1400 pod xlsOperationRefresh; istniejące transakcyjne stosowanie wyników, walidacja schematu, literały tekstowe i zachowanie formatowania pozostają w mocy

Te wpisy diagnostyczne nazywają się xlsDiagnosticQueryRefreshCancelled i xlsDiagnosticQueryRefreshFailed; przejęcie strażnika zapisu skoroszytu następuje przed konwersją statusu, więc zamrożony widok odczytu lub inne odrzucenie przez strażnika zapisu kończy się wyjątkiem

Otwieranie i zapisywanie skoroszytu nigdy nie pobiera danych połączeń, nie wykonuje zapytań ani nie działa na zachowanych metadanych RefreshOnLoad; przed zapisaniem wyniku odśwież jawnie każde wymagane zapytanie

Wbudowane providery

• xlckText czyta lokalny tekst rozdzielany lub o stałej szerokości ze ścisłym dekodowaniem UTF-8, UTF-16LE, UTF-16BE, Windows-1252 lub Latin-1, konfigurowalnym wierszem startowym i obsługiwanymi typami pól, w tym sześcioma układami dat oraz polami pomijanymi; dane rozdzielane obsługują też wielowierszowe rekordy w cudzysłowach
• xlckAdo, xlckOleDb i xlckOdbc korzystają z zainstalowanych w Windows sterowników ADO i baz danych, z połączeniami i recordsetami tylko do odczytu; CommandType = 2 wybiera tekst SQL, a CommandType = 3 polecenie tabeli
• xlckWeb używa Windows WinHTTP do anonimowego żądania HTTP lub HTTPS GET jednej niepustej prostokątnej tabeli HTML wskazanej dodatnim indeksem lub nazwą; obsługiwane zestawy znaków odpowiedzi to UTF-8, UTF-16, Windows-1252 i Latin-1

BaseDirectory stanowi podstawę wyłącznie dla względnych lokalnych ścieżek tekstowych; connection stringi baz danych i adresy URL sieci Web pozostają jawnymi metadanymi połączenia

Nieokreślone kodowanie tekstu akceptuje wyłącznie wejście ASCII, chyba że obsługiwany BOM wskazuje kodowanie; wejście spoza ASCII wymaga jawnego obsługiwanego kodowania albo BOM

Dla tekstowego połączenia rozdzielanego ustaw TextPrompt = False, TextDelimited = True i dokładnie jeden separator, bez scalania kolejnych separatorów; nowo utworzone połączenia domyślnie pytają o parametry i używają separatora tabulacji, więc przy wyborze innego separatora wyczyść TextTab

Tekst o stałej szerokości

Ustaw TextPrompt = False i TextDelimited = False, a następnie dodawaj TextFields w ściśle rosnącej kolejności pozycji Position numerowanych od zera, począwszy od zera; każde pole kończy się na następnej pozycji albo na fizycznym terminatorze rekordu, a xltiftSkip wyklucza swoje pole z wyniku

Pozycje liczą zdekodowane jednostki kodu UTF-16, a nie bajty wejścia; granica przecinająca parę surrogate jest odrzucana, a CRLF, LF i CR kończą rekordy niezależnie od ustawień separatora i kwalifikatora

Dopełnienie pól jest obcinane przed konwersją, łącznie z jawnie typowanym tekstem, co odpowiada zweryfikowanemu natywnemu zachowaniu importu o stałej szerokości; cudzysłowy, tabulatory i znaki separatora wewnątrz pola pozostają literałami wejścia, a krótkie rekordy dostarczają puste pola końcowe bez zmiany zadeklarowanego schematu

Bez TextFields każdy rekord to jedno pole ogólne; TextFirstRow wybiera pierwszy rekord schematu, Query.Headers pomija wartości tego rekordu, a jawne puste rekordy pozostają wierszami

Obowiązują istniejące limity wierszy, bajtów wejścia, komórek wyniku i pól liczących 32767 jednostek kodu; nieprawidłowe metadane, błędy konwersji lub nadmierne wejście czyszczą dane etapowane przed transakcyjną aktualizacją arkusza, a anulowanie zachowuje poprzednie komórki wyniku

Connection.TextPrompt := False;
Connection.TextDelimited := False;
Connection.TextFields.Add(xltiftGeneral, 0);
Connection.TextFields.Add(xltiftText, 8);
Status := Sheet.RefreshQueryTable('Imported');

Dla połączenia Web ustaw WebHtmlTables = True i WebHtmlFormat = 'none'; obsługiwane żądania odrzucają osadzone poświadczenia, fragmenty, uwierzytelnianie i przekierowania

Wbudowane providery odrzucają nieobsługiwane metadane w swoich rodzajach połączeń; odświeżanie baz danych odrzuca polecenia OLAP lub serwerowe, pośrednictwo plików połączeń, zapisane hasła i monity o poświadczenia, odświeżanie Text odrzuca monity o plik, a odświeżanie Web wymaga anonimowych metadanych tabeli

Typowane parametry bazy danych

Polecenia tekstowe SQL obsługują pozycyjne znaczniki ? wiązane przez ADO Command, w kolejności Connection.Parameters; wartości parametrów nigdy nie zastępują tekstu SQL, a nazwy etykietują wiązania bez zmiany kolejności pozycyjnej

Kontrola wstępna zlicza znaczniki poza pojedynczymi cudzysłowami, identyfikatorami w podwójnych cudzysłowach lub odwróconych apostrofach, identyfikatorami w nawiasach kwadratowych, komentarzami liniowymi i zagnieżdżonymi komentarzami blokowymi, łącznie z podwojonymi escapami cudzysłowów i nawiasów; niedomknięte cudzysłowy lub komentarze oraz niezgodna liczba znaczników odrzucają żądanie przed otwarciem połączenia

Użyj ParameterType = 'value' z jawnym ValueKind o wartości xlcpvInteger, xlcpvDouble, xlcpvBoolean lub xlcpvString oraz z odpowiadającą mu właściwością wartości; zero, False i puste ciągi są wartościami, a xlcpvNone nie powoduje wnioskowania wartości podczas wykonania

Connection.CommandType := 2;
Connection.CommandText := 'SELECT Amount FROM Sales WHERE Amount > ?';
with Connection.Parameters.Add do
begin
  Name := 'MinimumAmount';
  ParameterType := 'value';
  ValueKind := xlcpvInteger;
  IntegerValue := 0;
  SqlType := 4;
end;
Status := Sheet.RefreshQueryTable('SalesQuery');

Użyj ParameterType = 'cell', ValueKind = xlcpvCell i CellReference dla w pełni kwalifikowanego odwołania do lokalnego arkusza, takiego jak Inputs!$A$1 czy 'Sales Input'!B2; nazwy arkuszy w cudzysłowach używają podwójnych apostrofów, a zakresy, skoroszyty zewnętrzne, nazwy i niekwalifikowane odwołania do komórek są odrzucane

Odświeżanie arkusza tworzy migawkę zapisanych wartości skalarów i dostępnych pamięci podręcznych formuł bez przeliczania ani materializacji spakowanych komórek; brakujące pamięci podręczne formuł i komórki błędów są odrzucane, a brakująca lub pusta komórka dostarcza SQL null tylko przy jawnym obsługiwanym typie SQL

Migawka komórki zachowuje swój typ Variant, co pozwala na wejścia Int64 ze znakiem, Currency, typowane daty i null bez redukowania ich do trwałych pól literałów 32-bitowych całkowitych lub Double; bezpośrednio zapisane literały dat, null i Int64 wykraczają poza natywny model metadanych parametrów, więc dla takich wartości użyj typowanych wiązań komórkowych

SqlType używa kodów typów SQL z ODBC, jawnie mapowanych na typy ADO; nie jest to wartość ADO DataTypeEnum

Obsługiwane jawne typy akceptują również SQL null; tablice, Varianty referencyjne, błędy, liczby nieskończone, nieobsługiwane typy SQL i konwersje gubiące precyzję całkowitą są odrzucane, a NUMERIC lub DECIMAL wymagają metadanych precyzji i skali, których to API wiązania nie dostarcza

ADO otrzymuje typowaną wartość i zadeklarowany rozmiar, z przydzieloną co najmniej jedną jednostką kodu dla pustego tekstu; natywne sterowniki pozostają odpowiedzialne za dialekt SQL, obsługiwane typy parametrów i konwersje wyników, więc zainstalowany provider może nadal odrzucić poprawne wiązanie albo mieć węższe możliwości liczbowe czy datowe

Jet i ACE używają typowanych wiązań OLE DATE dla zwalidowanych wartości DATE, TIME i TIMESTAMP, aby zachować datę i czas niezależnie od zależnych od ustawień regionalnych projekcji tekstu znacznika czasu; reguły walidacji DATE i TIME nadal obowiązują, a możliwości projekcji null pozostają specyficzne dla providera

Parametry wymagają polecenia tekstowego SQL i są ograniczone do 1024 na pobranie, 255 jednostek kodu na nazwę i 32767 jednostek kodu na wartość tekstową; tekst polecenia, odwołania do parametrów, nazwy i ładunki także zużywają budżet bajtów wejścia

Monity i nieznane atrybuty rozszerzeń parametrów są odrzucane; RefreshOnChange pozostaje zachowanymi metadanymi i nie wyzwala odświeżania w tle, a otwieranie czy zapisywanie nie rozwiązuje komórek ani nie wykonuje poleceń

Bezpośrednie Fetch obsługuje literały; FetchWithCellResolver(Connection, Query, MaxRows, out Data, var Abort, AResolver) przyjmuje callback TXLSQueryParameterCellResolver dla wartości komórek, którego wynik Boolean wskazuje, czy zapisana wartość jest dostępna

Callback jest ograniczony do wywołania i nie jest zachowywany; automatyczne odświeżanie arkusza dostarcza własny lokalny resolver, a zarejestrowane niestandardowe providery nadal mają pierwszeństwo i definiują semantykę swoich parametrów

Odświeżanie Web obsługuje zwykłe tabele text/html bez komórek rozpinanych, zagnieżdżonych wybranych tabel ani treści napędzanych skryptami; nieobsługiwane układy i encje są odrzucane zamiast produkować częściowe dane

Rejestracja niestandardowego providera

Workbook.QueryProviders.RegisterProvider(xlckWeb, CustomProvider);
try
  Status := Sheet.RefreshQueryTable('RemoteData');
finally
  Workbook.QueryProviders.RegisterProvider(xlckWeb, nil);
end;

TXLSQueryProviderDispatcher.Create buduje niezależnie posiadany dispatcher do bezpośredniego użycia; skoroszyt tworzy i posiada własną instancję

RegisterProvider(AKind: TXLSConnectionKind; AProvider: TXLSQueryTableProvider) instaluje pożyczony handler dla zadeklarowanego rodzaju połączenia, a nil go wyrejestrowuje; handler musi istnieć dłużej niż rejestracja

Zarejestrowany handler ma pierwszeństwo przed wbudowanym providerem i może obsługiwać uwierzytelnianie albo rodzaje połączeń specyficzne dla aplikacji; zmiany rejestracji, zmiany konfiguracji i rekurencyjny dispatch są odrzucane w trakcie pobierania, a nieprawidłowe wartości enum przed dostępem do tablicy

Fetch(Connection, Query, MaxRows, out Data, var Abort) otrzymuje odłączone metadane podczas odświeżania arkusza i zwraca prostokątne TXLSQueryResultData; anulowanie lub wyjątki czyszczą etapowane wyniki przed ich propagacją

Limity zasobów

MaxInputBytes domyślnie wynosi 67108864 bajtów i ogranicza wejście tekstowe lub Web oraz obsługiwane ładunki wyników baz danych; MaxResultCells domyślnie wynosi 2000000 komórek i ogranicza prostokątny wynik

TimeoutSeconds domyślnie wynosi 30 i konfiguruje obsługiwane natywne fazy bazodanowe lub HTTP; nie jest to gwarantowany deadline dla całej operacji ani dla niestandardowego providera

Wszystkie trzy ustawienia i MaxRows muszą być dodatnie, a timeout musi mieścić się w natywnej liczbie całkowitej milisekund; dispatcher odrzuca nadmiarowe wiersze, kolumny lub komórki bez ucinania, podczas gdy limity bajtów i wejścia są egzekwowane przez wbudowane providery i pozostają odpowiedzialnością zarejestrowanego handlera przy niestandardowych pobraniach

Odświeżanie arkusza waliduje wszystkie wartości wyniku i przywraca komórki oraz metadane zapytania lub tabeli po anulowaniu albo błędach aplikacji; niestandardowe providery pozostają odpowiedzialne za respektowanie własnych limitów operacji zewnętrznych

Natywne wiązania wyników XLSX

Zapytania bazodanowe oparte na tabeli korzystają z relacji tabela–tabela zapytania, spójnych identyfikatorów pól, tożsamości kolumn i ukrytej lokalnej nazwy docelowej; samodzielne obsługiwane cele Text i Web zachowują swój zakres wyniku

TXLSXTable.ColumnUniqueNames[Index]: WideString ujawnia natywne tożsamości kolumn numerowane od zera, zachowując je przy przypisaniu, kopiowaniu i ponownym otwarciu razem z ColumnQueryTableFieldIds

Starsze połączenie Text związane bezpośrednio jako tabela zewnętrzna nie jest obsługiwanym natywnym kształtem eksportu, a zapis odrzuca go przed wyjściem; jawnie odświeżone wartości tekstowe mogą wypełnić zwykłą tabelę, albo zainstalowany sterownik tekstowy ADO/ODBC może dostarczyć natywne zapytanie bazodanowe oparte na tabeli

Niezwiązane lub nieobsługiwane zaimportowane relacje i rozszerzenia XML pozostają zachowane; ta funkcja nie konwertuje nieprzejrzystych zewnętrznych grafów na obsługiwane odświeżalne zapytania

Zobacz API połączeń i transakcyjnych zapytań, aby poznać walidację celów, callbacki postępu i otaczający model metadanych