자동 쿼리 공급자

버전 2.384.99부터 Windows의 XLSX 통합 문서 퍼사드를 통해 제공되며, 자동 공급자 선택은 명시적인 쿼리 새로 고침 중에만 일어납니다

기존 쿼리 새로 고침

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는 lxQueryProviders의 통합 문서 소유 dispatcher를 노출합니다. dispatcher를 직접 해제하지 마세요

TXLSXWorksheet.RefreshQueryTable(const AName: WideString; AMaxRows: Integer = 1000000; AOnProgress: TXLSQueryRefreshProgress = nil): Integer와 0 기반 AIndex를 받는 오버로드는 기존 쿼리를 선택해 이 dispatcher를 사용합니다

명시적인 TXLSQueryTableProvider를 받는 기존 오버로드는 공급자가 없을 때 거부하는 기존 동작을 포함해 해당 공급자를 계속 직접 사용하며, 자동 디스패치로 폴백하지 않습니다

새로 고침은 성공 시 1, 취소 시 0, 실패 시 -1을 반환하고 xlsOperationRefresh 아래의 진단 코드 1401과 1400이 붙습니다. 기존의 트랜잭션 방식 결과 적용, 스키마 검증, 리터럴 문자열, 서식 동작은 그대로 유지됩니다

이 진단의 이름은 xlsDiagnosticQueryRefreshCancelled와 xlsDiagnosticQueryRefreshFailed입니다. 상태 변환 전에 통합 문서 쓰기 가드를 먼저 확보하므로, 읽기 전용 뷰가 고정되었거나 쓰기 가드가 거부하면 예외가 발생합니다

통합 문서를 열거나 저장할 때 연결 데이터를 가져오거나 쿼리를 평가하거나 보존된 RefreshOnLoad 메타데이터에 작업하는 일은 절대 없습니다. 결과를 저장하기 전에 필요한 각 쿼리를 명시적으로 새로 고치세요

지원되는 내장 공급자

• xlckText는 엄격한 UTF-8, UTF-16LE, UTF-16BE, Windows-1252, Latin-1 디코딩으로 로컬 구분 기호 텍스트와 고정폭 텍스트를 읽고, 구성 가능한 시작 행과 여섯 가지 날짜 순서, 건너뛰기 필드 등 지원되는 필드 타입을 다룹니다. 구분 기호 입력은 따옴표로 묶인 여러 줄 레코드도 지원합니다
• xlckAdo, xlckOleDb, xlckOdbc는 설치된 Windows ADO와 데이터베이스 드라이버를 읽기 전용 연결 및 레코드셋으로 사용합니다. CommandType = 2는 SQL 텍스트를, CommandType = 3은 테이블 명령을 선택합니다
• xlckWeb은 Windows WinHTTP로 익명 HTTP 또는 HTTPS GET을 수행해, 양의 인덱스나 이름으로 고른 비어 있지 않은 사각형 HTML 테이블 하나를 가져옵니다. 지원되는 응답 문자셋은 UTF-8, UTF-16, Windows-1252, Latin-1입니다

BaseDirectory는 상대 경로인 로컬 텍스트 경로의 기준으로만 쓰입니다. 데이터베이스 연결 문자열과 Web URL은 여전히 명시적인 연결 메타데이터입니다

텍스트 인코딩을 지정하지 않으면 지원되는 BOM(byte order mark)이 인코딩을 알려주는 경우가 아니라 ASCII 전용 입력만 받습니다. non-ASCII 입력에는 지원되는 인코딩이나 BOM을 명시해야 합니다

구분 기호 Text 연결에서는 TextPrompt = False, TextDelimited = True로 두고 연속된 구분 기호를 묶지 않는 정확히 하나의 구분 기호를 지정합니다. 새로 만든 연결은 기본으로 프롬프트와 탭 구분 기호를 쓰므로, 다른 구분 기호를 고른다면 TextTab을 해제하세요

고정폭 텍스트

TextPrompt = False와 TextDelimited = False로 설정한 뒤, 0부터 시작해 0 기반 Position이 엄격하게 증가하는 순서로 TextFields를 추가합니다. 각 필드는 다음 위치나 물리적 레코드 종결자에서 끝나며, xltiftSkip 필드는 결과에서 제외됩니다

위치는 입력 바이트가 아니라 디코딩된 UTF-16 코드 단위로 셉니다. 서러게이트 쌍을 가르는 경계는 거부되며, CRLF, LF, CR은 구분 기호와 한정자 설정과 무관하게 레코드를 종결합니다

필드 패딩은 명시적으로 타입이 지정된 텍스트를 포함해 변환 전에 잘려 나가며, 이는 검증된 네이티브 고정폭 가져오기 동작과 일치합니다. 필드 안의 따옴표, 탭, 구분 기호 문자는 리터럴 입력으로 남고, 짧은 레코드는 선언된 스키마를 바꾸지 않은 채 빈 뒤쪽 필드를 채웁니다

