Proveedores de consulta automáticos

Disponible desde la versión 2.384.99 a través de la fachada de libros XLSX en Windows; la selección automática de proveedores ocurre únicamente durante una actualización de consulta explícita

Actualizar una 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 expone un despachador de propiedad del libro desde lxQueryProviders; no libere el despachador

TXLSXWorksheet.RefreshQueryTable(const AName: WideString; AMaxRows: Integer = 1000000; AOnProgress: TXLSQueryRefreshProgress = nil): Integer y la sobrecarga que recibe un AIndex basado en cero seleccionan una consulta existente y usan este despachador

Las sobrecargas existentes que reciben un TXLSQueryTableProvider explícito siguen usando ese proveedor directamente, incluido su rechazo actual de un proveedor ausente; no hacen fallback al despacho automático

La actualización devuelve 1 en caso de éxito, 0 en caso de cancelación o -1 en caso de falla, con los códigos de diagnóstico 1401 y 1400 bajo xlsOperationRefresh; la aplicación transaccional de resultados, la validación de esquema, las cadenas literales y el comportamiento de formato existentes siguen vigentes

Estos diagnósticos se llaman xlsDiagnosticQueryRefreshCancelled y xlsDiagnosticQueryRefreshFailed; la adquisición del guardián de escritura del libro ocurre antes de la conversión del estado, de modo que una vista de lectura congelada u otro rechazo del guardián de escritura lanza una excepción

Abrir y guardar un libro nunca obtiene datos de conexión, evalúa consultas ni actúa sobre los metadatos RefreshOnLoad retenidos; actualice explícitamente cada consulta requerida antes de guardar su resultado

Proveedores integrados admitidos

• xlckText lee texto local delimitado o de ancho fijo con decodificación estricta UTF-8, UTF-16LE, UTF-16BE, Windows-1252 o Latin-1, filas iniciales configuradas y tipos de campo admitidos que incluyen seis órdenes de fecha y campos omitidos; la entrada delimitada también admite registros multilínea entre comillas
• xlckAdo, xlckOleDb y xlckOdbc usan controladores ADO y de bases de datos instalados en Windows con conexiones y recordsets de solo lectura; CommandType = 2 selecciona texto SQL y CommandType = 3 selecciona un comando de tabla
• xlckWeb usa WinHTTP de Windows para un GET HTTP o HTTPS anónimo de una tabla HTML rectangular no vacía seleccionada por su índice positivo o su nombre; los juegos de caracteres de respuesta admitidos son UTF-8, UTF-16, Windows-1252 y Latin-1

BaseDirectory aporta la base únicamente para rutas locales de texto relativas; las cadenas de conexión de bases de datos y las URL Web siguen siendo metadatos de conexión explícitos

Una codificación de texto sin especificar acepta entrada solo ASCII, salvo que una marca de orden de bytes admitida identifique la codificación; la entrada no ASCII requiere una codificación admitida explícita o una marca de orden de bytes

Para una conexión Text delimitada, defina TextPrompt = False, TextDelimited = True y exactamente un delimitador, sin colapsar delimitadores consecutivos; las conexiones recién creadas usan como valores predeterminados preguntar al usuario y el tabulador como delimitador, así que limpie TextTab al elegir otro delimitador

Texto de ancho fijo

Defina TextPrompt = False y TextDelimited = False, y luego agregue TextFields en orden de Position basado en cero estrictamente creciente, empezando en cero; cada campo termina en la siguiente posición o en el terminador físico del registro, y xltiftSkip excluye su campo del resultado

Las posiciones cuentan unidades de código UTF-16 decodificadas en lugar de bytes de entrada; un límite que divida un par suplente provoca rechazo, y CRLF, LF y CR terminan los registros con independencia de la configuración de delimitadores y calificadores

El relleno de los campos se recorta antes de la conversión, incluido el texto con tipo explícito, en consonancia con el comportamiento verificado de importación nativa de ancho fijo; las comillas, los tabuladores y los caracteres delimitadores dentro de un campo permanecen como entrada literal, y los registros cortos aportan campos finales vacíos sin alterar el esquema declarado

Sin TextFields, cada registro es un campo general; TextFirstRow selecciona el primer registro del esquema, Query.Headers omite los valores de ese registro, y los registros en blanco explícitos permanecen como filas

