Provider di query automatici

Disponibile dalla versione 2.384.99 tramite la facciata del workbook XLSX su Windows; la selezione automatica del provider avviene solo durante un aggiornamento esplicito della query

Aggiornare una query esistente

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 espone un dispatcher di proprietà del workbook dall'unità lxQueryProviders; non liberare il dispatcher

TXLSXWorksheet.RefreshQueryTable(const AName: WideString; AMaxRows: Integer = 1000000; AOnProgress: TXLSQueryRefreshProgress = nil): Integer e l'overload che accetta un AIndex a base zero selezionano una query esistente e usano questo dispatcher

Gli overload esistenti che accettano un TXLSQueryTableProvider esplicito continuano a usare direttamente quel provider, compreso il consueto rifiuto di un provider mancante; non ricadono sul dispatch automatico

L'aggiornamento restituisce 1 in caso di successo, 0 in caso di annullamento o -1 in caso di errore, con codici diagnostici 1401 e 1400 sotto xlsOperationRefresh; l'applicazione transazionale dei risultati, la validazione dello schema e il comportamento consolidato per stringhe letterali e formattazione restano in vigore

Queste diagnostiche si chiamano xlsDiagnosticQueryRefreshCancelled e xlsDiagnosticQueryRefreshFailed; l'acquisizione della guardia di scrittura del workbook avviene prima della conversione dello stato, quindi una vista di lettura bloccata o un altro rifiuto della guardia di scrittura solleva un'eccezione

L'apertura e il salvataggio di un workbook non scaricano mai i dati di connessione, non valutano query né agiscono sui metadati RefreshOnLoad conservati; aggiorna esplicitamente ogni query necessaria prima di salvare il suo risultato

Provider incorporati supportati

• xlckText legge testo locale delimitato o a larghezza fissa con decodifica rigorosa UTF-8, UTF-16LE, UTF-16BE, Windows-1252 o Latin-1, righe iniziali configurabili e tipi di campo supportati tra cui sei ordinamenti di data e campi da saltare; l'input delimitato supporta anche record multilinea tra virgolette
• xlckAdo, xlckOleDb e xlckOdbc usano i driver ADO e di database Windows installati con connessioni e recordset in sola lettura; CommandType = 2 seleziona testo SQL e CommandType = 3 seleziona un comando tabella
• xlckWeb usa WinHTTP di Windows per una GET HTTP o HTTPS anonima di una tabella HTML rettangolare non vuota selezionata per indice positivo o per nome; i set di caratteri di risposta supportati sono UTF-8, UTF-16, Windows-1252 e Latin-1

BaseDirectory fornisce la base solo per i percorsi di testo locali relativi; le stringhe di connessione ai database e gli URL Web restano metadati di connessione espliciti

Una codifica del testo non specificata accetta input solo ASCII a meno che un byte order mark supportato identifichi la codifica; l'input non ASCII richiede una codifica supportata esplicita o un byte order mark

Per una connessione Text delimitata, imposta TextPrompt = False, TextDelimited = True ed esattamente un delimitatore, senza collassare i delimitatori consecutivi; le connessioni appena create hanno per impostazione predefinita il prompt e il delimitatore tab, quindi azzera TextTab quando scegli un delimitatore diverso

Testo a larghezza fissa

Imposta TextPrompt = False e TextDelimited = False, poi aggiungi i TextFields in ordine di Position a base zero strettamente crescente, partendo da zero; ogni campo termina alla posizione successiva o al terminatore fisico del record, e xltiftSkip esclude il suo campo dal risultato

Le posizioni contano unità di codice UTF-16 decodificate, non byte di input; un confine che spezza una coppia surrogata viene rifiutato, e CRLF, LF e CR terminano i record indipendentemente dalle impostazioni di delimitatore e qualificatore

Il padding dei campi viene rimosso prima della conversione, compreso il testo tipizzato esplicitamente, in accordo con il comportamento verificato dell'importazione nativa a larghezza fissa; virgolette, tab e caratteri delimitatori dentro un campo restano input letterale, e i record corti forniscono campi finali vuoti senza cambiare lo schema dichiarato

Senza TextFields, ogni record è un campo generale; TextFirstRow seleziona il primo record dello schema, Query.Headers salta i valori di quel record, e i record vuoti espliciti restano righe

