Providers de requêtes automatiques

Disponible depuis la version 2.384.99 via la facade du classeur XLSX sous Windows ; la sélection automatique de provider n'intervient que lors d'une actualisation explicite de requête

Actualiser une requête existante

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 expose un dispatcher détenu par le classeur et issu de lxQueryProviders ; ne libérez pas le dispatcher vous-même

TXLSXWorksheet.RefreshQueryTable(const AName: WideString; AMaxRows: Integer = 1000000; AOnProgress: TXLSQueryRefreshProgress = nil): Integer ainsi que l'overload qui prend un AIndex en base zéro sélectionnent une requête existante et passent par ce dispatcher

Les overloads existants qui acceptent un TXLSQueryTableProvider explicite continuent d'utiliser ce provider directement, y compris leur rejet habituel quand le provider est absent ; ils ne basculent pas vers la distribution automatique

L'actualisation renvoie 1 en cas de succès, 0 en cas d'annulation ou -1 en cas d'échec, avec les codes de diagnostic 1401 et 1400 sous xlsOperationRefresh ; l'application transactionnelle des résultats, la validation de schéma et le comportement existant pour les literal strings et le formatage restent en vigueur

Ces diagnostics se nomment xlsDiagnosticQueryRefreshCancelled et xlsDiagnosticQueryRefreshFailed ; l'acquisition de la garde d'écriture du classeur a lieu avant la conversion du statut, donc une vue de lecture figée ou tout autre refus de la garde d'écriture lève une exception

L'ouverture et l'enregistrement d'un classeur ne récupèrent jamais de données de connexion, n'évaluent jamais de requêtes et n'agissent jamais sur les métadonnées RefreshOnLoad conservées ; actualisez explicitement chaque requête nécessaire avant d'enregistrer son résultat

Providers intégrés pris en charge

• xlckText lit du texte local délimité ou à largeur fixe avec un décodage strict UTF-8, UTF-16LE, UTF-16BE, Windows-1252 ou Latin-1, des lignes de départ configurables et des types de champs pris en charge, dont six ordres de date et des champs ignorés ; l'entrée délimitée gère aussi les enregistrements multilignes entre guillemets
• xlckAdo, xlckOleDb et xlckOdbc s'appuient sur les drivers ADO et de bases de données Windows installés, avec des connexions et des recordsets en lecture seule ; CommandType = 2 sélectionne du texte SQL et CommandType = 3 une commande de table
• xlckWeb utilise WinHTTP sous Windows pour un GET HTTP ou HTTPS anonyme d'une seule table HTML rectangulaire non vide, désignée par son index positif ou par son nom ; les jeux de caractères de réponse pris en charge sont UTF-8, UTF-16, Windows-1252 et Latin-1

BaseDirectory ne sert de base qu'aux chemins de texte locaux relatifs ; les chaînes de connexion aux bases de données et les URL Web restent des métadonnées de connexion explicites

Une encodage de texte non spécifié accepte une entrée ASCII pure, sauf si un byte order mark pris en charge identifie l'encodage ; une entrée non ASCII exige un encodage pris en charge explicite ou un byte order mark

Pour une connexion Text délimitée, réglez TextPrompt = False, TextDelimited = True et exactement un séparateur, sans fusionner les séparateurs consécutifs ; les connexions nouvellement créées demandent une invite par défaut avec la tabulation comme séparateur, donc désactivez TextTab quand vous choisissez un autre séparateur

Texte à largeur fixe

Réglez TextPrompt = False et TextDelimited = False, puis ajoutez les TextFields dans un ordre de Position en base zéro strictement croissant, à partir de zéro ; chaque champ s'arrête à la position suivante ou au terminateur physique d'enregistrement, et xltiftSkip exclut son champ du résultat

Les positions se comptent en unités de code UTF-16 décodées, pas en octets d'entrée ; une borne qui coupe une surrogate pair est rejetée, et CRLF, LF et CR terminent les enregistrements indépendamment des réglages de séparateur et de qualificateur

Le bourrage des champs est retiré avant la conversion, y compris pour du texte explicitement typé, ce qui correspond au comportement natif vérifié de l'import à largeur fixe ; guillemets, tabulations et séparateurs à l'intérieur d'un champ restent des données littérales, et les enregistrements courts fournissent des champs finaux vides sans modifier le schéma déclaré