Se aplican los límites existentes de filas, bytes de entrada, celdas de resultado y campos de 32767 unidades de código; los metadatos inválidos, las fallas de conversión o la entrada excesiva limpian los datos en preparación antes de la actualización transaccional de la hoja, y la cancelación preserva las celdas de resultado anteriores

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

Para una conexión Web, defina WebHtmlTables = True y WebHtmlFormat = 'none'; las solicitudes admitidas rechazan credenciales incrustadas, fragmentos, autenticación y redirecciones

Los proveedores integrados rechazan los metadatos no admitidos en sus respectivos tipos de conexión; la actualización de bases de datos rechaza comandos OLAP o de servidor, direccionamiento indirecto por archivo de conexión, contraseñas almacenadas y peticiones de credenciales, la actualización Text rechaza peticiones de archivo, y la actualización Web exige metadatos de tabla anónimos

Parámetros de base de datos con tipo

Los comandos de texto SQL admiten marcadores ? posicionales enlazados mediante un Command de ADO, en el orden de Connection.Parameters; los valores de parámetros nunca reemplazan el texto SQL, y los nombres etiquetan los enlaces sin alterar el orden posicional

La verificación previa cuenta los marcadores fuera de cadenas entre comillas simples, identificadores entre comillas dobles o acentos graves, identificadores entre corchetes, comentarios de línea y comentarios de bloque anidados, incluidos los escapes de comillas o corchetes doblados; las comillas o comentarios sin cerrar y las discrepancias en el número de marcadores provocan rechazo antes de abrir una conexión

Use ParameterType = 'value' con un ValueKind explícito de xlcpvInteger, xlcpvDouble, xlcpvBoolean o xlcpvString y su propiedad de valor correspondiente; cero, False y las cadenas vacías son valores, y xlcpvNone no infiere un valor durante la ejecución

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 y CellReference para una referencia local de hoja de cálculo completamente calificada como Inputs!$A$1 o 'Sales Input'!B2; los nombres de hoja entre comillas usan apóstrofos doblados, y los rangos, los libros externos, los nombres y las referencias de celda sin calificar provocan rechazo

La actualización de la hoja toma una instantánea de los valores escalares almacenados y de las cachés de fórmula disponibles sin recálculo ni materialización de celdas empaquetadas; las cachés de fórmula ausentes y las celdas de error provocan rechazo, mientras que una celda ausente o en blanco aporta un SQL null solo con un tipo SQL admitido explícito

La instantánea de la celda conserva su tipo Variant, lo que permite entradas Int64 con signo, Currency, fechas con tipo y null sin reducirlas a los campos literales enteros de 32 bits o Double persistidos; los literales de fecha, null e Int64 almacenados directamente quedan fuera del modelo de metadatos de parámetros nativo, así que use enlaces de celda con tipo para esos valores

SqlType usa códigos de tipo SQL de ODBC, que se mapean explícitamente a tipos de ADO; no es un valor de DataTypeEnum de ADO

Los tipos explícitos admitidos también aceptan SQL null; las matrices, los Variants de referencia, los errores, los números no finitos, los tipos SQL no admitidos y las conversiones que perderían precisión entera provocan rechazo, y NUMERIC o DECIMAL exigen metadatos de precisión y escala que esta API de enlace no proporciona

ADO recibe el valor con tipo y el tamaño declarado, con al menos una unidad de código asignada para texto vacío; los controladores nativos siguen siendo responsables del dialecto SQL, de los tipos de parámetros admitidos y de las conversiones de resultados, de modo que un proveedor instalado aún puede rechazar un enlace válido o tener capacidades numéricas o de fecha más limitadas

Jet y ACE usan enlaces OLE DATE con tipo para los valores DATE, TIME y TIMESTAMP validados, a fin de preservar fecha y hora con independencia de las proyecciones de texto de marca de tiempo dependientes de la configuración regional; las reglas de validación de DATE y TIME siguen aplicándose, y las capacidades de proyección de null siguen siendo específicas de cada proveedor

Los parámetros exigen un comando de texto SQL y están limitados a 1024 por lectura, 255 unidades de código por nombre y 32767 unidades de código por valor de texto; el texto del comando, las referencias de parámetros, los nombres y las cargas útiles también consumen el presupuesto de bytes de entrada