TextFields가 없으면 각 레코드는 하나의 general 필드가 됩니다. TextFirstRow는 첫 스키마 레코드를 고르고, Query.Headers는 그 레코드의 값을 건너뛰며, 명시적인 빈 레코드도 행으로 남습니다

기존의 행, 입력 바이트, 결과 셀, 32767 코드 단위 필드 한도가 그대로 적용됩니다. 잘못된 메타데이터, 변환 실패, 과도한 입력은 트랜잭션 방식 워크시트 갱신 전에 스테이징 데이터를 지우고, 취소 시에는 이전 결과 셀이 보존됩니다

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

Web 연결에서는 WebHtmlTables = True와 WebHtmlFormat = 'none'으로 둡니다. 지원되는 요청은 내장 자격 증명, 프래그먼트, 인증, 리다이렉트를 거부합니다

내장 공급자는 각 연결 종류에서 지원되지 않는 메타데이터를 거부합니다. 데이터베이스 새로 고침은 OLAP·서버 명령, 연결 파일 간접 참조, 저장된 암호, 자격 증명 프롬프트를 거부하고, Text 새로 고침은 파일 프롬프트를 거부하며, Web 새로 고침은 익명 테이블 메타데이터를 요구합니다

타입이 지정된 데이터베이스 매개변수

SQL 텍스트 명령은 Connection.Parameters 순서대로 ADO Command에 바인딩되는 위치 기반 ? 마커를 지원합니다. 매개변수 값이 SQL 텍스트를 대체하는 일은 없고, 이름은 위치 순서를 바꾸지 않으면서 바인딩에 레이블을 붙입니다

프리플라이트는 작은따옴표 문자열, 큰따옴표·백틱 식별자, 대괄호 식별자, 행 주석, 중첩 블록 주석 바깥의 마커를 셉니다. 겹친 따옴표·대괄호 이스케이프도 포함됩니다. 짝이 맞지 않는 따옴표나 주석, 마커 개수 불일치는 연결을 열기 전에 거부됩니다

ParameterType = 'value'에 명시적인 ValueKind(xlcpvInteger, xlcpvDouble, xlcpvBoolean, xlcpvString)와 대응하는 값 프로퍼티를 함께 씁니다. 0, False, 빈 문자열도 값이고, xlcpvNone은 실행 중 값을 추론하지 않습니다

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

ParameterType = 'cell', ValueKind = xlcpvCell, CellReference는 Inputs!$A$1이나 'Sales Input'!B2처럼 시트가 완전히 한정된 로컬 워크시트 참조에 사용합니다. 따옴표로 묶인 시트 이름은 어포스트로피를 겹쳐 쓰고, 범위, 외부 통합 문서, 이름, 시트 한정이 없는 셀 참조는 거부됩니다

워크시트 새로 고침은 재계산이나 압축 셀 구체화 없이 저장된 스칼라 값과 사용 가능한 수식 캐시의 스냅샷을 만듭니다. 수식 캐시가 없거나 오류 셀이면 거부되고, 없거나 빈 셀은 명시적인 지원 SQL 타입이 있을 때만 SQL null을 공급합니다

셀 스냅샷은 Variant 타입을 그대로 유지하므로 부호 있는 Int64, Currency, 타입이 지정된 날짜, null 입력을 영속되는 32비트 정수나 Double 리터럴 필드로 축소하지 않고 다룹니다. 직접 저장된 date, null, Int64 리터럴은 네이티브 매개변수 메타데이터 모델의 범위 밖이므로, 이런 값에는 타입이 지정된 셀 바인딩을 사용하세요

SqlType은 ODBC SQL 타입 코드를 사용하며 ADO 타입으로 명시적으로 매핑됩니다. ADO DataTypeEnum 값이 아닙니다

지원되는 명시적 타입은 SQL null도 받습니다. 배열, 참조 Variant, 오류, non-finite 숫자, 지원되지 않는 SQL 타입, 정수 정밀도를 잃는 변환은 거부되며, NUMERIC이나 DECIMAL에는 이 바인딩 API가 제공하지 않는 precision·scale 메타데이터가 필요합니다

ADO는 타입이 지정된 값과 선언된 크기를 받으며, 빈 텍스트에도 최소 한 코드 단위가 할당됩니다. SQL 방언, 지원되는 매개변수 타입, 결과 변환은 네이티브 드라이버의 책임이므로, 설치된 공급자가 유효한 바인딩을 거부하거나 숫자·날짜 능력이 더 좁을 수 있습니다

Jet과 ACE는 검증된 DATE, TIME, TIMESTAMP 값에 타입이 지정된 OLE DATE 바인딩을 써서 로캘 의존적인 타임스탬프 텍스트 투영과 무관하게 날짜와 시간을 보존합니다. DATE·TIME 검증 규칙은 그대로 적용되고, null 투영 능력은 공급자마다 다릅니다