Sans TextFields, chaque enregistrement devient un champ general ; TextFirstRow choisit le premier enregistrement du schéma, Query.Headers ignore les valeurs de cet enregistrement, et les enregistrements explicitement vides restent des lignes

Les limites existantes s'appliquent : lignes, octets d'entrée, cellules de résultat et champs de 32767 unités de code ; des métadonnées invalides, des échecs de conversion ou une entrée excessive effacent les données staged avant la mise à jour transactionnelle de la feuille, et une annulation préserve les cellules de résultat précédentes

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

Pour une connexion Web, réglez WebHtmlTables = True et WebHtmlFormat = 'none' ; les requêtes prises en charge rejettent les credentials intégrés, les fragments, l'authentification et les redirections

Les providers intégrés rejettent les métadonnées non prises en charge dans leur type de connexion respectif ; l'actualisation de base de données refuse les commandes OLAP ou serveur, l'indirection par fichier de connexion, les mots de passe stockés et les invites de credentials, l'actualisation Text refuse les invites de fichier, et l'actualisation Web exige des métadonnées de table anonymes

Paramètres de base de données typés

Les commandes SQL textuelles acceptent des marqueurs ? positionnels liés via un ADO Command, dans l'ordre de Connection.Parameters ; les valeurs de paramètres ne remplacent jamais le texte SQL, et les noms étiquettent les liaisons sans modifier l'ordre positionnel

Le preflight compte les marqueurs hors chaînes entre apostrophes, identifiels entre guillemets doubles ou backticks, identifiels entre crochets, commentaires de ligne et commentaires de bloc imbriqués, y compris les échappements doublés de guillemets ou de crochets ; des guillemets ou commentaires non appariés et une discordance du nombre de marqueurs sont rejetés avant l'ouverture de connexion

Utilisez ParameterType = 'value' avec un ValueKind explicite parmi xlcpvInteger, xlcpvDouble, xlcpvBoolean ou xlcpvString et sa propriété de valeur correspondante ; zéro, False et les chaînes vides sont des valeurs, et xlcpvNone ne déduit aucune valeur pendant l'exécution

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

Utilisez ParameterType = 'cell', ValueKind = xlcpvCell et CellReference pour une référence de feuille locale pleinement qualifiée telle que Inputs!$A$1 ou 'Sales Input'!B2 ; les noms de feuilles entre guillemets doublent les apostrophes, tandis que les plages, les classeurs externes, les noms et les références de cellules non qualifiées sont rejetés

L'actualisation de feuille photographie les valeurs scalaires stockées et les caches de formules disponibles, sans recalcul ni matérialisation des cellules compactées ; des caches de formules manquants et des cellules en erreur sont rejetés, tandis qu'une cellule absente ou vide ne fournit un SQL null qu'avec un type SQL pris en charge explicite

La photographie de cellule conserve son type Variant, ce qui autorise des Int64 signés, des Currency, des dates typées et des entrées null sans les réduire aux champs littéraux persistés en entier 32 bits ou Double ; les littéraux date, null et Int64 stockés directement sortent du modèle natif de métadonnées de paramètres, donc servez-vous de liaisons de cellules typées pour ces valeurs

SqlType emploie les codes de types SQL ODBC, mappés explicitement vers les types ADO ; ce n'est pas une valeur de l'ADO DataTypeEnum

Les types explicites pris en charge acceptent aussi le SQL null ; tableaux, Variants de référence, erreurs, nombres non finis, types SQL non pris en charge et conversions qui perdraient de la précision entière sont rejetés, et NUMERIC ou DECIMAL exige des métadonnées de précision et d'échelle que cette API de liaison ne fournit pas

ADO reçoit la valeur typée et la taille déclarée, avec au moins une unité de code allouée pour le texte vide ; les drivers natifs restent responsables du dialecte SQL, des types de paramètres pris en charge et des conversions de résultats, donc un provider installé peut toujours rejeter une liaison valide ou afficher des capacités numériques ou de date plus étroites

Jet et ACE emploient des liaisons OLE DATE typées pour les valeurs DATE, TIME et TIMESTAMP validées, afin de préserver date et heure indépendamment des projections textuelles d'horodatage dépendantes de la locale ; les règles de validation DATE et TIME continuent de s'appliquer, et les capacités de projection null restent propres à chaque provider

