Automatische Abfrageprovider

Verfügbar ab Version 2.384.99 über die XLSX-Arbeitsmappen-Fassade unter Windows; die automatische Providerauswahl greift ausschließlich während einer expliziten Abfrageaktualisierung

Vorhandene Abfrage aktualisieren

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 legt einen von der Arbeitsmappe besessenen Dispatcher aus lxQueryProviders offen; geben Sie den Dispatcher nicht selbst frei

TXLSXWorksheet.RefreshQueryTable(const AName: WideString; AMaxRows: Integer = 1000000; AOnProgress: TXLSQueryRefreshProgress = nil): Integer und die Überladung mit nullbasiertem AIndex wählen eine vorhandene Abfrage aus und verwenden diesen Dispatcher

Bestehende Überladungen, die einen expliziten TXLSQueryTableProvider entgegennehmen, nutzen diesen Provider weiterhin direkt, einschließlich ihrer bisherigen Zurückweisung eines fehlenden Providers; sie fallen nicht auf automatisches Dispatching zurück

Die Aktualisierung liefert 1 bei Erfolg, 0 bei Abbruch oder -1 bei Fehlschlag, mit den Diagnosecodes 1401 und 1400 unter xlsOperationRefresh; die bisherige transaktionale Ergebnisanwendung, die Schemavalidierung sowie das Verhalten für Literal-Strings und Formatierung bleiben in Kraft

Diese Diagnosen heißen xlsDiagnosticQueryRefreshCancelled und xlsDiagnosticQueryRefreshFailed; der Schreibschutz der Arbeitsmappe wird vor der Statuskonvertierung angefordert, daher löst ein eingefrorener Lese-View oder eine andere Schreibschutz-Zurückweisung eine Exception aus

Öffnen und Speichern einer Arbeitsmappe holt nie Verbindungsdaten, wertet nie Abfragen aus und greift nie auf gespeicherte RefreshOnLoad-Metadaten zurück; aktualisieren Sie jede benötigte Abfrage explizit, bevor Sie ihr Ergebnis speichern

Unterstützte eingebaute Provider

• xlckText liest lokale Textdateien mit Trennzeichen oder fester Breite mit strikter UTF-8-, UTF-16LE-, UTF-16BE-, Windows-1252- oder Latin-1-Dekodierung, konfigurierten Startzeilen und unterstützten Feldtypen einschließlich sechs Datumsreihenfolgen und überspringbarer Felder; Eingaben mit Trennzeichen unterstützen auch gequotete mehrzeilige Records
• xlckAdo, xlckOleDb und xlckOdbc nutzen installierte Windows-ADO- und Datenbanktreiber mit nur lesenden Verbindungen und Recordsets; CommandType = 2 wählt SQL-Text und CommandType = 3 einen Tabellenbefehl
• xlckWeb nutzt Windows WinHTTP für ein anonymes HTTP- oder HTTPS-GET genau einer nichtleeren rechteckigen HTML-Tabelle, ausgewählt über ihren positiven Index oder Namen; unterstützte Antwort-Zeichensätze sind UTF-8, UTF-16, Windows-1252 und Latin-1

BaseDirectory dient ausschließlich als Basis für relative lokale Textpfade; Datenbank-Connection-Strings und Web-URLs bleiben explizite Verbindungsmetadaten

Eine nicht angegebene Textkodierung akzeptiert reinen ASCII-Input, sofern kein unterstütztes Byte Order Mark die Kodierung identifiziert; Nicht-ASCII-Input erfordert eine explizit unterstützte Kodierung oder ein Byte Order Mark

Für eine Textverbindung mit Trennzeichen setzen Sie TextPrompt = False, TextDelimited = True und genau ein Trennzeichen, ohne aufeinanderfolgende Trennzeichen zusammenzufassen; neu angelegte Verbindungen stehen standardmäßig auf Prompting und Tab-Trennzeichen, löschen Sie TextTab also, wenn Sie ein anderes Trennzeichen wählen

Text mit fester Breite

Setzen Sie TextPrompt = False und TextDelimited = False und fügen Sie dann TextFields in streng aufsteigender nullbasierter Position-Reihenfolge ab null hinzu; jedes Feld endet an der nächsten Position oder am physischen Record-Terminator, und xltiftSkip schließt sein Feld vom Ergebnis aus

Positionen zählen dekodierte UTF-16-Codeeinheiten statt Input-Bytes; eine Grenze, die ein Surrogatpaar spaltet, wird zurückgewiesen, und CRLF, LF und CR beenden Records unabhängig von Trennzeichen- und Qualifier-Einstellungen

Feld-Padding wird vor der Konvertierung entfernt, auch bei explizit typisiertem Text, passend zum verifizierten nativen Import mit fester Breite; Anführungszeichen, Tabs und Trennzeichen innerhalb eines Felds bleiben literale Eingabe, und kurze Records liefern leere nachfolgende Felder, ohne das deklarierte Schema zu ändern