매개변수에는 SQL 텍스트 명령이 필요하고 페치당 1024개, 이름당 255 코드 단위, 텍스트 값당 32767 코드 단위로 제한됩니다. 명령 텍스트, 매개변수 참조, 이름, 페이로드도 입력 바이트 예산을 소비합니다

프롬프트와 알 수 없는 매개변수 확장 속성은 거부됩니다. RefreshOnChange는 보존되는 메타데이터일 뿐 백그라운드 새로 고침을 유발하지 않고, 열기나 저장이 셀을 해결하거나 명령을 실행하지도 않습니다

직접 Fetch는 리터럴을 지원합니다. FetchWithCellResolver(Connection, Query, MaxRows, out Data, var Abort, AResolver)는 셀 값용 TXLSQueryParameterCellResolver 콜백을 받으며, 이 콜백의 Boolean 결과는 저장된 값을 쓸 수 있는지를 나타냅니다

콜백은 해당 호출에만 스코프가 있고 보존되지 않습니다. 자동 워크시트 새로 고침은 자체 로컬 resolver를 공급하고, 등록된 커스텀 공급자는 여전히 우선하며 자체 매개변수 시맨틱을 소유합니다

Web 새로 고침은 spanning 셀, 중첩된 선택 테이블, 스크립트 기반 콘텐츠가 없는 평범한 text/html 테이블을 지원합니다. 지원되지 않는 레이아웃과 엔티티는 부분 데이터를 만들지 않고 거부됩니다

커스텀 공급자 등록

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

TXLSQueryProviderDispatcher.Create는 직접 사용할 수 있도록 독립적으로 소유되는 dispatcher를 생성합니다. 통합 문서는 자체 인스턴스를 만들고 소유합니다

RegisterProvider(AKind: TXLSConnectionKind; AProvider: TXLSQueryTableProvider)는 선언된 연결 종류에 빌려 쓰는 핸들러를 설치하고 nil은 등록을 해제합니다. 핸들러는 등록 기간보다 오래 살아 있어야 합니다

등록된 핸들러는 내장 공급자보다 우선하며 애플리케이션 고유의 인증이나 연결 종류를 지원할 수 있습니다. 페치 중에는 등록 변경, 구성 변경, 재귀 디스패치가 거부되고, 잘못된 enum 값은 배열 접근 전에 거부됩니다

Fetch(Connection, Query, MaxRows, out Data, var Abort)는 워크시트 새로 고침 중 분리된 메타데이터를 받고 사각형 TXLSQueryResultData를 반환합니다. 취소나 예외는 전파되기 전에 스테이징된 결과를 지웁니다

리소스 한도

MaxInputBytes는 기본값 67108864바이트로 Text·Web 입력과 지원되는 데이터베이스 결과 페이로드를 제한하고, MaxResultCells는 기본값 2000000 셀로 사각형 결과를 제한합니다

TimeoutSeconds는 기본값 30으로 지원되는 네이티브 데이터베이스·HTTP 단계를 구성합니다. 전체 작업이나 커스텀 공급자에 대한 보장된 데드라인은 아닙니다

세 설정과 MaxRows는 모두 양수여야 하고 타임아웃은 네이티브 밀리초 정수에 들어가야 합니다. dispatcher는 초과한 행, 열, 셀을 잘라내지 않고 거부하며, 바이트·입력 한도는 내장 공급자가 집행하고 커스텀 페치에서는 등록된 핸들러의 책임으로 남습니다

워크시트 새로 고침은 모든 결과 값을 검증하고 취소나 애플리케이션 오류 뒤에 셀과 쿼리·테이블 메타데이터를 복원합니다. 커스텀 공급자는 자체 외부 작업 한도를 지키는 일을 계속 책임집니다

네이티브 XLSX 결과 바인딩

테이블 기반 데이터베이스 쿼리는 테이블↔쿼리 테이블 관계, 일관된 필드 ID, 열 식별자, 숨은 로컬 대상 이름을 사용합니다. 독립형으로 지원되는 Text·Web 대상은 결과 범위를 그대로 유지합니다

TXLSXTable.ColumnUniqueNames[Index]: WideString은 0 기반 네이티브 열 식별자를 노출하며, ColumnQueryTableFieldIds와 함께 대입, 복사, 다시 열기 과정에서 보존됩니다

외부 테이블로 직접 바인딩된 레거시 Text 연결은 지원되는 네이티브 내보내기 형태가 아니어서 저장 시 출력 전에 거부됩니다. 명시적으로 새로 고친 텍스트 값으로 일반 테이블을 채우거나, 설치된 ADO/ODBC 텍스트 드라이버로 네이티브 테이블 기반 데이터베이스 쿼리를 제공할 수 있습니다

관련 없거나 지원되지 않는 가져온 관계와 확장 XML은 그대로 보존됩니다. 이 기능이 불투명한 외부 그래프를 지원되는 새로 고침 가능 쿼리로 바꾸지는 않습니다

대상 검증, 진행 콜백, 주변 메타데이터 모델은 연결 및 트랜잭션 쿼리 API를 참조하세요