Proveedores de consulta automáticos

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

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 distribuidor propiedad del libro a partir de lxQueryProviders; no liberes el distribuidor

TXLSXWorksheet.RefreshQueryTable(const AName: WideString; AMaxRows: Integer = 1000000; AOnProgress: TXLSQueryRefreshProgress = nil): Integer y la sobrecarga que acepta un AIndex de base cero seleccionan una consulta existente y usan este distribuidor

Las sobrecargas existentes que aceptan un TXLSQueryTableProvider explícito siguen usando ese proveedor directamente, incluido su rechazo actual de un proveedor ausente; no recurren a la distribución automática

La actualización devuelve 1 si tiene éxito, 0 si se cancela o -1 si falla, con los códigos de diagnóstico 1401 y 1400 bajo xlsOperationRefresh; la aplicación transaccional de resultados existente, la validación de esquema, el comportamiento de cadenas literales y el formato 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 inmovilizada u otro rechazo del guardián de escritura lanza una excepción

Abrir y guardar un libro nunca recupera datos de conexión, evalúa consultas ni actúa sobre los metadatos RefreshOnLoad retenidos; actualiza explícitamente cada consulta necesaria 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 los controladores ADO y de bases de datos instalados en Windows con conexiones y conjuntos de registros 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 conjuntos de caracteres de respuesta admitidos son UTF-8, UTF-16, Windows-1252 y Latin-1

BaseDirectory aporta la base solo para las rutas locales de texto relativas; las cadenas de conexión de base 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 exige una codificación admitida explícita o una marca de orden de bytes

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

Texto de ancho fijo

Establece TextPrompt = False y TextDelimited = False, y añade TextFields en orden estrictamente creciente de Position de base cero, empezando en cero; cada campo termina en la siguiente posición o en el terminador físico de 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 parta un surrogate pair provoca el rechazo, y CRLF, LF y CR terminan registros con independencia de la configuración de delimitador y calificador

El relleno de los campos se recorta antes de la conversión, incluido el texto con tipo explícito, igualando el comportamiento nativo verificado de importación 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 cambiar 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 no válidos, los fallos de conversión o la entrada excesiva limpian los datos preparados antes de la actualización transaccional de la hoja, y la cancelación conserva 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, establece WebHtmlTables = True y WebHtmlFormat = 'none'; las peticiones admitidas rechazan credenciales incrustadas, fragmentos, autenticación y redirecciones

Los proveedores integrados rechazan los metadatos no admitidos en sus tipos de conexión respectivos; la actualización de base de datos rechaza comandos OLAP o de servidor, direccionamiento indirecto mediante archivos de conexión, contraseñas almacenadas y peticiones de credenciales, la actualización Text rechaza las 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ámetro nunca reemplazan el texto SQL, y los nombres etiquetan las vinculaciones sin cambiar el orden posicional

La comprobación previa cuenta los marcadores fuera de cadenas entre comillas simples, identificadores entre comillas dobles o backticks, identificadores entre corchetes, comentarios de línea y comentarios de bloque anidados, incluidos los escapes dobles de comilla o corchete; las comillas o comentarios sin cerrar y los desajustes en el número de marcadores se rechazan antes de abrir una conexión

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

Usa ParameterType = 'cell', ValueKind = xlcpvCell y CellReference para una referencia de hoja local plenamente calificada como Inputs!$A$1 o 'Sales Input'!B2; los nombres de hoja entre comillas usan apóstrofos dobles, y los rangos, libros externos, nombres y referencias de celda sin calificar se rechazan

La actualización de la hoja toma instantáneas 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 se rechazan, 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 de entero de 32 bits o Double persistidos; los literales de fecha, null e Int64 almacenados directamente quedan fuera del modelo nativo de metadatos de parámetros, así que usa vinculaciones 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 ADO DataTypeEnum

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 se rechazan, y NUMERIC o DECIMAL exigen metadatos de precisión y escala que esta API de vinculación no proporciona

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

Jet y ACE usan vinculaciones OLE DATE con tipo para valores DATE, TIME y TIMESTAMP validados, preservando 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 DATE y TIME siguen aplicando, y las capacidades de proyección de null siguen siendo específicas del 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ámetro, los nombres y las cargas también consumen el presupuesto de bytes de entrada

Las peticiones de preguntar y los atributos de extensión de parámetro desconocidos se rechazan; RefreshOnChange sigue siendo metadatos retenidos y no dispara 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 un callback TXLSQueryParameterCellResolver para valores de celda, cuyo resultado Boolean indica si hay un valor almacenado disponible

El callback tiene el alcance de la llamada y no se retiene; la actualización automática de la hoja aporta su resolver local, y los proveedores personalizados registrados siguen teniendo prioridad y poseen su propia semántica de parámetros

La actualización Web admite tablas text/html simples sin celdas de expansión, tablas seleccionadas anidadas ni contenido controlado por scripts; los diseños y entidades no admitidos se rechazan 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 distribuidor de propiedad independiente para uso directo; el libro crea y posee su propia instancia

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

Un manejador registrado tiene prioridad sobre el proveedor integrado y puede admitir autenticación o tipos de conexión específicos de la aplicación; los cambios de registro, los cambios de configuración y la distribución recursiva se rechazan durante la lectura, y los valores de enum no válidos se rechazan antes de acceder a la matriz

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

Límites de recursos

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

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

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

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

Vinculaciones nativas de resultados XLSX

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

TXLSXTable.ColumnUniqueNames[Index]: WideString expone identidades de columna nativas de base cero, conservá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 aportar una consulta nativa de base de datos respaldada por tabla

Las relaciones importadas no relacionadas o no admitidas y el XML de extensión siguen preservándose; esta característica no convierte grafos externos opacos en consultas actualizables admitidas

Consulta las API de conexión y consulta transaccional para la validación de destinos, los callbacks de progreso y el modelo de metadatos circundante