Ohne TextFields ist jeder Record ein General-Feld; TextFirstRow wählt den ersten Schema-Record, Query.Headers überspringt die Werte dieses Records, und explizit leere Records bleiben Zeilen

Die bestehenden Limits für Zeilen, Input-Bytes, Ergebniszellen und 32767-Codeeinheiten pro Feld gelten weiter; ungültige Metadaten, Konvertierungsfehler oder übermäßiger Input räumen die Staging-Daten vor der transaktionalen Arbeitsblattaktualisierung weg, und ein Abbruch erhält die bisherigen Ergebniszellen

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

Für eine Web-Verbindung setzen Sie WebHtmlTables = True und WebHtmlFormat = 'none'; unterstützte Requests weisen eingebettete Credentials, Fragmente, Authentifizierung und Redirects zurück

Die eingebauten Provider weisen nicht unterstützte Metadaten ihrer jeweiligen Verbindungsart zurück; die Datenbankaktualisierung weist OLAP- oder Serverbefehle, Connection-File-Indirektion, gespeicherte Passwörter und Credential-Prompts zurück, die Textaktualisierung weist Datei-Prompts zurück, und die Web-Aktualisierung verlangt anonyme Tabellenmetadaten

Typisierte Datenbankparameter

SQL-Textbefehle unterstützen positionale ?-Marker, die über einen ADO Command gebunden werden, in der Reihenfolge von Connection.Parameters; Parameterwerte ersetzen nie den SQL-Text, und Namen beschriften Bindungen, ohne die positionale Reihenfolge zu ändern

Der Preflight zählt Marker außerhalb von einfach gequoteten Strings, doppelt gequoteten oder Backtick-Bezeichnern, geklammerten Bezeichnern, Zeilenkommentaren und verschachtelten Blockkommentaren, einschließlich verdoppelter Quote- oder Bracket-Escapes; nicht geschlossene Quotes oder Kommentare und Abweichungen bei der Markeranzahl weisen zurück, bevor eine Verbindung geöffnet wird

Verwenden Sie ParameterType = 'value' mit einem expliziten ValueKind aus xlcpvInteger, xlcpvDouble, xlcpvBoolean oder xlcpvString und der zugehörigen Wert-Property; null, False und leere Strings sind Werte, und xlcpvNone leitet während der Ausführung keinen Wert her

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');

Verwenden Sie ParameterType = 'cell', ValueKind = xlcpvCell und CellReference für eine voll qualifizierte lokale Arbeitsblattreferenz wie Inputs!$A$1 oder 'Sales Input'!B2; gequotete Blattnamen verwenden verdoppelte Apostrophe, während Bereiche, externe Arbeitsmappen, Namen und nicht qualifizierte Zellreferenzen zurückgewiesen werden

Die Arbeitsblattaktualisierung erfasst gespeicherte Skalarwerte und verfügbare Formel-Caches ohne Neuberechnung oder Materialisierung gepackter Zellen; fehlende Formel-Caches und Fehlerzellen weisen zurück, während eine fehlende oder leere Zelle nur mit einem explizit unterstützten SQL-Typ SQL-NULL liefert

Der Zell-Snapshot behält seinen Variant-Typ und erlaubt vorzeichenbehaftete Int64-, Currency-, typisierte Datums- und NULL-Eingaben, ohne sie auf die persistierten 32-Bit-Integer- oder Double-Literalfelder zu reduzieren; direkt gespeicherte Datum-, NULL- und Int64-Literale liegen außerhalb des nativen Parametermetadatenmodells, verwenden Sie für diese Werte also typisierte Zellbindungen

SqlType verwendet ODBC-SQL-Typcodes, die explizit auf ADO-Typen gemappt werden; es ist kein ADO-DataTypeEnum-Wert

Unterstützte explizite Typen akzeptieren auch SQL-NULL; Arrays, Referenz-Variants, Fehler, nicht endliche Zahlen, nicht unterstützte SQL-Typen und Konvertierungen, die Integer-Präzision verlieren würden, weisen zurück, und NUMERIC oder DECIMAL verlangen Präzisions- und Scale-Metadaten, die diese Bindungs-API nicht liefert

ADO erhält den typisierten Wert und die deklarierte Größe, mit mindestens einer allokierten Codeeinheit für leeren Text; native Treiber bleiben für SQL-Dialekt, unterstützte Parametertypen und Ergebniskonvertierungen verantwortlich, daher kann ein installierter Provider weiterhin eine gültige Bindung zurückweisen oder engere numerische bzw. Datumsfähigkeiten haben

Jet und ACE verwenden typisierte OLE-DATE-Bindungen für validierte DATE-, TIME- und TIMESTAMP-Werte, um Datum und Zeit unabhängig von gebietsabhängigen Zeitstempel-Textprojektionen zu erhalten; die DATE- und TIME-Validierungsregeln gelten weiterhin, und die NULL-Projektionsfähigkeiten bleiben providerspezifisch

Parameter erfordern einen SQL-Textbefehl und sind auf 1024 pro Fetch, 255 Codeeinheiten pro Name und 32767 Codeeinheiten pro Textwert begrenzt; Befehlstext, Parameterreferenzen, Namen und Payloads zählen ebenfalls gegen das Input-Byte-Budget