Si applicano i limiti esistenti su righe, byte di input, celle risultato e campi di 32767 unità di codice; metadati non validi, errori di conversione o input eccessivo cancellano i dati in staging prima dell'aggiornamento transazionale del foglio di lavoro, e l'annullamento preserva le celle del risultato precedente

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

Per una connessione Web, imposta WebHtmlTables = True e WebHtmlFormat = 'none'; le richieste supportate rifiutano credenziali incorporate, frammenti, autenticazione e redirect

I provider incorporati rifiutano i metadati non supportati nei rispettivi tipi di connessione; l'aggiornamento da database rifiuta comandi OLAP o server, indirezione tramite file di connessione, password memorizzate e prompt di credenziali, l'aggiornamento Text rifiuta i prompt su file, e l'aggiornamento Web richiede metadati di tabella anonimi

Parametri di database tipizzati

I comandi di testo SQL supportano segnaposto posizionali ? associati tramite un ADO Command, nell'ordine di Connection.Parameters; i valori dei parametri non sostituiscono mai il testo SQL, e i nomi etichettano i binding senza cambiare l'ordine posizionale

Il preflight conteggia i segnaposto fuori da stringhe tra apici singoli, identificatori tra virgolette doppie o backtick, identificatori tra parentesi quadre, commenti di riga e commenti a blocco annidati, inclusi gli escape di apici o parentesi raddoppiati; apici o commenti non bilanciati e disallineamenti nel conteggio dei segnaposto vengono rifiutati prima di aprire una connessione

Usa ParameterType = 'value' con un ValueKind esplicito tra xlcpvInteger, xlcpvDouble, xlcpvBoolean o xlcpvString e la corrispondente proprietà del valore; zero, False e stringhe vuote sono valori, e xlcpvNone non inferisce un valore durante l'esecuzione

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

Usa ParameterType = 'cell', ValueKind = xlcpvCell e CellReference per un riferimento locale pienamente qualificato con foglio, come Inputs!$A$1 o 'Sales Input'!B2; i nomi di foglio tra apici usano apostrofi raddoppiati, e intervalli, workbook esterni, nomi e riferimenti di cella non qualificati vengono rifiutati

L'aggiornamento del foglio di lavoro scatta uno snapshot dei valori scalari memorizzati e delle cache delle formule disponibili, senza ricalcolo né materializzazione delle celle compattate; cache di formule mancanti e celle di errore vengono rifiutate, mentre una cella mancante o vuota fornisce un SQL null solo con un tipo SQL supportato dichiarato esplicitamente

Lo snapshot della cella conserva il suo tipo Variant, consentendo input Int64 con segno, Currency, date tipizzate e null senza ridurli ai campi letterali persistiti a 32 bit o Double; i letterali date, null e Int64 memorizzati direttamente restano fuori dal modello nativo di metadati dei parametri, quindi per quei valori usa binding di celle tipizzati

SqlType usa i codici di tipo SQL ODBC, mappati esplicitamente ai tipi ADO; non è un valore di ADO DataTypeEnum

Anche i tipi espliciti supportati accettano SQL null; array, Variant per riferimento, errori, numeri non finiti, tipi SQL non supportati e conversioni che perderebbero precisione intera vengono rifiutati, e NUMERIC o DECIMAL richiedono metadati di precisione e scala che questa API di binding non fornisce

ADO riceve il valore tipizzato e la dimensione dichiarata, con almeno un'unità di codice allocata per il testo vuoto; i driver nativi restano responsabili del dialetto SQL, dei tipi di parametro supportati e delle conversioni dei risultati, quindi un provider installato può comunque rifiutare un binding valido o avere capacità numeriche o di data più ristrette

Jet e ACE usano binding OLE DATE tipizzati per i valori DATE, TIME e TIMESTAMP validati, per preservare data e ora indipendentemente dalle proiezioni testuali dei timestamp dipendenti dal locale; le regole di validazione di DATE e TIME restano applicate, e le capacità di proiezione del null restano specifiche del provider

