Provedores de consulta automáticos

Disponível desde a versão 2.384.99 por meio da fachada de pasta de trabalho XLSX no Windows; a seleção automática de provedor ocorre apenas durante uma atualização de consulta explícita

Atualizar uma consulta existente

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 expõe um dispatcher de propriedade da pasta de trabalho a partir de lxQueryProviders; não libere o dispatcher

TXLSXWorksheet.RefreshQueryTable(const AName: WideString; AMaxRows: Integer = 1000000; AOnProgress: TXLSQueryRefreshProgress = nil): Integer e o overload que recebe um AIndex com base zero selecionam uma consulta existente e usam esse dispatcher

Os overloads existentes que aceitam um TXLSQueryTableProvider explícito continuam usando esse provedor diretamente, incluindo a rejeição que já fazem de um provedor ausente; eles não recorrem ao dispatch automático

A atualização retorna 1 em caso de sucesso, 0 em caso de cancelamento ou -1 em caso de falha, com os códigos de diagnóstico 1401 e 1400 sob xlsOperationRefresh; a aplicação transacional de resultados existente, a validação de esquema e o comportamento de strings literais e de formatação permanecem em vigor

Esses diagnósticos se chamam xlsDiagnosticQueryRefreshCancelled e xlsDiagnosticQueryRefreshFailed; a aquisição da guarda de gravação da pasta de trabalho ocorre antes da conversão do status, de modo que uma visualização de leitura congelada ou outra rejeição da guarda de gravação dispara uma exceção

Abrir e salvar uma pasta de trabalho nunca busca dados de conexão, não avalia consultas nem age sobre metadados RefreshOnLoad retidos; atualize explicitamente cada consulta necessária antes de salvar o resultado

Provedores internos com suporte

• xlckText lê texto local delimitado ou de largura fixa com decodificação estrita de UTF-8, UTF-16LE, UTF-16BE, Windows-1252 ou Latin-1, linhas iniciais configuradas e tipos de campo com suporte, incluindo seis ordens de data e campos ignorados; a entrada delimitada também aceita registros multilinha entre aspas
• xlckAdo, xlckOleDb e xlckOdbc usam drivers de banco de dados e ADO do Windows instalados, com conexões e recordsets somente leitura; CommandType = 2 seleciona texto SQL e CommandType = 3 seleciona um comando de tabela
• xlckWeb usa WinHTTP do Windows para um GET anônimo via HTTP ou HTTPS de uma tabela HTML retangular não vazia, selecionada pelo índice positivo ou pelo nome; os conjuntos de caracteres de resposta com suporte são UTF-8, UTF-16, Windows-1252 e Latin-1

BaseDirectory fornece a base apenas para caminhos de texto locais relativos; strings de conexão de banco de dados e URLs Web continuam sendo metadados de conexão explícitos

Uma codificação de texto não especificada aceita entrada somente ASCII, a menos que uma marca de ordem de byte com suporte identifique a codificação; entrada não ASCII exige uma codificação com suporte explícita ou uma marca de ordem de byte

Para uma conexão Text delimitada, defina TextPrompt = False, TextDelimited = True e exatamente um delimitador, sem colapsar delimitadores consecutivos; conexões recém-criadas têm como padrão prompt e delimitador de tabulação, então limpe TextTab ao escolher outro delimitador

Texto de largura fixa

Defina TextPrompt = False e TextDelimited = False e adicione TextFields em ordem de Position com base zero estritamente crescente, começando em zero; cada campo termina na próxima posição ou no terminador físico do registro, e xltiftSkip exclui esse campo do resultado

As posições contam unidades de código UTF-16 decodificadas, e não bytes de entrada; um limite que divide um par surrogate é rejeitado, e CRLF, LF e CR terminam registros independentemente das configurações de delimitador e qualificador

O preenchimento de campo é removido antes da conversão, incluindo texto com tipo explícito, correspondendo ao comportamento nativo verificado de importação de largura fixa; aspas, tabulações e caracteres delimitadores dentro de um campo permanecem como entrada literal, e registros curtos fornecem campos finais vazios sem alterar o esquema declarado