Les paramètres exigent une commande SQL textuelle et sont plafonnés à 1024 par extraction, 255 unités de code par nom et 32767 unités de code par valeur texte ; le texte de commande, les références de paramètres, les noms et les payloads consomment aussi le budget d'octets d'entrée

Les invites et les attributs d'extension de paramètres inconnus sont rejetés ; RefreshOnChange reste des métadonnées conservées et ne déclenche aucune actualisation en arrière-plan, et l'ouverture ou l'enregistrement ne résout ni cellules ni commandes

Le Fetch direct accepte des littéraux ; FetchWithCellResolver(Connection, Query, MaxRows, out Data, var Abort, AResolver) prend un callback TXLSQueryParameterCellResolver pour les valeurs de cellules, dont le résultat Boolean indique si une valeur stockée est disponible

Le callback est limité à l'appel et n'est pas conservé ; l'actualisation automatique de feuille fournit son propre resolver local, et les providers personnalisés enregistrés gardent la priorité et possèdent leur sémantique de paramètres

L'actualisation Web accepte des tables text/html simples, sans cellules étendues, sans tables sélectionnées imbriquées ni contenu piloté par scripts ; les dispositions et entités non prises en charge sont rejetées plutôt que de produire des données partielles

Enregistrer un provider personnalisé

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

TXLSQueryProviderDispatcher.Create construit un dispatcher à possession indépendante pour un usage direct ; le classeur crée et possède sa propre instance

RegisterProvider(AKind: TXLSConnectionKind; AProvider: TXLSQueryTableProvider) installe un handler emprunté pour un type de connexion déclaré, et nil le désinstalle ; le handler doit survivre à l'enregistrement

Un handler enregistré passe devant le provider intégré et peut gérer une authentification ou des types de connexion spécifiques à l'application ; changements d'enregistrement, changements de configuration et distribution récursive sont rejetés pendant l'extraction, et des valeurs d'enum invalides sont rejetées avant tout accès au tableau

Fetch(Connection, Query, MaxRows, out Data, var Abort) reçoit des métadonnées détachées pendant l'actualisation de feuille et renvoie un TXLSQueryResultData rectangulaire ; annulation ou exceptions effacent les résultats staged avant leur propagation

Limites de ressources

MaxInputBytes vaut 67108864 octets par défaut et borne l'entrée text ou Web ainsi que les payloads de résultats de bases de données pris en charge ; MaxResultCells vaut 2000000 cellules par défaut et borne le résultat rectangulaire

TimeoutSeconds vaut 30 par défaut et configure les phases natives de base de données ou HTTP prises en charge ; ce n'est pas une échéance garantie pour l'opération complète ni pour un provider personnalisé

Les trois réglages et MaxRows doivent être positifs, et le timeout doit tenir dans un entier natif de millisecondes ; le dispatcher refuse les lignes, colonnes ou cellules excédentaires sans tronquer, tandis que les limites d'octets et d'entrée sont appliquées par les providers intégrés et restent de la responsabilité du handler enregistré pour les extractions personnalisées

L'actualisation de feuille valide toutes les valeurs de résultat et restaure cellules et métadonnées de requête ou de table après une annulation ou des erreurs d'application ; les providers personnalisés restent responsables du respect de leurs propres limites d'opérations externes

Liaisons de résultats natives XLSX

Les requêtes de bases de données adossées à une table utilisent la relation table-vers-table de requête, des field IDs cohérents, des identités de colonnes et un nom de destination local caché ; les destinations Text et Web autonomes prises en charge conservent leur plage de résultat

TXLSXTable.ColumnUniqueNames[Index]: WideString expose des identités de colonnes natives en base zéro, préservées lors des affectations, copies et réouvertures avec ColumnQueryTableFieldIds

Une connexion Text legacy liée directement comme table externe n'est pas une forme d'export native prise en charge et l'enregistrement la refuse avant la sortie ; des valeurs texte explicitement actualisées peuvent remplir une table ordinaire, ou un driver texte ADO/ODBC installé peut fournir une requête de base de données native adossée à une table

Les relations importées sans rapport ou non prises en charge ainsi que le XML d'extension restent préservés ; cette fonctionnalité ne convertit pas des graphes externes opaques en requêtes actualisables prises en charge

Voir les API de connexions et de requêtes transactionnelles pour la validation des destinations, les callbacks de progression et le modèle de métadonnées englobant