I parametri richiedono un comando di testo SQL e sono limitati a 1024 per fetch, 255 unità di codice per nome e 32767 unità di codice per valore di testo; anche il testo del comando, i riferimenti ai parametri, i nomi e i payload consumano il budget di byte di input

Prompt e attributi di estensione dei parametri sconosciuti vengono rifiutati; RefreshOnChange resta un metadato conservato e non attiva aggiornamenti in background, e apertura o salvataggio non risolvono celle né eseguono comandi

Il Fetch diretto supporta i letterali; FetchWithCellResolver(Connection, Query, MaxRows, out Data, var Abort, AResolver) accetta una callback TXLSQueryParameterCellResolver per i valori di cella, il cui risultato Boolean indica se un valore memorizzato è disponibile

La callback vale solo per la chiamata e non viene conservata; l'aggiornamento automatico del foglio di lavoro fornisce il suo resolver locale, e i provider personalizzati registrati continuano ad avere precedenza e a definire la semantica dei propri parametri

L'aggiornamento Web supporta tabelle text/html semplici, senza celle estese, tabelle selezionate annidate o contenuto guidato da script; layout ed entità non supportati vengono rifiutati invece di produrre dati parziali

Registrare un provider personalizzato

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

TXLSQueryProviderDispatcher.Create costruisce un dispatcher di proprietà indipendente per uso diretto; il workbook crea e possiede la propria istanza

RegisterProvider(AKind: TXLSConnectionKind; AProvider: TXLSQueryTableProvider) installa un handler preso in prestito per un tipo di connessione dichiarato, e nil lo deregistra; l'handler deve sopravvivere alla registrazione

Un handler registrato ha precedenza sul provider incorporato e può supportare autenticazioni o tipi di connessione specifici dell'applicazione; cambi di registrazione, cambi di configurazione e dispatch ricorsivo vengono rifiutati durante il fetch, e valori enum non validi vengono rifiutati prima dell'accesso all'array

Fetch(Connection, Query, MaxRows, out Data, var Abort) riceve metadati scollegati durante l'aggiornamento del foglio di lavoro e restituisce un TXLSQueryResultData rettangolare; annullamento o eccezioni cancellano i risultati in staging prima della propagazione

Limiti di risorse

MaxInputBytes vale 67108864 byte per impostazione predefinita e limita l'input di testo o Web e i payload dei risultati dei database supportati; MaxResultCells vale 2000000 celle per impostazione predefinita e limita il risultato rettangolare

TimeoutSeconds vale 30 per impostazione predefinita e configura le fasi native di database o HTTP supportate; non è una scadenza garantita per l'operazione completa né per un provider personalizzato

Tutte e tre le impostazioni e MaxRows devono essere positive, e il timeout deve stare in un intero nativo di millisecondi; il dispatcher rifiuta righe, colonne o celle in eccesso senza troncamento, mentre i limiti di byte e di input sono applicati dai provider incorporati e, per i fetch personalizzati, restano responsabilità dell'handler registrato

L'aggiornamento del foglio di lavoro valida tutti i valori del risultato e ripristina celle e metadati di query o tabella dopo un annullamento o errori di applicazione; i provider personalizzati restano responsabili di rispettare i propri limiti sulle operazioni esterne

Binding nativi dei risultati XLSX

Le query di database supportate da tabelle usano la relazione tabella-query-tabella, ID di campo coerenti, identità di colonna e un nome di destinazione locale nascosto; le destinazioni Text e Web supportate standalone conservano il loro intervallo di risultato

TXLSXTable.ColumnUniqueNames[Index]: WideString espone le identità di colonna native a base zero, preservandole attraverso assegnazione, copia e riapertura insieme a ColumnQueryTableFieldIds

Una connessione Text legacy legata direttamente come tabella esterna non è una forma di esportazione nativa supportata e il salvataggio la rifiuta prima dell'output; i valori di testo aggiornati esplicitamente possono popolare una tabella ordinaria, oppure un driver di testo ADO/ODBC installato può fornire una query di database nativa supportata da tabella

Le relazioni importate non correlate o non supportate e l'XML di estensione restano preservati; questa funzionalità non converte grafi esterni opachi in query aggiornabili supportate

Vedi le API di connessione e di query transazionale per la validazione delle destinazioni, le callback di avanzamento e il modello di metadati circostante