Sem TextFields, cada registro é um campo geral; TextFirstRow seleciona o primeiro registro do esquema, Query.Headers ignora os valores desse registro, e registros em branco explícitos permanecem como linhas

Os limites existentes de linhas, de bytes de entrada, de células de resultado e de campos com 32767 unidades de código continuam valendo; metadados inválidos, falhas de conversão ou entrada excessiva limpam os dados preparados antes da atualização transacional da planilha, e o cancelamento preserva as células de resultado anteriores

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

Para uma conexão Web, defina WebHtmlTables = True e WebHtmlFormat = 'none'; as solicitações com suporte rejeitam credenciais embutidas, fragmentos, autenticação e redirecionamentos

Os provedores internos rejeitam metadados sem suporte em seus respectivos tipos de conexão; a atualização de banco de dados rejeita comandos OLAP ou de servidor, indireção por arquivo de conexão, senhas armazenadas e prompts de credencial, a atualização Text rejeita prompts de arquivo, e a atualização Web exige metadados de tabela anônimos

Parâmetros de banco de dados tipados

Comandos de texto SQL aceitam marcadores posicionais ? vinculados por meio de um ADO Command, na ordem de Connection.Parameters; valores de parâmetro nunca substituem o texto SQL, e nomes rotulam as vinculações sem alterar a ordem posicional

O preflight conta os marcadores fora de strings entre aspas simples, identificadores entre aspas duplas ou crases, identificadores entre colchetes, comentários de linha e comentários de bloco aninhados, incluindo escapes de aspas ou colchetes duplicados; aspas ou comentários sem par e divergências na contagem de marcadores são rejeitados antes de abrir uma conexão

Use ParameterType = 'value' com um ValueKind explícito de xlcpvInteger, xlcpvDouble, xlcpvBoolean ou xlcpvString e a propriedade de valor correspondente; zero, False e strings vazias são valores, e xlcpvNone não infere um valor durante a execução

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

Use ParameterType = 'cell', ValueKind = xlcpvCell e CellReference para uma referência de planilha local totalmente qualificada, como Inputs!$A$1 ou 'Sales Input'!B2; nomes de planilha entre aspas usam apóstrofos duplicados, e intervalos, pastas de trabalho externas, nomes e referências de célula não qualificadas são rejeitados

A atualização da planilha tira um snapshot dos valores escalares armazenados e dos caches de fórmula disponíveis, sem recálculo nem materialização de células compactadas; caches de fórmula ausentes e células de erro são rejeitados, enquanto uma célula ausente ou em branco fornece SQL null apenas com um tipo SQL com suporte explícito

O snapshot de célula retém seu tipo Variant, permitindo entradas Int64 com sinal, Currency, data tipada e null sem reduzi-las aos campos literais persistidos de inteiro de 32 bits ou Double; literais de data, null e Int64 armazenados diretamente estão fora do modelo nativo de metadados de parâmetro, então use vinculações de célula tipadas para esses valores

SqlType usa códigos de tipo SQL do ODBC, que são mapeados explicitamente para tipos ADO; não é um valor de ADO DataTypeEnum

Os tipos explícitos com suporte também aceitam SQL null; arrays, Variants de referência, erros, números não finitos, tipos SQL sem suporte e conversões que perderiam precisão inteira são rejeitados, e NUMERIC ou DECIMAL exigem metadados de precisão e escala que esta API de vinculação não fornece

O ADO recebe o valor tipado e o tamanho declarado, com pelo menos uma unidade de código alocada para texto vazio; os drivers nativos continuam responsáveis pelo dialeto SQL, pelos tipos de parâmetro com suporte e pelas conversões de resultado, de modo que um provedor instalado ainda pode rejeitar uma vinculação válida ou ter recursos numéricos ou de data mais restritos

Jet e ACE usam vinculações OLE DATE tipadas para valores DATE, TIME e TIMESTAMP validados, preservando data e hora de forma independente das projeções de texto de timestamp dependentes de localidade; as regras de validação de DATE e TIME continuam valendo, e os recursos de projeção de null permanecem específicos do provedor