Las peticiones al usuario y los atributos de extensión de parámetros desconocidos provocan rechazo; RefreshOnChange sigue siendo metadatos retenidos y no activa una actualización en segundo plano, y abrir o guardar no resuelve celdas ni ejecuta comandos

El Fetch directo admite literales; FetchWithCellResolver(Connection, Query, MaxRows, out Data, var Abort, AResolver) acepta una devolución de llamada TXLSQueryParameterCellResolver para valores de celda, cuyo resultado Boolean indica si hay un valor almacenado disponible

La devolución de llamada tiene el alcance de la llamada y no se retiene; la actualización automática de la hoja aporta su resolutor local, y los proveedores personalizados registrados siguen teniendo precedencia y son dueños de su semántica de parámetros

La actualización Web admite tablas text/html simples sin celdas expandidas, tablas seleccionadas anidadas ni contenido dirigido por scripts; los diseños y las entidades no admitidos provocan rechazo en lugar de producir datos parciales

Registrar un proveedor personalizado

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

TXLSQueryProviderDispatcher.Create construye un despachador de propiedad independiente para uso directo; el libro crea y posee su propia instancia

RegisterProvider(AKind: TXLSConnectionKind; AProvider: TXLSQueryTableProvider) instala un controlador prestado para un tipo de conexión declarado, y nil lo desregistra; el controlador debe sobrevivir al registro

Un controlador registrado tiene precedencia sobre el proveedor integrado y puede admitir autenticación específica de la aplicación o tipos de conexión propios; los cambios de registro, los cambios de configuración y el despacho recursivo provocan rechazo durante la lectura, y los valores de enum inválidos provocan rechazo antes del acceso al arreglo

Fetch(Connection, Query, MaxRows, out Data, var Abort) recibe metadatos desacoplados durante la actualización de la hoja y devuelve un TXLSQueryResultData rectangular; la cancelación o las excepciones limpian los resultados en preparación antes de propagarlos

Límites de recursos

MaxInputBytes tiene un valor predeterminado de 67108864 bytes y acota la entrada de texto o Web y las cargas de resultados de bases de datos admitidas; MaxResultCells tiene un valor predeterminado de 2000000 celdas y acota el resultado rectangular

TimeoutSeconds tiene un valor predeterminado de 30 y configura las fases nativas admitidas de bases de datos o HTTP; no es un plazo garantizado para la operación completa ni para un proveedor personalizado

Las tres configuraciones y MaxRows deben ser positivas, y el timeout debe caber en un entero nativo de milisegundos; el despachador rechaza filas, columnas o celdas en exceso sin truncar, mientras que los límites de bytes y de entrada los aplican los proveedores integrados y siguen siendo responsabilidad del controlador registrado en las lecturas personalizadas

La actualización de la hoja valida todos los valores de resultado y restaura las celdas y los metadatos de consulta o tabla tras una cancelación o errores de la aplicación; los proveedores personalizados siguen siendo responsables de respetar sus propios límites de operaciones externas

Enlaces nativos de resultados XLSX

Las consultas de bases de datos respaldadas por tablas usan la relación tabla-a-tabla de consulta, IDs de campo coherentes, identidades de columna y un nombre local de destino oculto; los destinos Text y Web admitidos independientes conservan su rango de resultados

TXLSXTable.ColumnUniqueNames[Index]: WideString expone identidades nativas de columna basadas en cero, preservándolas durante la asignación, la copia y la reapertura junto con ColumnQueryTableFieldIds

Una conexión Text heredada enlazada directamente como tabla externa no es una forma de exportación nativa admitida y el guardado la rechaza antes de la salida; los valores de texto actualizados explícitamente pueden poblar una tabla ordinaria, o un controlador de texto ADO/ODBC instalado puede proporcionar una consulta nativa de base de datos respaldada por tabla

Las relaciones importadas no relacionadas o no admitidas y el XML de extensión permanecen preservados; esta función no convierte grafos externos opacos en consultas actualizables admitidas

Consulte las APIs de conexión y de consulta transaccional para conocer la validación de destinos, las devoluciones de llamada de progreso y el modelo de metadatos circundante