Prompts und unbekannte Parameter-Erweiterungsattribute weisen zurück; RefreshOnChange bleibt gespeicherte Metadaten und löst keine Hintergrundaktualisierung aus, und Öffnen oder Speichern löst keine Zellen auf und führt keine Befehle aus

Direktes Fetch unterstützt Literale; FetchWithCellResolver(Connection, Query, MaxRows, out Data, var Abort, AResolver) nimmt einen TXLSQueryParameterCellResolver-Callback für Zellwerte entgegen, dessen Boolean-Ergebnis anzeigt, ob ein gespeicherter Wert verfügbar ist

Der Callback ist auf den Aufruf beschränkt und wird nicht zurückgehalten; die automatische Arbeitsblattaktualisierung stellt ihren lokalen Resolver bereit, und registrierte Custom-Provider behalten weiterhin Vorrang und besitzen ihre Parametersemantik

Die Web-Aktualisierung unterstützt einfache text/html-Tabellen ohne spanning cells, ohne verschachtelte ausgewählte Tabellen und ohne skriptgetriebene Inhalte; nicht unterstützte Layouts und Entities weisen zurück, statt partielle Daten zu erzeugen

Custom-Provider registrieren

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

TXLSQueryProviderDispatcher.Create konstruiert einen unabhängig besessenen Dispatcher für die direkte Verwendung; die Arbeitsmappe erzeugt und besitzt ihre eigene Instanz

RegisterProvider(AKind: TXLSConnectionKind; AProvider: TXLSQueryTableProvider) installiert einen geliehenen Handler für eine deklarierte Verbindungsart, und nil meldet ihn ab; der Handler muss die Registrierung überdauern

Ein registrierter Handler hat Vorrang vor dem eingebauten Provider und kann anwendungsspezifische Authentifizierung oder Verbindungsarten unterstützen; Registrierungsänderungen, Konfigurationsänderungen und rekursives Dispatching weisen während des Fetches zurück, und ungültige Enum-Werte weisen vor dem Arrayzugriff zurück

Fetch(Connection, Query, MaxRows, out Data, var Abort) erhält während der Arbeitsblattaktualisierung abgekoppelte Metadaten und gibt rechteckige TXLSQueryResultData zurück; Abbruch oder Exceptions räumen die Staging-Ergebnisse auf, bevor sie weitergereicht werden

Ressourcenlimits

MaxInputBytes steht standardmäßig auf 67108864 Bytes und begrenzt Text- oder Web-Input sowie unterstützte Datenbank-Ergebnis-Payloads; MaxResultCells steht standardmäßig auf 2000000 Zellen und begrenzt das rechteckige Ergebnis

TimeoutSeconds steht standardmäßig auf 30 und konfiguriert unterstützte native Datenbank- oder HTTP-Phasen; es ist keine garantierte Deadline für die komplette Operation oder für einen Custom-Provider

Alle drei Einstellungen und MaxRows müssen positiv sein, und der Timeout muss in einen nativen Millisekunden-Integer passen; der Dispatcher weist überschüssige Zeilen, Spalten oder Zellen ohne Abschneiden zurück, während Byte- und Input-Limits von den eingebauten Providern durchgesetzt werden und bei Custom-Fetches in der Verantwortung des registrierten Handlers bleiben

Die Arbeitsblattaktualisierung validiert alle Ergebniswerte und stellt Zellen sowie Abfrage- bzw. Tabellenmetadaten nach Abbruch oder Anwendungsfehlern wieder her; Custom-Provider bleiben dafür verantwortlich, ihre eigenen Limits externer Operationen einzuhalten

Native XLSX-Ergebnisbindungen

Datenbankabfragen mit Tabellenbindung nutzen die Table-zu-QueryTable-Beziehung, kohärente Feld-IDs, Spaltenidentitäten und einen versteckten lokalen Zielnamen; eigenständige unterstützte Text- und Web-Ziele behalten ihren Ergebnisbereich

TXLSXTable.ColumnUniqueNames[Index]: WideString legt nullbasierte native Spaltenidentitäten offen und erhält sie zusammen mit ColumnQueryTableFieldIds über Zuweisung, Kopieren und erneutes Öffnen hinweg

Eine Legacy-Textverbindung, die direkt als externe Tabelle gebunden ist, ist keine unterstützte native Exportform, und das Speichern weist sie vor der Ausgabe zurück; explizit aktualisierte Textwerte können eine gewöhnliche Tabelle füllen, oder ein installierter ADO/ODBC-Texttreiber liefert eine native tabellengebundene Datenbankabfrage

Nicht verwandte oder nicht unterstützte importierte Beziehungen und Erweiterungs-XML bleiben erhalten; dieses Feature wandelt opake externe Graphen nicht in unterstützte, aktualisierbare Abfragen um

Siehe Verbindungs- und transaktionale Abfrage-APIs für Zielvalidierung, Progress-Callbacks und das umgebende Metadatenmodell