Os parâmetros exigem um comando de texto SQL e são limitados a 1024 por fetch, 255 unidades de código por nome e 32767 unidades de código por valor de texto; o texto do comando, as referências de parâmetro, os nomes e os payloads também consomem o orçamento de bytes de entrada

Prompts e atributos de extensão de parâmetro desconhecidos são rejeitados; RefreshOnChange continua sendo um metadado retido e não dispara atualização em segundo plano, e abrir ou salvar não resolve células nem executa comandos

O Fetch direto aceita literais; FetchWithCellResolver(Connection, Query, MaxRows, out Data, var Abort, AResolver) aceita um callback TXLSQueryParameterCellResolver para valores de célula, cujo resultado Boolean indica se há um valor armazenado disponível

O callback tem escopo da chamada e não é retido; a atualização automática da planilha fornece seu resolver local, e provedores personalizados registrados continuam tendo precedência e são donos da semântica de seus parâmetros

A atualização Web aceita tabelas text/html simples, sem células com span, tabelas selecionadas aninhadas ou conteúdo dirigido por script; layouts e entidades sem suporte são rejeitados em vez de produzir dados parciais

Registrar um provedor personalizado

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

TXLSQueryProviderDispatcher.Create constrói um dispatcher de propriedade independente para uso direto; a pasta de trabalho cria e é dona da própria instância

RegisterProvider(AKind: TXLSConnectionKind; AProvider: TXLSQueryTableProvider) instala um manipulador emprestado para um tipo de conexão declarado, e nil cancela o registro; o manipulador deve sobreviver ao registro

Um manipulador registrado tem precedência sobre o provedor interno e pode aceitar autenticação ou tipos de conexão específicos do aplicativo; mudanças de registro, mudanças de configuração e dispatch recursivo são rejeitados durante o fetch, e valores de enum inválidos são rejeitados antes do acesso ao array

Fetch(Connection, Query, MaxRows, out Data, var Abort) recebe metadados desanexados durante a atualização da planilha e retorna um TXLSQueryResultData retangular; cancelamento ou exceções limpam os resultados preparados antes da propagação

Limites de recursos

MaxInputBytes tem como padrão 67108864 bytes e limita a entrada de texto ou Web e os payloads de resultado de banco de dados com suporte; MaxResultCells tem como padrão 2000000 células e limita o resultado retangular

TimeoutSeconds tem como padrão 30 e configura as fases nativas de banco de dados ou HTTP com suporte; não é um prazo garantido para a operação completa nem para um provedor personalizado

As três configurações e MaxRows devem ser positivas, e o timeout deve caber em um inteiro nativo de milissegundos; o dispatcher rejeita excesso de linhas, colunas ou células sem truncamento, enquanto os limites de bytes e de entrada são aplicados pelos provedores internos e continuam sendo responsabilidade do manipulador registrado em fetches personalizados

A atualização da planilha valida todos os valores de resultado e restaura células e metadados de consulta ou tabela após cancelamento ou erros de aplicação; provedores personalizados continuam responsáveis por honrar os próprios limites de operações externas

Vinculações nativas de resultado XLSX

Consultas de banco de dados baseadas em tabela usam a relação tabela-para-query-table, IDs de campo coerentes, identidades de coluna e um nome de destino local oculto; destinos Text e Web com suporte autônomos mantêm seu intervalo de resultado

TXLSXTable.ColumnUniqueNames[Index]: WideString expõe identidades nativas de coluna com base zero, preservando-as por atribuição, cópia e reabertura junto com ColumnQueryTableFieldIds

Uma conexão Text legada vinculada diretamente como tabela externa não é uma forma de exportação nativa com suporte, e salvar a rejeita antes da saída; valores de texto atualizados explicitamente podem popular uma tabela comum, ou um driver de texto ADO/ODBC instalado pode fornecer uma consulta de banco de dados nativa baseada em tabela

Relações importadas não relacionadas ou sem suporte e XML de extensão permanecem preservados; este recurso não converte grafos externos opacos em consultas atualizáveis com suporte

Consulte as APIs de conexão e de consulta transacional para validação de destino, callbacks de progresso e o modelo de metadados ao redor